X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=5945becc8401b44ed85c9bed370828d6f0fa87ce;hb=ff23347e9ef93e40f6bc9f2bc2656893b6259bf4;hp=397f52b0294005a64baf1c3a8984c10c4bb34dce;hpb=b851fbc1add6c3d9fa6158884279133c311a3efc;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 397f52b..5945bec 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -17,6 +17,85 @@ unadorned names, but this support may be disabled in a future release. The listing is alphabetical, case insensitive. + +=head1 "Gimme" Values + +=over 8 + +=item GIMME + +A backward-compatible version of C which can only return +C or C; in a void context, it returns C. +Deprecated. Use C instead. + + U32 GIMME + +=for hackers +Found in file op.h + +=item GIMME_V + +The XSUB-writer's equivalent to Perl's C. Returns C, +C or C for void, scalar or list context, +respectively. + + U32 GIMME_V + +=for hackers +Found in file op.h + +=item G_ARRAY + +Used to indicate list context. See C, C and +L. + +=for hackers +Found in file cop.h + +=item G_DISCARD + +Indicates that arguments returned from a callback should be discarded. See +L. + +=for hackers +Found in file cop.h + +=item G_EVAL + +Used to force a Perl C wrapper around a callback. See +L. + +=for hackers +Found in file cop.h + +=item G_NOARGS + +Indicates that no arguments are being sent to a callback. See +L. + +=for hackers +Found in file cop.h + +=item G_SCALAR + +Used to indicate scalar context. See C, C, and +L. + +=for hackers +Found in file cop.h + +=item G_VOID + +Used to indicate void context. See C and L. + +=for hackers +Found in file cop.h + + +=back + +=head1 Array Manipulation Functions + =over 8 =item AvFILL @@ -182,47 +261,55 @@ must then use C to assign values to these new elements. =for hackers Found in file av.c -=item ax +=item get_av -Variable which is setup by C to indicate the stack base offset, -used by the C, C and C macros. The C macro -must be called prior to setup the C variable. +Returns the AV of the specified Perl array. If C is set and the +Perl variable does not exist then it will be created. If C is not +set and the variable does not exist then NULL is returned. - I32 ax +NOTE: the perl_ form of this function is deprecated. + + AV* get_av(const char* name, I32 create) =for hackers -Found in file XSUB.h +Found in file perl.c -=item bytes_from_utf8 +=item newAV -Converts a string C of length C from UTF8 into byte encoding. -Unlike but like C, returns a pointer to -the newly-created string, and updates C to contain the new -length. Returns the original string if no conversion occurs, C -is unchanged. Do nothing if C points to 0. Sets C to -0 if C is converted or contains all 7bit characters. +Creates a new AV. The reference count is set to 1. -NOTE: this function is experimental and may change or be -removed without notice. + AV* newAV() + +=for hackers +Found in file av.c + +=item Nullav + +Null AV pointer. - U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) =for hackers -Found in file utf8.c +Found in file av.h -=item bytes_to_utf8 +=item sortsv -Converts a string C of length C from ASCII into UTF8 encoding. -Returns a pointer to the newly-created string, and sets C to -reflect the new length. +Sort an array. Here is an example: -NOTE: this function is experimental and may change or be -removed without notice. + sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); - U8* bytes_to_utf8(U8 *s, STRLEN *len) +See lib/sort.pm for details about controlling the sorting algorithm. + + void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) =for hackers -Found in file utf8.c +Found in file pp_sort.c + + +=back + +=head1 Callback Functions + +=over 8 =item call_argv @@ -270,388 +357,438 @@ NOTE: the perl_ form of this function is deprecated. =for hackers Found in file perl.c -=item CLASS +=item ENTER -Variable which is setup by C to indicate the -class name for a C++ XS constructor. This is always a C. See C. +Opening bracket on a callback. See C and L. - char* CLASS + ENTER; =for hackers -Found in file XSUB.h +Found in file scope.h -=item Copy +=item eval_pv -The XSUB-writer's interface to the C C function. The C is the -source, C is the destination, C is the number of items, and C is -the type. May fail on overlapping copies. See also C. +Tells Perl to C the given string and return an SV* result. - void Copy(void* src, void* dest, int nitems, type) +NOTE: the perl_ form of this function is deprecated. -=for hackers -Found in file handy.h + SV* eval_pv(const char* p, I32 croak_on_error) -=item croak +=for hackers +Found in file perl.c -This is the XSUB-writer's interface to Perl's C function. -Normally use this function the same way you use the C C -function. See C. +=item eval_sv -If you want to throw an exception object, assign the object to -C<$@> and then pass C to croak(): +Tells Perl to C the string in the SV. - errsv = get_sv("@", TRUE); - sv_setsv(errsv, exception_object); - croak(Nullch); +NOTE: the perl_ form of this function is deprecated. - void croak(const char* pat, ...) + I32 eval_sv(SV* sv, I32 flags) =for hackers -Found in file util.c +Found in file perl.c -=item CvSTASH +=item FREETMPS -Returns the stash of the CV. +Closing bracket for temporaries on a callback. See C and +L. - HV* CvSTASH(CV* cv) + FREETMPS; =for hackers -Found in file cv.h - -=item cv_const_sv +Found in file scope.h -If C is a constant sub eligible for inlining. returns the constant -value returned by the sub. Otherwise, returns NULL. +=item LEAVE -Constant subs can be created with C or as described in -L. +Closing bracket on a callback. See C and L. - SV* cv_const_sv(CV* cv) + LEAVE; =for hackers -Found in file op.c +Found in file scope.h -=item dAX +=item SAVETMPS -Sets up the C variable. -This is usually handled automatically by C by calling C. +Opening bracket for temporaries on a callback. See C and +L. - dAX; + SAVETMPS; =for hackers -Found in file XSUB.h +Found in file scope.h -=item dITEMS -Sets up the C variable. -This is usually handled automatically by C by calling C. +=back - dITEMS; +=head1 Character classes -=for hackers -Found in file XSUB.h +=over 8 -=item dMARK +=item isALNUM -Declare a stack marker variable, C, for the XSUB. See C and -C. +Returns a boolean indicating whether the C C is an ASCII alphanumeric +character (including underscore) or digit. - dMARK; + bool isALNUM(char ch) =for hackers -Found in file pp.h +Found in file handy.h -=item dORIGMARK +=item isALPHA -Saves the original stack mark for the XSUB. See C. +Returns a boolean indicating whether the C C is an ASCII alphabetic +character. - dORIGMARK; + bool isALPHA(char ch) =for hackers -Found in file pp.h +Found in file handy.h -=item dSP +=item isDIGIT -Declares a local copy of perl's stack pointer for the XSUB, available via -the C macro. See C. +Returns a boolean indicating whether the C C is an ASCII +digit. - dSP; + bool isDIGIT(char ch) =for hackers -Found in file pp.h +Found in file handy.h -=item dXSARGS +=item isLOWER -Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. -Sets up the C and C variables by calling C and C. -This is usually handled automatically by C. +Returns a boolean indicating whether the C C is a lowercase +character. - dXSARGS; + bool isLOWER(char ch) =for hackers -Found in file XSUB.h +Found in file handy.h -=item dXSI32 +=item isSPACE -Sets up the C variable for an XSUB which has aliases. This is usually -handled automatically by C. +Returns a boolean indicating whether the C C is whitespace. - dXSI32; + bool isSPACE(char ch) =for hackers -Found in file XSUB.h +Found in file handy.h -=item ENTER +=item isUPPER -Opening bracket on a callback. See C and L. +Returns a boolean indicating whether the C C is an uppercase +character. - ENTER; + bool isUPPER(char ch) =for hackers -Found in file scope.h +Found in file handy.h -=item eval_pv +=item toLOWER -Tells Perl to C the given string and return an SV* result. +Converts the specified character to lowercase. -NOTE: the perl_ form of this function is deprecated. + char toLOWER(char ch) - SV* eval_pv(const char* p, I32 croak_on_error) +=for hackers +Found in file handy.h + +=item toUPPER + +Converts the specified character to uppercase. + + char toUPPER(char ch) =for hackers -Found in file perl.c +Found in file handy.h -=item eval_sv -Tells Perl to C the string in the SV. +=back + +=head1 Cloning an interpreter + +=over 8 + +=item perl_clone + +Create and return a new interpreter by cloning the current one. + +perl_clone takes these flags as paramters: + +CLONEf_COPY_STACKS - is used to, well, copy the stacks also, +without it we only clone the data and zero the stacks, +with it we copy the stacks and the new perl interpreter is +ready to run at the exact same point as the previous one. +The pseudo-fork code uses COPY_STACKS while the +threads->new doesn't. + +CLONEf_KEEP_PTR_TABLE +perl_clone keeps a ptr_table with the pointer of the old +variable as a key and the new variable as a value, +this allows it to check if something has been cloned and not +clone it again but rather just use the value and increase the +refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill +the ptr_table using the function +C, +reason to keep it around is if you want to dup some of your own +variable who are outside the graph perl scans, example of this +code is in threads.xs create + +CLONEf_CLONE_HOST +This is a win32 thing, it is ignored on unix, it tells perls +win32host code (which is c++) to clone itself, this is needed on +win32 if you want to run two threads at the same time, +if you just want to do some stuff in a separate perl interpreter +and then throw it away and return to the original one, +you don't need to do anything. + + PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) + +=for hackers +Found in file sv.c + + +=back + +=head1 CV Manipulation Functions + +=over 8 + +=item CvSTASH + +Returns the stash of the CV. + + HV* CvSTASH(CV* cv) + +=for hackers +Found in file cv.h + +=item get_cv + +Returns the CV of the specified Perl subroutine. If C is set and +the Perl subroutine does not exist then it will be declared (which has the +same effect as saying C). If C is not set and the +subroutine does not exist then NULL is returned. NOTE: the perl_ form of this function is deprecated. - I32 eval_sv(SV* sv, I32 flags) + CV* get_cv(const char* name, I32 create) =for hackers Found in file perl.c -=item EXTEND +=item Nullcv -Used to extend the argument stack for an XSUB's return values. Once -used, guarantees that there is room for at least C to be pushed -onto the stack. +Null CV pointer. - void EXTEND(SP, int nitems) =for hackers -Found in file pp.h +Found in file cv.h -=item fbm_compile -Analyses the string in order to make fast searches on it using fbm_instr() --- the Boyer-Moore algorithm. +=back - void fbm_compile(SV* sv, U32 flags) +=head1 Embedding Functions -=for hackers -Found in file util.c +=over 8 -=item fbm_instr +=item cv_undef -Returns the location of the SV in the string delimited by C and -C. It returns C if the string can't be found. The C -does not have to be fbm_compiled, but the search will not be as fast -then. +Clear out all the active components of a CV. This can happen either +by an explicit C, or by the reference count going to zero. +In the former case, we keep the CvOUTSIDE pointer, so that any anonymous +children can still follow the full lexical scope chain. - char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) + void cv_undef(CV* cv) =for hackers -Found in file util.c +Found in file op.c -=item FREETMPS +=item load_module -Closing bracket for temporaries on a callback. See C and -L. +Loads the module whose name is pointed to by the string part of name. +Note that the actual module name, not its filename, should be given. +Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of +PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS +(or 0 for no flags). ver, if specified, provides version semantics +similar to C. The optional trailing SV* +arguments can be used to specify arguments to the module's import() +method, similar to C. - FREETMPS; + void load_module(U32 flags, SV* name, SV* ver, ...) =for hackers -Found in file scope.h +Found in file op.c -=item getcwd_sv +=item nothreadhook -Fill the sv with current working directory +Stub that provides thread hook for perl_destruct when there are +no threads. - int getcwd_sv(SV* sv) + int nothreadhook() =for hackers -Found in file util.c +Found in file perl.c -=item get_av +=item perl_alloc -Returns the AV of the specified Perl array. If C is set and the -Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then NULL is returned. +Allocates a new Perl interpreter. See L. -NOTE: the perl_ form of this function is deprecated. + PerlInterpreter* perl_alloc() - AV* get_av(const char* name, I32 create) +=for hackers +Found in file perl.c + +=item perl_construct + +Initializes a new Perl interpreter. See L. + + void perl_construct(PerlInterpreter* interp) =for hackers Found in file perl.c -=item get_cv +=item perl_destruct -Returns the CV of the specified Perl subroutine. If C is set and -the Perl subroutine does not exist then it will be declared (which has the -same effect as saying C). If C is not set and the -subroutine does not exist then NULL is returned. +Shuts down a Perl interpreter. See L. -NOTE: the perl_ form of this function is deprecated. + int perl_destruct(PerlInterpreter* interp) - CV* get_cv(const char* name, I32 create) +=for hackers +Found in file perl.c + +=item perl_free + +Releases a Perl interpreter. See L. + + void perl_free(PerlInterpreter* interp) =for hackers Found in file perl.c -=item get_hv +=item perl_parse -Returns the HV of the specified Perl hash. If C is set and the -Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then NULL is returned. +Tells a Perl interpreter to parse a Perl script. See L. -NOTE: the perl_ form of this function is deprecated. + int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) - HV* get_hv(const char* name, I32 create) +=for hackers +Found in file perl.c + +=item perl_run + +Tells a Perl interpreter to run. See L. + + int perl_run(PerlInterpreter* interp) =for hackers Found in file perl.c -=item get_sv +=item require_pv -Returns the SV of the specified Perl scalar. If C is set and the -Perl variable does not exist then it will be created. If C is not -set and the variable does not exist then NULL is returned. +Tells Perl to C the file named by the string argument. It is +analogous to the Perl code C. It's even +implemented that way; consider using Perl_load_module instead. NOTE: the perl_ form of this function is deprecated. - SV* get_sv(const char* name, I32 create) + void require_pv(const char* pv) =for hackers Found in file perl.c -=item GIMME -A backward-compatible version of C which can only return -C or C; in a void context, it returns C. -Deprecated. Use C instead. +=back - U32 GIMME +=head1 Functions in file pp_pack.c -=for hackers -Found in file op.h -=item GIMME_V +=over 8 -The XSUB-writer's equivalent to Perl's C. Returns C, -C or C for void, scalar or list context, -respectively. +=item pack_cat - U32 GIMME_V +The engine implementing pack() Perl function. + + void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) =for hackers -Found in file op.h +Found in file pp_pack.c -=item grok_bin +=item unpack_str -converts a string representing a binary number to numeric form. +The engine implementing unpack() Perl function. -On entry I and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first invalid character. -On return I<*len> is set to the length scanned string, and I<*flags> gives -output flags. + I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) -If the value is <= UV_MAX it is returned as a UV, the output flags are clear, -and nothing is written to I<*result>. If the value is > UV_MAX C -returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I -is NULL). +=for hackers +Found in file pp_pack.c -The hex number may optionally be prefixed with "0b" or "b" unless -C is set in I<*flags> on entry. If -C is set in I<*flags> then the binary -number may use '_' characters to separate digits. - UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) +=back -=for hackers -Found in file numeric.c +=head1 Global Variables -=item grok_hex +=over 8 -converts a string representing a hex number to numeric form. +=item PL_modglobal -On entry I and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first non-hex-digit character. -On return I<*len> is set to the length scanned string, and I<*flags> gives -output flags. +C is a general purpose, interpreter global HV for use by +extensions that need to keep information on a per-interpreter basis. +In a pinch, it can also be used as a symbol table for extensions +to share data among each other. It is a good idea to use keys +prefixed by the package name of the extension that owns the data. -If the value is <= UV_MAX it is returned as a UV, the output flags are clear, -and nothing is written to I<*result>. If the value is > UV_MAX C -returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I -is NULL). + HV* PL_modglobal -The hex number may optionally be prefixed with "0x" or "x" unless -C is set in I<*flags> on entry. If -C is set in I<*flags> then the hex -number may use '_' characters to separate digits. +=for hackers +Found in file intrpvar.h - UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) +=item PL_na -=for hackers -Found in file numeric.c +A convenience variable which is typically used with C when one +doesn't care about the length of the string. It is usually more efficient +to either declare a local variable and use that instead or to use the +C macro. -=item grok_number + STRLEN PL_na -Recognise (or not) a number. The type of the number is returned -(0 if unrecognised), otherwise it is a bit-ORed combination of -IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, -IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h). +=for hackers +Found in file thrdvar.h -If the value of the number can fit an in UV, it is returned in the *valuep -IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV -will never be set unless *valuep is valid, but *valuep may have been assigned -to during processing even though IS_NUMBER_IN_UV is not set on return. -If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when -valuep is non-NULL, but no actual assignment (or SEGV) will occur. +=item PL_sv_no -IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were -seen (in which case *valuep gives the true value truncated to an integer), and -IS_NUMBER_NEG if the number is negative (in which case *valuep holds the -absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the -number is larger than a UV. +This is the C SV. See C. Always refer to this as +C<&PL_sv_no>. - int grok_number(const char *pv, STRLEN len, UV *valuep) + SV PL_sv_no =for hackers -Found in file numeric.c +Found in file intrpvar.h -=item grok_numeric_radix +=item PL_sv_undef -Scan and skip for a numeric decimal separator (radix). +This is the C SV. Always refer to this as C<&PL_sv_undef>. - bool grok_numeric_radix(const char **sp, const char *send) + SV PL_sv_undef =for hackers -Found in file numeric.c +Found in file intrpvar.h -=item grok_oct +=item PL_sv_yes +This is the C SV. See C. Always refer to this as +C<&PL_sv_yes>. - UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) + SV PL_sv_yes =for hackers -Found in file numeric.c +Found in file intrpvar.h + + +=back + +=head1 GV Functions + +=over 8 =item GvSV @@ -722,6 +859,20 @@ C apply equally to these functions. =for hackers Found in file gv.c +=item gv_fetchmeth_autoload + +Same as gv_fetchmeth(), but looks for autoloaded subroutines too. +Returns a glob for the subroutine. + +For an autoloaded subroutine without a GV, will create a GV even +if C. For an autoloaded subroutine without a stub, GvCV() +of the result may be zero. + + GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) + +=for hackers +Found in file gv.c + =item gv_stashpv Returns a pointer to the stash for a specified package. C should @@ -744,61 +895,55 @@ valid UTF-8 string. See C. =for hackers Found in file gv.c -=item G_ARRAY -Used to indicate list context. See C, C and -L. +=back -=for hackers -Found in file cop.h +=head1 Handy Values -=item G_DISCARD +=over 8 + +=item HEf_SVKEY + +This flag, used in the length slot of hash entries and magic structures, +specifies the structure contains an C pointer where a C pointer +is to be expected. (For information only--not to be used). -Indicates that arguments returned from a callback should be discarded. See -L. =for hackers -Found in file cop.h - -=item G_EVAL +Found in file hv.h -Used to force a Perl C wrapper around a callback. See -L. +=item Nullch +Null character pointer. =for hackers -Found in file cop.h +Found in file handy.h -=item G_NOARGS +=item Nullsv -Indicates that no arguments are being sent to a callback. See -L. +Null SV pointer. =for hackers -Found in file cop.h +Found in file handy.h -=item G_SCALAR -Used to indicate scalar context. See C, C, and -L. +=back -=for hackers -Found in file cop.h +=head1 Hash Manipulation Functions -=item G_VOID +=over 8 -Used to indicate void context. See C and L. +=item get_hv -=for hackers -Found in file cop.h +Returns the HV of the specified Perl hash. If C is set and the +Perl variable does not exist then it will be created. If C is not +set and the variable does not exist then NULL is returned. -=item HEf_SVKEY +NOTE: the perl_ form of this function is deprecated. -This flag, used in the length slot of hash entries and magic structures, -specifies the structure contains an C pointer where a C pointer -is to be expected. (For information only--not to be used). + HV* get_hv(const char* name, I32 create) =for hackers -Found in file hv.h +Found in file perl.c =item HeHASH @@ -981,568 +1126,813 @@ store it somewhere. See L for more information on how to use this function on tied hashes. - HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash) + HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash) + +=for hackers +Found in file hv.c + +=item hv_iterinit + +Prepares a starting point to traverse a hash table. Returns the number of +keys in the hash (i.e. the same as C). The return value is +currently only meaningful for hashes without tie magic. + +NOTE: Before version 5.004_65, C used to return the number of +hash buckets that happen to be in use. If you still need that esoteric +value, you can get it through the macro C. + + + I32 hv_iterinit(HV* tb) + +=for hackers +Found in file hv.c + +=item hv_iterkey + +Returns the key from the current position of the hash iterator. See +C. + + char* hv_iterkey(HE* entry, I32* retlen) + +=for hackers +Found in file hv.c + +=item hv_iterkeysv + +Returns the key as an C from the current position of the hash +iterator. The return value will always be a mortal copy of the key. Also +see C. + + SV* hv_iterkeysv(HE* entry) + +=for hackers +Found in file hv.c + +=item hv_iternext + +Returns entries from a hash iterator. See C. + +You may call C or C on the hash entry that the +iterator currently points to, without losing your place or invalidating your +iterator. Note that in this case the current entry is deleted from the hash +with your iterator holding the last reference to it. Your iterator is flagged +to free the entry on the next call to C, so you must not discard +your iterator immediately else the entry will leak - call C to +trigger the resource deallocation. + + HE* hv_iternext(HV* tb) + +=for hackers +Found in file hv.c + +=item hv_iternextsv + +Performs an C, C, and C in one +operation. + + SV* hv_iternextsv(HV* hv, char** key, I32* retlen) + +=for hackers +Found in file hv.c + +=item hv_iternext_flags + +Returns entries from a hash iterator. See C and C. +The C value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is +set the placeholders keys (for restricted hashes) will be returned in addition +to normal keys. By default placeholders are automatically skipped over. +Currently a placeholder is implemented with a value that is literally +<&Perl_sv_undef> (a regular C value is a normal read-write SV for which +C is false). Note that the implementation of placeholders and +restricted hashes may change, and the implementation currently is +insufficiently abstracted for any change to be tidy. + +NOTE: this function is experimental and may change or be +removed without notice. + + HE* hv_iternext_flags(HV* tb, I32 flags) + +=for hackers +Found in file hv.c + +=item hv_iterval + +Returns the value from the current position of the hash iterator. See +C. + + SV* hv_iterval(HV* tb, HE* entry) + +=for hackers +Found in file hv.c + +=item hv_magic + +Adds magic to a hash. See C. + + void hv_magic(HV* hv, GV* gv, int how) + +=for hackers +Found in file hv.c + +=item hv_store + +Stores an SV in a hash. The hash key is specified as C and C is +the length of the key. The C parameter is the precomputed hash +value; if it is zero then Perl will compute it. The return value will be +NULL if the operation failed or if the value did not need to be actually +stored within the hash (as in the case of tied hashes). Otherwise it can +be dereferenced to get the original C. Note that the caller is +responsible for suitably incrementing the reference count of C before +the call, and decrementing it if the function returned NULL. Effectively +a successful hv_store takes ownership of one reference to C. This is +usually what you want; a newly created SV has a reference count of one, so +if all your code does is create SVs then store them in a hash, hv_store +will own the only reference to the new SV, and your code doesn't need to do +anything further to tidy up. hv_store is not implemented as a call to +hv_store_ent, and does not create a temporary SV for the key, so if your +key data is not already in SV form then use hv_store in preference to +hv_store_ent. + +See L for more +information on how to use this function on tied hashes. + + SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash) + +=for hackers +Found in file hv.c + +=item hv_store_ent + +Stores C in a hash. The hash key is specified as C. The C +parameter is the precomputed hash value; if it is zero then Perl will +compute it. The return value is the new hash entry so created. It will be +NULL if the operation failed or if the value did not need to be actually +stored within the hash (as in the case of tied hashes). Otherwise the +contents of the return value can be accessed using the C macros +described here. Note that the caller is responsible for suitably +incrementing the reference count of C before the call, and +decrementing it if the function returned NULL. Effectively a successful +hv_store_ent takes ownership of one reference to C. This is +usually what you want; a newly created SV has a reference count of one, so +if all your code does is create SVs then store them in a hash, hv_store +will own the only reference to the new SV, and your code doesn't need to do +anything further to tidy up. Note that hv_store_ent only reads the C; +unlike C it does not take ownership of it, so maintaining the correct +reference count on C is entirely the caller's responsibility. hv_store +is not implemented as a call to hv_store_ent, and does not create a temporary +SV for the key, so if your key data is not already in SV form then use +hv_store in preference to hv_store_ent. + +See L for more +information on how to use this function on tied hashes. + + HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash) + +=for hackers +Found in file hv.c + +=item hv_undef + +Undefines the hash. + + void hv_undef(HV* tb) + +=for hackers +Found in file hv.c + +=item newHV + +Creates a new HV. The reference count is set to 1. + + HV* newHV() + +=for hackers +Found in file hv.c + +=item Nullhv + +Null HV pointer. + + +=for hackers +Found in file hv.h + + +=back + +=head1 Magical Functions + +=over 8 + +=item mg_clear + +Clear something magical that the SV represents. See C. + + int mg_clear(SV* sv) + +=for hackers +Found in file mg.c + +=item mg_copy + +Copies the magic from one SV to another. See C. + + int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) + +=for hackers +Found in file mg.c + +=item mg_find + +Finds the magic pointer for type matching the SV. See C. + + MAGIC* mg_find(SV* sv, int type) + +=for hackers +Found in file mg.c + +=item mg_free + +Free any magic storage used by the SV. See C. + + int mg_free(SV* sv) + +=for hackers +Found in file mg.c + +=item mg_get + +Do magic after a value is retrieved from the SV. See C. + + int mg_get(SV* sv) + +=for hackers +Found in file mg.c + +=item mg_length + +Report on the SV's length. See C. + + U32 mg_length(SV* sv) + +=for hackers +Found in file mg.c + +=item mg_magical + +Turns on the magical status of an SV. See C. + + void mg_magical(SV* sv) =for hackers -Found in file hv.c - -=item hv_iterinit +Found in file mg.c -Prepares a starting point to traverse a hash table. Returns the number of -keys in the hash (i.e. the same as C). The return value is -currently only meaningful for hashes without tie magic. +=item mg_set -NOTE: Before version 5.004_65, C used to return the number of -hash buckets that happen to be in use. If you still need that esoteric -value, you can get it through the macro C. +Do magic after a value is assigned to the SV. See C. - I32 hv_iterinit(HV* tb) + int mg_set(SV* sv) =for hackers -Found in file hv.c +Found in file mg.c -=item hv_iterkey +=item SvGETMAGIC -Returns the key from the current position of the hash iterator. See -C. +Invokes C on an SV if it has 'get' magic. This macro evaluates its +argument more than once. - char* hv_iterkey(HE* entry, I32* retlen) + void SvGETMAGIC(SV* sv) =for hackers -Found in file hv.c +Found in file sv.h -=item hv_iterkeysv +=item SvLOCK -Returns the key as an C from the current position of the hash -iterator. The return value will always be a mortal copy of the key. Also -see C. +Arranges for a mutual exclusion lock to be obtained on sv if a suitable module +has been loaded. - SV* hv_iterkeysv(HE* entry) + void SvLOCK(SV* sv) =for hackers -Found in file hv.c +Found in file sv.h -=item hv_iternext +=item SvSETMAGIC -Returns entries from a hash iterator. See C. +Invokes C on an SV if it has 'set' magic. This macro evaluates its +argument more than once. - HE* hv_iternext(HV* tb) + void SvSETMAGIC(SV* sv) =for hackers -Found in file hv.c +Found in file sv.h -=item hv_iternextsv +=item SvSetMagicSV -Performs an C, C, and C in one -operation. +Like C, but does any set magic required afterwards. - SV* hv_iternextsv(HV* hv, char** key, I32* retlen) + void SvSetMagicSV(SV* dsb, SV* ssv) =for hackers -Found in file hv.c +Found in file sv.h -=item hv_iterval +=item SvSetMagicSV_nosteal -Returns the value from the current position of the hash iterator. See -C. +Like C, but does any set magic required afterwards. - SV* hv_iterval(HV* tb, HE* entry) + void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) =for hackers -Found in file hv.c +Found in file sv.h -=item hv_magic +=item SvSetSV -Adds magic to a hash. See C. +Calls C if dsv is not the same as ssv. May evaluate arguments +more than once. - void hv_magic(HV* hv, GV* gv, int how) + void SvSetSV(SV* dsb, SV* ssv) =for hackers -Found in file hv.c - -=item hv_store +Found in file sv.h -Stores an SV in a hash. The hash key is specified as C and C is -the length of the key. The C parameter is the precomputed hash -value; if it is zero then Perl will compute it. The return value will be -NULL if the operation failed or if the value did not need to be actually -stored within the hash (as in the case of tied hashes). Otherwise it can -be dereferenced to get the original C. Note that the caller is -responsible for suitably incrementing the reference count of C before -the call, and decrementing it if the function returned NULL. +=item SvSetSV_nosteal -See L for more -information on how to use this function on tied hashes. +Calls a non-destructive version of C if dsv is not the same as +ssv. May evaluate arguments more than once. - SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash) + void SvSetSV_nosteal(SV* dsv, SV* ssv) =for hackers -Found in file hv.c - -=item hv_store_ent +Found in file sv.h -Stores C in a hash. The hash key is specified as C. The C -parameter is the precomputed hash value; if it is zero then Perl will -compute it. The return value is the new hash entry so created. It will be -NULL if the operation failed or if the value did not need to be actually -stored within the hash (as in the case of tied hashes). Otherwise the -contents of the return value can be accessed using the C macros -described here. Note that the caller is responsible for suitably -incrementing the reference count of C before the call, and -decrementing it if the function returned NULL. +=item SvSHARE -See L for more -information on how to use this function on tied hashes. +Arranges for sv to be shared between threads if a suitable module +has been loaded. - HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash) + void SvSHARE(SV* sv) =for hackers -Found in file hv.c - -=item hv_undef +Found in file sv.h -Undefines the hash. - void hv_undef(HV* tb) +=back -=for hackers -Found in file hv.c +=head1 Memory Management -=item ibcmp_utf8 +=over 8 -Return true if the strings s1 and s2 differ case-insensitively, false -if not (if they are equal case-insensitively). If u1 is true, the -string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, -the string s2 is assumed to be in UTF-8-encoded Unicode. +=item Copy -For case-insensitiveness, the "casefolding" of Unicode is used -instead of upper/lowercasing both the characters, see -http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). +The XSUB-writer's interface to the C C function. The C is the +source, C is the destination, C is the number of items, and C is +the type. May fail on overlapping copies. See also C. - I32 ibcmp_utf8(const char* a, bool ua, I32 len1, const char* b, bool ub, I32 len2) + void Copy(void* src, void* dest, int nitems, type) =for hackers -Found in file utf8.c +Found in file handy.h -=item isALNUM +=item Move -Returns a boolean indicating whether the C C is an ASCII alphanumeric -character (including underscore) or digit. +The XSUB-writer's interface to the C C function. The C is the +source, C is the destination, C is the number of items, and C is +the type. Can do overlapping moves. See also C. - bool isALNUM(char ch) + void Move(void* src, void* dest, int nitems, type) =for hackers Found in file handy.h -=item isALPHA +=item New -Returns a boolean indicating whether the C C is an ASCII alphabetic -character. +The XSUB-writer's interface to the C C function. - bool isALPHA(char ch) + void New(int id, void* ptr, int nitems, type) =for hackers Found in file handy.h -=item isDIGIT +=item Newc -Returns a boolean indicating whether the C C is an ASCII -digit. +The XSUB-writer's interface to the C C function, with +cast. - bool isDIGIT(char ch) + void Newc(int id, void* ptr, int nitems, type, cast) =for hackers Found in file handy.h -=item isLOWER +=item NEWSV -Returns a boolean indicating whether the C C is a lowercase -character. +Creates a new SV. A non-zero C parameter indicates the number of +bytes of preallocated string space the SV should have. An extra byte for a +tailing NUL is also reserved. (SvPOK is not set for the SV even if string +space is allocated.) The reference count for the new SV is set to 1. +C is an integer id between 0 and 1299 (used to identify leaks). - bool isLOWER(char ch) + + SV* NEWSV(int id, STRLEN len) =for hackers Found in file handy.h -=item isSPACE +=item Newz -Returns a boolean indicating whether the C C is whitespace. +The XSUB-writer's interface to the C C function. The allocated +memory is zeroed with C. - bool isSPACE(char ch) + void Newz(int id, void* ptr, int nitems, type) =for hackers Found in file handy.h -=item isUPPER +=item Poison -Returns a boolean indicating whether the C C is an uppercase -character. +Fill up memory with a pattern (byte 0xAB over and over again) that +hopefully catches attempts to access uninitialized memory. - bool isUPPER(char ch) + void Poison(void* dest, int nitems, type) =for hackers Found in file handy.h -=item is_utf8_char +=item Renew -Tests if some arbitrary number of bytes begins in a valid UTF-8 -character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character. -The actual number of bytes in the UTF-8 character will be returned if -it is valid, otherwise 0. +The XSUB-writer's interface to the C C function. - STRLEN is_utf8_char(U8 *p) + void Renew(void* ptr, int nitems, type) =for hackers -Found in file utf8.c +Found in file handy.h -=item is_utf8_string +=item Renewc -Returns true if first C bytes of the given string form a valid UTF8 -string, false otherwise. Note that 'a valid UTF8 string' does not mean -'a string that contains UTF8' because a valid ASCII string is a valid -UTF8 string. +The XSUB-writer's interface to the C C function, with +cast. - bool is_utf8_string(U8 *s, STRLEN len) + void Renewc(void* ptr, int nitems, type, cast) =for hackers -Found in file utf8.c +Found in file handy.h -=item items +=item Safefree -Variable which is setup by C to indicate the number of -items on the stack. See L. +The XSUB-writer's interface to the C C function. - I32 items + void Safefree(void* ptr) =for hackers -Found in file XSUB.h +Found in file handy.h -=item ix +=item savepv -Variable which is setup by C to indicate which of an -XSUB's aliases was used to invoke it. See L. +Perl's version of C. Returns a pointer to a newly allocated +string which is a duplicate of C. The size of the string is +determined by C. The memory allocated for the new string can +be freed with the C function. - I32 ix + char* savepv(const char* pv) =for hackers -Found in file XSUB.h +Found in file util.c -=item LEAVE +=item savepvn -Closing bracket on a callback. See C and L. +Perl's version of what C would be if it existed. Returns a +pointer to a newly allocated string which is a duplicate of the first +C bytes from C. The memory allocated for the new string can be +freed with the C function. - LEAVE; + char* savepvn(const char* pv, I32 len) =for hackers -Found in file scope.h +Found in file util.c -=item load_module +=item savesharedpv -Loads the module whose name is pointed to by the string part of name. -Note that the actual module name, not its filename, should be given. -Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of -PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS -(or 0 for no flags). ver, if specified, provides version semantics -similar to C. The optional trailing SV* -arguments can be used to specify arguments to the module's import() -method, similar to C. +A version of C which allocates the duplicate string in memory +which is shared between threads. - void load_module(U32 flags, SV* name, SV* ver, ...) + char* savesharedpv(const char* pv) =for hackers -Found in file op.c +Found in file util.c -=item looks_like_number +=item StructCopy -Test if the content of an SV looks like a number (or is a number). -C and C are treated as numbers (so will not issue a -non-numeric warning), even if your atof() doesn't grok them. +This is an architecture-independent macro to copy one structure to another. - I32 looks_like_number(SV* sv) + void StructCopy(type src, type dest, type) =for hackers -Found in file sv.c +Found in file handy.h -=item MARK +=item Zero -Stack marker variable for the XSUB. See C. +The XSUB-writer's interface to the C C function. The C is the +destination, C is the number of items, and C is the type. + + void Zero(void* dest, int nitems, type) =for hackers -Found in file pp.h +Found in file handy.h -=item mg_clear -Clear something magical that the SV represents. See C. +=back - int mg_clear(SV* sv) +=head1 Miscellaneous Functions + +=over 8 + +=item fbm_compile + +Analyses the string in order to make fast searches on it using fbm_instr() +-- the Boyer-Moore algorithm. + + void fbm_compile(SV* sv, U32 flags) =for hackers -Found in file mg.c +Found in file util.c -=item mg_copy +=item fbm_instr -Copies the magic from one SV to another. See C. +Returns the location of the SV in the string delimited by C and +C. It returns C if the string can't be found. The C +does not have to be fbm_compiled, but the search will not be as fast +then. - int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen) + char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags) =for hackers -Found in file mg.c +Found in file util.c -=item mg_find +=item form -Finds the magic pointer for type matching the SV. See C. +Takes a sprintf-style format pattern and conventional +(non-SV) arguments and returns the formatted string. - MAGIC* mg_find(SV* sv, int type) + (char *) Perl_form(pTHX_ const char* pat, ...) -=for hackers -Found in file mg.c +can be used any place a string (char *) is required: -=item mg_free + char * s = Perl_form("%d.%d",major,minor); -Free any magic storage used by the SV. See C. +Uses a single private buffer so if you want to format several strings you +must explicitly copy the earlier strings away (and free the copies when you +are done). - int mg_free(SV* sv) + char* form(const char* pat, ...) =for hackers -Found in file mg.c +Found in file util.c -=item mg_get +=item getcwd_sv -Do magic after a value is retrieved from the SV. See C. +Fill the sv with current working directory - int mg_get(SV* sv) + int getcwd_sv(SV* sv) =for hackers -Found in file mg.c +Found in file util.c -=item mg_length +=item strEQ -Report on the SV's length. See C. +Test two strings to see if they are equal. Returns true or false. - U32 mg_length(SV* sv) + bool strEQ(char* s1, char* s2) =for hackers -Found in file mg.c +Found in file handy.h -=item mg_magical +=item strGE -Turns on the magical status of an SV. See C. +Test two strings to see if the first, C, is greater than or equal to +the second, C. Returns true or false. - void mg_magical(SV* sv) + bool strGE(char* s1, char* s2) =for hackers -Found in file mg.c +Found in file handy.h -=item mg_set +=item strGT -Do magic after a value is assigned to the SV. See C. +Test two strings to see if the first, C, is greater than the second, +C. Returns true or false. - int mg_set(SV* sv) + bool strGT(char* s1, char* s2) =for hackers -Found in file mg.c +Found in file handy.h -=item Move +=item strLE -The XSUB-writer's interface to the C C function. The C is the -source, C is the destination, C is the number of items, and C is -the type. Can do overlapping moves. See also C. +Test two strings to see if the first, C, is less than or equal to the +second, C. Returns true or false. - void Move(void* src, void* dest, int nitems, type) + bool strLE(char* s1, char* s2) =for hackers Found in file handy.h -=item New +=item strLT -The XSUB-writer's interface to the C C function. +Test two strings to see if the first, C, is less than the second, +C. Returns true or false. - void New(int id, void* ptr, int nitems, type) + bool strLT(char* s1, char* s2) =for hackers Found in file handy.h -=item newAV +=item strNE -Creates a new AV. The reference count is set to 1. +Test two strings to see if they are different. Returns true or +false. - AV* newAV() + bool strNE(char* s1, char* s2) =for hackers -Found in file av.c +Found in file handy.h -=item Newc +=item strnEQ -The XSUB-writer's interface to the C C function, with -cast. +Test two strings to see if they are equal. The C parameter indicates +the number of bytes to compare. Returns true or false. (A wrapper for +C). - void Newc(int id, void* ptr, int nitems, type, cast) + bool strnEQ(char* s1, char* s2, STRLEN len) =for hackers Found in file handy.h -=item newCONSTSUB +=item strnNE -Creates a constant sub equivalent to Perl C which is -eligible for inlining at compile-time. +Test two strings to see if they are different. The C parameter +indicates the number of bytes to compare. Returns true or false. (A +wrapper for C). - CV* newCONSTSUB(HV* stash, char* name, SV* sv) + bool strnNE(char* s1, char* s2, STRLEN len) =for hackers -Found in file op.c - -=item newHV +Found in file handy.h -Creates a new HV. The reference count is set to 1. - HV* newHV() +=back -=for hackers -Found in file hv.c +=head1 Numeric functions -=item newRV_inc +=over 8 -Creates an RV wrapper for an SV. The reference count for the original SV is -incremented. +=item grok_bin - SV* newRV_inc(SV* sv) +converts a string representing a binary number to numeric form. -=for hackers -Found in file sv.h +On entry I and I<*len> give the string to scan, I<*flags> gives +conversion flags, and I should be NULL or a pointer to an NV. +The scan stops at the end of the string, or the first invalid character. +On return I<*len> is set to the length scanned string, and I<*flags> gives +output flags. -=item newRV_noinc +If the value is <= UV_MAX it is returned as a UV, the output flags are clear, +and nothing is written to I<*result>. If the value is > UV_MAX C +returns UV_MAX, sets C in the output flags, +and writes the value to I<*result> (or the value is discarded if I +is NULL). -Creates an RV wrapper for an SV. The reference count for the original -SV is B incremented. +The hex number may optionally be prefixed with "0b" or "b" unless +C is set in I<*flags> on entry. If +C is set in I<*flags> then the binary +number may use '_' characters to separate digits. - SV* newRV_noinc(SV *sv) + UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file sv.c - -=item newSV +Found in file numeric.c -Create a new null SV, or if len > 0, create a new empty SVt_PV type SV -with an initial PV allocation of len+1. Normally accessed via the C -macro. +=item grok_hex - SV* newSV(STRLEN len) +converts a string representing a hex number to numeric form. -=for hackers -Found in file sv.c +On entry I and I<*len> give the string to scan, I<*flags> gives +conversion flags, and I should be NULL or a pointer to an NV. +The scan stops at the end of the string, or the first non-hex-digit character. +On return I<*len> is set to the length scanned string, and I<*flags> gives +output flags. -=item NEWSV +If the value is <= UV_MAX it is returned as a UV, the output flags are clear, +and nothing is written to I<*result>. If the value is > UV_MAX C +returns UV_MAX, sets C in the output flags, +and writes the value to I<*result> (or the value is discarded if I +is NULL). -Creates a new SV. A non-zero C parameter indicates the number of -bytes of preallocated string space the SV should have. An extra byte for a -tailing NUL is also reserved. (SvPOK is not set for the SV even if string -space is allocated.) The reference count for the new SV is set to 1. -C is an integer id between 0 and 1299 (used to identify leaks). +The hex number may optionally be prefixed with "0x" or "x" unless +C is set in I<*flags> on entry. If +C is set in I<*flags> then the hex +number may use '_' characters to separate digits. - SV* NEWSV(int id, STRLEN len) + UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file handy.h +Found in file numeric.c -=item newSViv +=item grok_number -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. +Recognise (or not) a number. The type of the number is returned +(0 if unrecognised), otherwise it is a bit-ORed combination of +IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, +IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h). - SV* newSViv(IV i) +If the value of the number can fit an in UV, it is returned in the *valuep +IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV +will never be set unless *valuep is valid, but *valuep may have been assigned +to during processing even though IS_NUMBER_IN_UV is not set on return. +If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when +valuep is non-NULL, but no actual assignment (or SEGV) will occur. + +IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were +seen (in which case *valuep gives the true value truncated to an integer), and +IS_NUMBER_NEG if the number is negative (in which case *valuep holds the +absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the +number is larger than a UV. + + int grok_number(const char *pv, STRLEN len, UV *valuep) =for hackers -Found in file sv.c +Found in file numeric.c -=item newSVnv +=item grok_numeric_radix -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. +Scan and skip for a numeric decimal separator (radix). - SV* newSVnv(NV n) + bool grok_numeric_radix(const char **sp, const char *send) =for hackers -Found in file sv.c +Found in file numeric.c -=item newSVpv +=item grok_oct -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. If C is zero, Perl will compute the length using -strlen(). For efficiency, consider using C instead. - SV* newSVpv(const char* s, STRLEN len) + UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result) =for hackers -Found in file sv.c +Found in file numeric.c -=item newSVpvf +=item scan_bin -Creates a new SV and initializes it with the string formatted like -C. +For backwards compatibility. Use C instead. - SV* newSVpvf(const char* pat, ...) + NV scan_bin(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file sv.c +Found in file numeric.c -=item newSVpvn +=item scan_hex -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. Note that if C is zero, Perl will create a zero length -string. You are responsible for ensuring that the source string is at least -C bytes long. +For backwards compatibility. Use C instead. - SV* newSVpvn(const char* s, STRLEN len) + NV scan_hex(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file sv.c +Found in file numeric.c -=item newSVpvn_share +=item scan_oct -Creates a new SV with its SvPVX pointing to a shared string in the string -table. If the string does not already exist in the table, it is created -first. Turns on READONLY and FAKE. The string's hash is stored in the UV -slot of the SV; if the C parameter is non-zero, that value is used; -otherwise the hash is computed. The idea here is that as the string table -is used for shared hash keys these strings will have SvPVX == HeKEY and -hash lookup will avoid string compare. +For backwards compatibility. Use C instead. - SV* newSVpvn_share(const char* s, I32 len, U32 hash) + NV scan_oct(char* start, STRLEN len, STRLEN* retlen) =for hackers -Found in file sv.c - -=item newSVrv +Found in file numeric.c -Creates a new SV for the RV, C, to point to. If C is not an RV then -it will be upgraded to one. If C is non-null then the new SV will -be blessed in the specified package. The new SV is returned and its -reference count is 1. - SV* newSVrv(SV* rv, const char* classname) +=back -=for hackers -Found in file sv.c +=head1 Optree Manipulation Functions -=item newSVsv +=over 8 -Creates a new SV which is an exact duplicate of the original SV. -(Uses C). +=item cv_const_sv - SV* newSVsv(SV* old) +If C is a constant sub eligible for inlining. returns the constant +value returned by the sub. Otherwise, returns NULL. + +Constant subs can be created with C or as described in +L. + + SV* cv_const_sv(CV* cv) =for hackers -Found in file sv.c +Found in file op.c -=item newSVuv +=item newCONSTSUB -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. +Creates a constant sub equivalent to Perl C which is +eligible for inlining at compile-time. - SV* newSVuv(UV u) + CV* newCONSTSUB(HV* stash, char* name, SV* sv) =for hackers -Found in file sv.c +Found in file op.c =item newXS @@ -1551,76 +1941,76 @@ Used by C to hook up XSUBs as Perl subs. =for hackers Found in file op.c -=item newXSproto -Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to -the subs. +=back -=for hackers -Found in file XSUB.h +=head1 Pad Data Structures -=item Newz +=over 8 -The XSUB-writer's interface to the C C function. The allocated -memory is zeroed with C. +=item pad_sv - void Newz(int id, void* ptr, int nitems, type) +Get the value at offset po in the current pad. +Use macro PAD_SV instead of calling this function directly. + + SV* pad_sv(PADOFFSET po) =for hackers -Found in file handy.h +Found in file pad.c -=item new_vstring -Returns a pointer to the next character after the parsed -vstring, as well as updating the passed in sv. - * -Function must be called like - - sv = NEWSV(92,5); - s = new_vstring(s,sv); +=back -The sv must already be large enough to store the vstring -passed in. +=head1 Stack Manipulation Macros - char* new_vstring(char *vstr, SV *sv) +=over 8 -=for hackers -Found in file util.c +=item dMARK -=item Nullav +Declare a stack marker variable, C, for the XSUB. See C and +C. -Null AV pointer. + dMARK; =for hackers -Found in file av.h +Found in file pp.h -=item Nullch +=item dORIGMARK -Null character pointer. +Saves the original stack mark for the XSUB. See C. + + dORIGMARK; =for hackers -Found in file handy.h +Found in file pp.h -=item Nullcv +=item dSP -Null CV pointer. +Declares a local copy of perl's stack pointer for the XSUB, available via +the C macro. See C. + + dSP; =for hackers -Found in file cv.h +Found in file pp.h -=item Nullhv +=item EXTEND -Null HV pointer. +Used to extend the argument stack for an XSUB's return values. Once +used, guarantees that there is room for at least C to be pushed +onto the stack. + + void EXTEND(SP, int nitems) =for hackers -Found in file hv.h +Found in file pp.h -=item Nullsv +=item MARK -Null SV pointer. +Stack marker variable for the XSUB. See C. =for hackers -Found in file handy.h +Found in file pp.h =item ORIGMARK @@ -1629,571 +2019,613 @@ The original stack mark for the XSUB. See C. =for hackers Found in file pp.h -=item perl_alloc +=item POPi -Allocates a new Perl interpreter. See L. +Pops an integer off the stack. - PerlInterpreter* perl_alloc() + IV POPi =for hackers -Found in file perl.c +Found in file pp.h -=item perl_clone +=item POPl -Create and return a new interpreter by cloning the current one. +Pops a long off the stack. - PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags) + long POPl =for hackers -Found in file sv.c +Found in file pp.h -=item perl_construct +=item POPn -Initializes a new Perl interpreter. See L. +Pops a double off the stack. - void perl_construct(PerlInterpreter* interp) + NV POPn =for hackers -Found in file perl.c +Found in file pp.h -=item perl_destruct +=item POPp -Shuts down a Perl interpreter. See L. +Pops a string off the stack. Deprecated. New code should provide +a STRLEN n_a and use POPpx. - int perl_destruct(PerlInterpreter* interp) + char* POPp =for hackers -Found in file perl.c +Found in file pp.h -=item perl_free +=item POPpbytex -Releases a Perl interpreter. See L. +Pops a string off the stack which must consist of bytes i.e. characters < 256. +Requires a variable STRLEN n_a in scope. - void perl_free(PerlInterpreter* interp) + char* POPpbytex =for hackers -Found in file perl.c +Found in file pp.h -=item perl_parse +=item POPpx -Tells a Perl interpreter to parse a Perl script. See L. +Pops a string off the stack. +Requires a variable STRLEN n_a in scope. - int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env) + char* POPpx =for hackers -Found in file perl.c +Found in file pp.h -=item perl_run +=item POPs -Tells a Perl interpreter to run. See L. +Pops an SV off the stack. - int perl_run(PerlInterpreter* interp) + SV* POPs =for hackers -Found in file perl.c +Found in file pp.h -=item PL_modglobal +=item PUSHi -C is a general purpose, interpreter global HV for use by -extensions that need to keep information on a per-interpreter basis. -In a pinch, it can also be used as a symbol table for extensions -to share data among each other. It is a good idea to use keys -prefixed by the package name of the extension that owns the data. +Push an integer onto the stack. The stack must have room for this element. +Handles 'set' magic. See C. - HV* PL_modglobal + void PUSHi(IV iv) =for hackers -Found in file intrpvar.h +Found in file pp.h -=item PL_na +=item PUSHMARK -A convenience variable which is typically used with C when one -doesn't care about the length of the string. It is usually more efficient -to either declare a local variable and use that instead or to use the -C macro. +Opening bracket for arguments on a callback. See C and +L. - STRLEN PL_na + PUSHMARK; =for hackers -Found in file thrdvar.h +Found in file pp.h -=item PL_sv_no +=item PUSHn -This is the C SV. See C. Always refer to this as -C<&PL_sv_no>. +Push a double onto the stack. The stack must have room for this element. +Handles 'set' magic. See C. - SV PL_sv_no + void PUSHn(NV nv) =for hackers -Found in file intrpvar.h +Found in file pp.h -=item PL_sv_undef +=item PUSHp -This is the C SV. Always refer to this as C<&PL_sv_undef>. +Push a string onto the stack. The stack must have room for this element. +The C indicates the length of the string. Handles 'set' magic. See +C. - SV PL_sv_undef + void PUSHp(char* str, STRLEN len) =for hackers -Found in file intrpvar.h +Found in file pp.h -=item PL_sv_yes +=item PUSHs -This is the C SV. See C. Always refer to this as -C<&PL_sv_yes>. +Push an SV onto the stack. The stack must have room for this element. +Does not handle 'set' magic. See C. - SV PL_sv_yes + void PUSHs(SV* sv) =for hackers -Found in file intrpvar.h +Found in file pp.h -=item POPi +=item PUSHu -Pops an integer off the stack. +Push an unsigned integer onto the stack. The stack must have room for this +element. See C. - IV POPi + void PUSHu(UV uv) =for hackers Found in file pp.h -=item POPl +=item PUTBACK -Pops a long off the stack. +Closing bracket for XSUB arguments. This is usually handled by C. +See C and L for other uses. - long POPl + PUTBACK; =for hackers Found in file pp.h -=item POPn +=item SP -Pops a double off the stack. +Stack pointer. This is usually handled by C. See C and +C. - NV POPn +=for hackers +Found in file pp.h + +=item SPAGAIN + +Refetch the stack pointer. Used after a callback. See L. + + SPAGAIN; =for hackers Found in file pp.h -=item POPp +=item XPUSHi -Pops a string off the stack. Deprecated. New code should provide -a STRLEN n_a and use POPpx. +Push an integer onto the stack, extending the stack if necessary. Handles +'set' magic. See C. - char* POPp + void XPUSHi(IV iv) =for hackers Found in file pp.h -=item POPpbytex +=item XPUSHn -Pops a string off the stack which must consist of bytes i.e. characters < 256. -Requires a variable STRLEN n_a in scope. +Push a double onto the stack, extending the stack if necessary. Handles +'set' magic. See C. - char* POPpbytex + void XPUSHn(NV nv) =for hackers Found in file pp.h -=item POPpx +=item XPUSHp -Pops a string off the stack. -Requires a variable STRLEN n_a in scope. +Push a string onto the stack, extending the stack if necessary. The C +indicates the length of the string. Handles 'set' magic. See +C. - char* POPpx + void XPUSHp(char* str, STRLEN len) =for hackers Found in file pp.h -=item POPs +=item XPUSHs -Pops an SV off the stack. +Push an SV onto the stack, extending the stack if necessary. Does not +handle 'set' magic. See C. - SV* POPs + void XPUSHs(SV* sv) =for hackers Found in file pp.h -=item PUSHi +=item XPUSHu -Push an integer onto the stack. The stack must have room for this element. -Handles 'set' magic. See C. +Push an unsigned integer onto the stack, extending the stack if necessary. +See C. - void PUSHi(IV iv) + void XPUSHu(UV uv) =for hackers Found in file pp.h -=item PUSHMARK +=item XSRETURN -Opening bracket for arguments on a callback. See C and -L. +Return from XSUB, indicating number of items on the stack. This is usually +handled by C. - PUSHMARK; + void XSRETURN(int nitems) =for hackers -Found in file pp.h +Found in file XSUB.h -=item PUSHn +=item XSRETURN_IV -Push a double onto the stack. The stack must have room for this element. -Handles 'set' magic. See C. +Return an integer from an XSUB immediately. Uses C. - void PUSHn(NV nv) + void XSRETURN_IV(IV iv) =for hackers -Found in file pp.h +Found in file XSUB.h -=item PUSHp +=item XSRETURN_NO -Push a string onto the stack. The stack must have room for this element. -The C indicates the length of the string. Handles 'set' magic. See -C. +Return C<&PL_sv_no> from an XSUB immediately. Uses C. - void PUSHp(char* str, STRLEN len) + XSRETURN_NO; =for hackers -Found in file pp.h +Found in file XSUB.h -=item PUSHs +=item XSRETURN_NV -Push an SV onto the stack. The stack must have room for this element. -Does not handle 'set' magic. See C. +Return a double from an XSUB immediately. Uses C. - void PUSHs(SV* sv) + void XSRETURN_NV(NV nv) =for hackers -Found in file pp.h +Found in file XSUB.h -=item PUSHu +=item XSRETURN_PV -Push an unsigned integer onto the stack. The stack must have room for this -element. See C. +Return a copy of a string from an XSUB immediately. Uses C. - void PUSHu(UV uv) + void XSRETURN_PV(char* str) =for hackers -Found in file pp.h +Found in file XSUB.h -=item PUTBACK +=item XSRETURN_UNDEF -Closing bracket for XSUB arguments. This is usually handled by C. -See C and L for other uses. +Return C<&PL_sv_undef> from an XSUB immediately. Uses C. - PUTBACK; + XSRETURN_UNDEF; =for hackers -Found in file pp.h +Found in file XSUB.h -=item pv_uni_display +=item XSRETURN_YES -Build to the scalar dsv a displayable version of the string spv, -length len, the displayable version being at most pvlim bytes long -(if longer, the rest is truncated and "..." will be appended). -The flags argument is currently unused but available for future extensions. -The pointer to the PV of the dsv is returned. +Return C<&PL_sv_yes> from an XSUB immediately. Uses C. - char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags) + XSRETURN_YES; =for hackers -Found in file utf8.c +Found in file XSUB.h -=item Renew +=item XST_mIV -The XSUB-writer's interface to the C C function. +Place an integer into the specified position C on the stack. The +value is stored in a new mortal SV. - void Renew(void* ptr, int nitems, type) + void XST_mIV(int pos, IV iv) =for hackers -Found in file handy.h +Found in file XSUB.h -=item Renewc +=item XST_mNO -The XSUB-writer's interface to the C C function, with -cast. +Place C<&PL_sv_no> into the specified position C on the +stack. - void Renewc(void* ptr, int nitems, type, cast) + void XST_mNO(int pos) =for hackers -Found in file handy.h - -=item require_pv +Found in file XSUB.h -Tells Perl to C the file named by the string argument. It is -analogous to the Perl code C. It's even -implemented that way; consider using Perl_load_module instead. +=item XST_mNV -NOTE: the perl_ form of this function is deprecated. +Place a double into the specified position C on the stack. The value +is stored in a new mortal SV. - void require_pv(const char* pv) + void XST_mNV(int pos, NV nv) =for hackers -Found in file perl.c +Found in file XSUB.h -=item RETVAL +=item XST_mPV -Variable which is setup by C to hold the return value for an -XSUB. This is always the proper type for the XSUB. See -L. +Place a copy of a string into the specified position C on the stack. +The value is stored in a new mortal SV. - (whatever) RETVAL + void XST_mPV(int pos, char* str) =for hackers Found in file XSUB.h -=item Safefree +=item XST_mUNDEF -The XSUB-writer's interface to the C C function. +Place C<&PL_sv_undef> into the specified position C on the +stack. - void Safefree(void* ptr) + void XST_mUNDEF(int pos) =for hackers -Found in file handy.h +Found in file XSUB.h -=item savepv +=item XST_mYES -Copy a string to a safe spot. This does not use an SV. +Place C<&PL_sv_yes> into the specified position C on the +stack. - char* savepv(const char* sv) + void XST_mYES(int pos) =for hackers -Found in file util.c +Found in file XSUB.h -=item savepvn -Copy a string to a safe spot. The C indicates number of bytes to -copy. This does not use an SV. +=back - char* savepvn(const char* sv, I32 len) +=head1 SV Flags -=for hackers -Found in file util.c +=over 8 -=item SAVETMPS +=item svtype -Opening bracket for temporaries on a callback. See C and -L. +An enum of flags for Perl types. These are found in the file B +in the C enum. Test these flags with the C macro. - SAVETMPS; +=for hackers +Found in file sv.h + +=item SVt_IV + +Integer type flag for scalars. See C. =for hackers -Found in file scope.h +Found in file sv.h -=item scan_bin +=item SVt_NV -For backwards compatibility. Use C instead. +Double type flag for scalars. See C. - NV scan_bin(char* start, STRLEN len, STRLEN* retlen) +=for hackers +Found in file sv.h + +=item SVt_PV + +Pointer type flag for scalars. See C. =for hackers -Found in file numeric.c +Found in file sv.h -=item scan_hex +=item SVt_PVAV -For backwards compatibility. Use C instead. +Type flag for arrays. See C. - NV scan_hex(char* start, STRLEN len, STRLEN* retlen) +=for hackers +Found in file sv.h + +=item SVt_PVCV + +Type flag for code refs. See C. =for hackers -Found in file numeric.c +Found in file sv.h -=item scan_oct +=item SVt_PVHV -For backwards compatibility. Use C instead. +Type flag for hashes. See C. - NV scan_oct(char* start, STRLEN len, STRLEN* retlen) +=for hackers +Found in file sv.h + +=item SVt_PVMG + +Type flag for blessed scalars. See C. =for hackers -Found in file numeric.c +Found in file sv.h + -=item sharedsv_find +=back -Tries to find if a given SV has a shared backend, either by -looking at magic, or by checking if it is tied again threads::shared. +=head1 SV Manipulation Functions - shared_sv* sharedsv_find(SV* sv) +=over 8 -=for hackers -Found in file sharedsv.c +=item get_sv -=item sharedsv_init +Returns the SV of the specified Perl scalar. If C is set and the +Perl variable does not exist then it will be created. If C is not +set and the variable does not exist then NULL is returned. -Saves a space for keeping SVs wider than an interpreter, -currently only stores a pointer to the first interpreter. +NOTE: the perl_ form of this function is deprecated. - void sharedsv_init() + SV* get_sv(const char* name, I32 create) =for hackers -Found in file sharedsv.c +Found in file perl.c + +=item looks_like_number -=item sharedsv_lock +Test if the content of an SV looks like a number (or is a number). +C and C are treated as numbers (so will not issue a +non-numeric warning), even if your atof() doesn't grok them. -Recursive locks on a sharedsv. -Locks are dynamically scoped at the level of the first lock. - void sharedsv_lock(shared_sv* ssv) + I32 looks_like_number(SV* sv) =for hackers -Found in file sharedsv.c +Found in file sv.c + +=item newRV_inc -=item sharedsv_new +Creates an RV wrapper for an SV. The reference count for the original SV is +incremented. -Allocates a new shared sv struct, you must yourself create the SV/AV/HV. - shared_sv* sharedsv_new() + SV* newRV_inc(SV* sv) =for hackers -Found in file sharedsv.c +Found in file sv.h -=item sharedsv_thrcnt_dec +=item newRV_noinc -Decrements the threadcount of a shared sv. When a threads frontend is freed -this function should be called. +Creates an RV wrapper for an SV. The reference count for the original +SV is B incremented. - void sharedsv_thrcnt_dec(shared_sv* ssv) + SV* newRV_noinc(SV *sv) =for hackers -Found in file sharedsv.c +Found in file sv.c -=item sharedsv_thrcnt_inc +=item newSV + +Create a new null SV, or if len > 0, create a new empty SVt_PV type SV +with an initial PV allocation of len+1. Normally accessed via the C +macro. -Increments the threadcount of a sharedsv. - void sharedsv_thrcnt_inc(shared_sv* ssv) + SV* newSV(STRLEN len) =for hackers -Found in file sharedsv.c +Found in file sv.c -=item sharedsv_unlock +=item newSViv -Recursively unlocks a shared sv. +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. - void sharedsv_unlock(shared_sv* ssv) + SV* newSViv(IV i) =for hackers -Found in file sharedsv.c - -=item sortsv +Found in file sv.c -Sort an array. Here is an example: +=item newSVnv - sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. - void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) + SV* newSVnv(NV n) =for hackers -Found in file pp_sort.c +Found in file sv.c -=item SP +=item newSVpv + +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. If C is zero, Perl will compute the length using +strlen(). For efficiency, consider using C instead. -Stack pointer. This is usually handled by C. See C and -C. + SV* newSVpv(const char* s, STRLEN len) =for hackers -Found in file pp.h +Found in file sv.c -=item SPAGAIN +=item newSVpvf -Refetch the stack pointer. Used after a callback. See L. +Creates a new SV and initializes it with the string formatted like +C. - SPAGAIN; + SV* newSVpvf(const char* pat, ...) =for hackers -Found in file pp.h +Found in file sv.c -=item ST +=item newSVpvn -Used to access elements on the XSUB's stack. +Creates a new SV and copies a string into it. The reference count for the +SV is set to 1. Note that if C is zero, Perl will create a zero length +string. You are responsible for ensuring that the source string is at least +C bytes long. - SV* ST(int ix) + SV* newSVpvn(const char* s, STRLEN len) =for hackers -Found in file XSUB.h +Found in file sv.c -=item strEQ +=item newSVpvn_share -Test two strings to see if they are equal. Returns true or false. +Creates a new SV with its SvPVX pointing to a shared string in the string +table. If the string does not already exist in the table, it is created +first. Turns on READONLY and FAKE. The string's hash is stored in the UV +slot of the SV; if the C parameter is non-zero, that value is used; +otherwise the hash is computed. The idea here is that as the string table +is used for shared hash keys these strings will have SvPVX == HeKEY and +hash lookup will avoid string compare. - bool strEQ(char* s1, char* s2) + SV* newSVpvn_share(const char* s, I32 len, U32 hash) =for hackers -Found in file handy.h +Found in file sv.c -=item strGE +=item newSVrv -Test two strings to see if the first, C, is greater than or equal to -the second, C. Returns true or false. +Creates a new SV for the RV, C, to point to. If C is not an RV then +it will be upgraded to one. If C is non-null then the new SV will +be blessed in the specified package. The new SV is returned and its +reference count is 1. - bool strGE(char* s1, char* s2) + SV* newSVrv(SV* rv, const char* classname) =for hackers -Found in file handy.h +Found in file sv.c -=item strGT +=item newSVsv -Test two strings to see if the first, C, is greater than the second, -C. Returns true or false. +Creates a new SV which is an exact duplicate of the original SV. +(Uses C). - bool strGT(char* s1, char* s2) + SV* newSVsv(SV* old) =for hackers -Found in file handy.h +Found in file sv.c -=item strLE +=item newSVuv -Test two strings to see if the first, C, is less than or equal to the -second, C. Returns true or false. +Creates a new SV and copies an unsigned integer into it. +The reference count for the SV is set to 1. - bool strLE(char* s1, char* s2) + SV* newSVuv(UV u) =for hackers -Found in file handy.h +Found in file sv.c -=item strLT +=item new_version -Test two strings to see if the first, C, is less than the second, -C. Returns true or false. +Returns a new version object based on the passed in SV: - bool strLT(char* s1, char* s2) + SV *sv = new_version(SV *ver); -=for hackers -Found in file handy.h +Does not alter the passed in ver SV. See "upg_version" if you +want to upgrade the SV. -=item strNE + SV* new_version(SV *ver) -Test two strings to see if they are different. Returns true or -false. +=for hackers +Found in file util.c - bool strNE(char* s1, char* s2) +=item scan_version -=for hackers -Found in file handy.h +Returns a pointer to the next character after the parsed +version string, as well as upgrading the passed in SV to +an RV. -=item strnEQ +Function must be called with an already existing SV like -Test two strings to see if they are equal. The C parameter indicates -the number of bytes to compare. Returns true or false. (A wrapper for -C). + sv = NEWSV(92,0); + s = scan_version(s,sv); - bool strnEQ(char* s1, char* s2, STRLEN len) +Performs some preprocessing to the string to ensure that +it has the correct characteristics of a version. Flags the +object if it contains an underscore (which denotes this +is a beta version). -=for hackers -Found in file handy.h + char* scan_version(char *vstr, SV *sv) -=item strnNE +=for hackers +Found in file util.c -Test two strings to see if they are different. The C parameter -indicates the number of bytes to compare. Returns true or false. (A -wrapper for C). +=item scan_vstring - bool strnNE(char* s1, char* s2, STRLEN len) +Returns a pointer to the next character after the parsed +vstring, as well as updating the passed in sv. -=for hackers -Found in file handy.h +Function must be called like -=item StructCopy + sv = NEWSV(92,5); + s = scan_vstring(s,sv); -This is an architecture-independent macro to copy one structure to another. +The sv should already be large enough to store the vstring +passed in, for performance reasons. - void StructCopy(type src, type dest, type) + char* scan_vstring(char *vstr, SV *sv) =for hackers -Found in file handy.h +Found in file util.c =item SvCUR @@ -2223,16 +2655,6 @@ See C. Access the character as *(SvEND(sv)). =for hackers Found in file sv.h -=item SvGETMAGIC - -Invokes C on an SV if it has 'get' magic. This macro evaluates its -argument more than once. - - void SvGETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - =item SvGROW Expands the character buffer in the SV so that it has room for the @@ -2443,22 +2865,22 @@ which guarantees to evaluate sv only once. =for hackers Found in file sv.h -=item SvNVx +=item SvNVX -Coerces the given SV to a double and returns it. Guarantees to evaluate -sv only once. Use the more efficient C otherwise. +Returns the raw value in the SV's NV slot, without checks or conversions. +Only use when you are sure SvNOK is true. See also C. - NV SvNVx(SV* sv) + NV SvNVX(SV* sv) =for hackers Found in file sv.h -=item SvNVX +=item SvNVx -Returns the raw value in the SV's NV slot, without checks or conversions. -Only use when you are sure SvNOK is true. See also C. +Coerces the given SV to a double and returns it. Guarantees to evaluate +sv only once. Use the more efficient C otherwise. - NV SvNVX(SV* sv) + NV SvNVx(SV* sv) =for hackers Found in file sv.h @@ -2544,8 +2966,9 @@ Found in file sv.h =item SvPV -Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. Handles 'get' magic. See also +Returns a pointer to the string in the SV, or a stringified form of +the SV if the SV does not contain a string. The SV may cache the +stringified version becoming C. Handles 'get' magic. See also C for a version which guarantees to evaluate sv only once. char* SvPV(SV* sv, STRLEN len) @@ -2652,29 +3075,30 @@ Like C, but converts sv to utf8 first if necessary. =for hackers Found in file sv.h -=item SvPVX +=item SvPVx -Returns a pointer to the physical string in the SV. The SV must contain a -string. +A version of C which guarantees to evaluate sv only once. - char* SvPVX(SV* sv) + char* SvPVx(SV* sv, STRLEN len) =for hackers Found in file sv.h -=item SvPVx +=item SvPVX -A version of C which guarantees to evaluate sv only once. +Returns a pointer to the physical string in the SV. The SV must contain a +string. - char* SvPVx(SV* sv, STRLEN len) + char* SvPVX(SV* sv) =for hackers Found in file sv.h =item SvPV_force -Like but will force the SV into becoming a string (SvPOK). You want -force if you are going to update the SvPVX directly. +Like C but will force the SV into containing just a string +(C). You want force if you are going to update the C +directly. char* SvPV_force(SV* sv, STRLEN len) @@ -2683,8 +3107,9 @@ Found in file sv.h =item SvPV_force_nomg -Like but will force the SV into becoming a string (SvPOK). You want -force if you are going to update the SvPVX directly. Doesn't process magic. +Like C but will force the SV into containing just a string +(C). You want force if you are going to update the C +directly. Doesn't process magic. char* SvPV_force_nomg(SV* sv, STRLEN len) @@ -2693,8 +3118,9 @@ Found in file sv.h =item SvPV_nolen -Returns a pointer to the string in the SV, or a stringified form of the SV -if the SV does not contain a string. Handles 'get' magic. +Returns a pointer to the string in the SV, or a stringified form of +the SV if the SV does not contain a string. The SV may cache the +stringified form becoming C. Handles 'get' magic. char* SvPV_nolen(SV* sv) @@ -2764,54 +3190,6 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h -=item SvSETMAGIC - -Invokes C on an SV if it has 'set' magic. This macro evaluates its -argument more than once. - - void SvSETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSetMagicSV - -Like C, but does any set magic required afterwards. - - void SvSetMagicSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetMagicSV_nosteal - -Like C, but does any set magic required afterwards. - - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV - -Calls C if dsv is not the same as ssv. May evaluate arguments -more than once. - - void SvSetSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV_nosteal - -Calls a non-destructive version of C if dsv is not the same as -ssv. May evaluate arguments more than once. - - void SvSetSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item SvSTASH Returns the stash of the SV. @@ -2873,14 +3251,6 @@ false, defined or undefined. Does not handle 'get' magic. =for hackers Found in file sv.h -=item svtype - -An enum of flags for Perl types. These are found in the file B -in the C enum. Test these flags with the C macro. - -=for hackers -Found in file sv.h - =item SvTYPE Returns the type of the SV. See C. @@ -2890,51 +3260,13 @@ Returns the type of the SV. See C. =for hackers Found in file sv.h -=item SVt_IV - -Integer type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_NV - -Double type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_PV - -Pointer type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVAV - -Type flag for arrays. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVCV - -Type flag for code refs. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVHV - -Type flag for hashes. See C. +=item SvUNLOCK -=for hackers -Found in file sv.h +Releases a mutual exclusion lock on sv if a suitable module +has been loaded. -=item SVt_PVMG -Type flag for blessed scalars. See C. + void SvUNLOCK(SV* sv) =for hackers Found in file sv.h @@ -2991,7 +3323,17 @@ Found in file sv.h Coerces the given SV to an unsigned integer and returns it. See C for a version which guarantees to evaluate sv only once. - UV SvUV(SV* sv) + UV SvUV(SV* sv) + +=for hackers +Found in file sv.h + +=item SvUVX + +Returns the raw value in the SV's UV slot, without checks or conversions. +Only use when you are sure SvIOK is true. See also C. + + UV SvUVX(SV* sv) =for hackers Found in file sv.h @@ -3006,12 +3348,11 @@ evaluate sv only once. Use the more efficient C otherwise. =for hackers Found in file sv.h -=item SvUVX +=item SvVOK -Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. +Returns a boolean indicating whether the SV contains a v-string. - UV SvUVX(SV* sv) + bool SvVOK(SV* sv) =for hackers Found in file sv.h @@ -3357,6 +3698,21 @@ settings. =for hackers Found in file sv.c +=item sv_copypv + +Copies a stringified representation of the source SV into the +destination SV. Automatically performs any necessary mg_get and +coercion of numeric values into strings. Guaranteed to preserve +UTF-8 flag even from overloaded objects. Similar in nature to +sv_2pv[_flags] but operates directly on an SV instead of just the +string. Mostly uses sv_2pv_flags to do its work, except when that +would lose the UTF-8'ness of the PV. + + void sv_copypv(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.c + =item sv_dec Auto-decrement of the value in the SV, doing string to numeric conversion @@ -3404,8 +3760,13 @@ Found in file sv.c Undo various types of fakery on an SV: if the PV is a shared string, make a private copy; if we're a ref, stop refing; if we're a glob, downgrade to -an xpvmg. The C parameter gets passed to C -when unrefing. C calls this function with flags set to 0. +an xpvmg; if we're a copy-on-write scalar, this is the on-write time when +we do the copy, and is also used locally. If C is set +then a copy-on-write scalar drops its PV buffer (if any) and becomes +SvPOK_off rather than making a copy. (Used where this scalar is about to be +set to some other value.) In addition, the C parameter gets passed to +C when unrefing. C calls this function +with flags set to 0. void sv_force_normal_flags(SV *sv, U32 flags) @@ -3522,13 +3883,32 @@ Found in file sv.c Adds magic to an SV. First upgrades C to type C if necessary, then adds a new magic item of type C to the head of the magic list. -C is assumed to contain an C if C<(name && namelen == HEf_SVKEY)> - void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen) =for hackers Found in file sv.c +=item sv_magicext + +Adds magic to an SV, upgrading it if necessary. Applies the +supplied vtable and returns pointer to the magic added. + +Note that sv_magicext will allow things that sv_magic will not. +In particular you can add magic to SvREADONLY SVs and and more than +one instance of the same 'how' + +I C is greater then zero then a savepvn() I of C is stored, +if C is zero then C is stored as-is and - as another special +case - if C<(name && namelen == HEf_SVKEY)> then C is assumed to contain +an C and has its REFCNT incremented + +(This is now used as a subroutine by sv_magic.) + + MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen ) + +=for hackers +Found in file sv.c + =item sv_mortalcopy Creates a new SV which is a copy of the original SV (using C). @@ -3563,6 +3943,39 @@ instead. =for hackers Found in file sv.c +=item sv_nolocking + +Dummy routine which "locks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nolocking(SV *) + +=for hackers +Found in file util.c + +=item sv_nosharing + +Dummy routine which "shares" an SV when there is no sharing module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nosharing(SV *) + +=for hackers +Found in file util.c + +=item sv_nounlocking + +Dummy routine which "unlocks" an SV when there is no locking module present. +Exists to avoid test for a NULL function pointer and because it could potentially warn under +some level of strict-ness. + + void sv_nounlocking(SV *) + +=for hackers +Found in file util.c + =item sv_nv A private implementation of the C macro for compilers which can't @@ -3599,8 +4012,7 @@ Found in file sv.c =item sv_pv -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. +Use the C macro instead char* sv_pv(SV *sv) @@ -3609,9 +4021,7 @@ Found in file sv.c =item sv_pvbyte -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. +Use C instead. char* sv_pvbyte(SV *sv) @@ -3677,9 +4087,7 @@ Found in file sv.c =item sv_pvutf8 -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. +Use the C macro instead char* sv_pvutf8(SV *sv) @@ -3708,24 +4116,6 @@ instead. =for hackers Found in file sv.c -=item sv_recode_to_utf8 - -The encoding is assumed to be an Encode object, on entry the PV -of the sv is assumed to be octets in that encoding, and the sv -will be converted into Unicode (and UTF-8). - -If the sv already is UTF-8 (or if it is not POK), or if the encoding -is not a reference, nothing is done to the sv. If the encoding is not -an C Encoding object, bad things will happen. -(See F and L). - -The PV of the sv is returned. - - char* sv_recode_to_utf8(SV* sv, SV *encoding) - -=for hackers -Found in file sv.c - =item sv_reftype Returns a string describing what the SV is a reference to. @@ -3847,25 +4237,6 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c -=item sv_setpviv - -Copies an integer into the given SV, also updating its string value. -Does not handle 'set' magic. See C. - - void sv_setpviv(SV* sv, IV num) - -=for hackers -Found in file sv.c - -=item sv_setpviv_mg - -Like C, but also handles 'set' magic. - - void sv_setpviv_mg(SV *sv, IV iv) - -=for hackers -Found in file sv.c - =item sv_setpvn Copies a string into an SV. The C parameter indicates the number of @@ -3980,7 +4351,6 @@ You probably want to use one of the assortment of wrappers, such as C, C, C and C. - void sv_setsv(SV* dsv, SV* ssv) =for hackers @@ -4064,19 +4434,6 @@ instead use an in-line version. =for hackers Found in file sv.c -=item sv_uni_display - -Build to the scalar dsv a displayable version of the scalar sv, -he displayable version being at most pvlim bytes long -(if longer, the rest is truncated and "..." will be appended). -The flags argument is currently unused but available for future extensions. -The pointer to the PV of the dsv is returned. - - char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) - -=for hackers -Found in file utf8.c - =item sv_unmagic Removes all magic of type C from an SV. @@ -4177,6 +4534,9 @@ This may not be possible if the PV contains non-byte encoding characters; if this is the case, either returns false or, if C is not true, croaks. +This is not as a general purpose Unicode to byte encoding interface: +use the Encode extension for that. + NOTE: this function is experimental and may change or be removed without notice. @@ -4203,6 +4563,9 @@ Forces the SV to string form if it is not already. Always sets the SvUTF8 flag to avoid future validity checks even if all the bytes have hibit clear. +This is not as a general purpose byte encoding to Unicode interface: +use the Encode extension for that. + STRLEN sv_utf8_upgrade(SV *sv) =for hackers @@ -4217,6 +4580,9 @@ if all the bytes have hibit clear. If C has C bit set, will C on C if appropriate, else not. C and C are implemented in terms of this function. +This is not as a general purpose byte encoding to Unicode interface: +use the Encode extension for that. + STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags) =for hackers @@ -4247,68 +4613,321 @@ Usually used via one of its frontends C and C. =for hackers Found in file sv.c -=item sv_vsetpvfn +=item sv_vsetpvfn + +Works like C but copies the text into the SV instead of +appending it. + +Usually used via one of its frontends C and C. + + void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) + +=for hackers +Found in file sv.c + +=item upg_version + +In-place upgrade of the supplied SV to a version object. + + SV *sv = upg_version(SV *sv); + +Returns a pointer to the upgraded SV. + + SV* upg_version(SV *ver) + +=for hackers +Found in file util.c + +=item vcmp + +Version object aware cmp. Both operands must already have been +converted into version objects. + + int vcmp(SV *lvs, SV *rvs) + +=for hackers +Found in file util.c + +=item vnumify + +Accepts a version object and returns the normalized floating +point representation. Call like: + + sv = vnumify(rv); + +NOTE: you can pass either the object directly or the SV +contained within the RV. + + SV* vnumify(SV *vs) + +=for hackers +Found in file util.c + +=item vstringify + +Accepts a version object and returns the normalized string +representation. Call like: + + sv = vstringify(rv); + +NOTE: you can pass either the object directly or the SV +contained within the RV. + + SV* vstringify(SV *vs) + +=for hackers +Found in file util.c + + +=back + +=head1 Unicode Support + +=over 8 + +=item bytes_from_utf8 + +Converts a string C of length C from UTF8 into byte encoding. +Unlike but like C, returns a pointer to +the newly-created string, and updates C to contain the new +length. Returns the original string if no conversion occurs, C +is unchanged. Do nothing if C points to 0. Sets C to +0 if C is converted or contains all 7bit characters. + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8) + +=for hackers +Found in file utf8.c + +=item bytes_to_utf8 + +Converts a string C of length C from ASCII into UTF8 encoding. +Returns a pointer to the newly-created string, and sets C to +reflect the new length. + +If you want to convert to UTF8 from other encodings than ASCII, +see sv_recode_to_utf8(). + +NOTE: this function is experimental and may change or be +removed without notice. + + U8* bytes_to_utf8(U8 *s, STRLEN *len) + +=for hackers +Found in file utf8.c + +=item ibcmp_utf8 + +Return true if the strings s1 and s2 differ case-insensitively, false +if not (if they are equal case-insensitively). If u1 is true, the +string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, +the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2 +are false, the respective string is assumed to be in native 8-bit +encoding. + +If the pe1 and pe2 are non-NULL, the scanning pointers will be copied +in there (they will point at the beginning of the I character). +If the pointers behind pe1 or pe2 are non-NULL, they are the end +pointers beyond which scanning will not continue under any +circustances. If the byte lengths l1 and l2 are non-zero, s1+l1 and +s2+l2 will be used as goal end pointers that will also stop the scan, +and which qualify towards defining a successful match: all the scans +that define an explicit length must reach their goal pointers for +a match to succeed). + +For case-insensitiveness, the "casefolding" of Unicode is used +instead of upper/lowercasing both the characters, see +http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). + + I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2) + +=for hackers +Found in file utf8.c + +=item is_utf8_char + +Tests if some arbitrary number of bytes begins in a valid UTF-8 +character. Note that an INVARIANT (i.e. ASCII) character is a valid +UTF-8 character. The actual number of bytes in the UTF-8 character +will be returned if it is valid, otherwise 0. + + STRLEN is_utf8_char(U8 *p) + +=for hackers +Found in file utf8.c + +=item is_utf8_string + +Returns true if first C bytes of the given string form a valid +UTF8 string, false otherwise. Note that 'a valid UTF8 string' does +not mean 'a string that contains code points above 0x7F encoded in +UTF8' because a valid ASCII string is a valid UTF8 string. + + bool is_utf8_string(U8 *s, STRLEN len) + +=for hackers +Found in file utf8.c + +=item pv_uni_display + +Build to the scalar dsv a displayable version of the string spv, +length len, the displayable version being at most pvlim bytes long +(if longer, the rest is truncated and "..." will be appended). + +The flags argument can have UNI_DISPLAY_ISPRINT set to display +isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH +to display the \\[nrfta\\] as the backslashed versions (like '\n') +(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). +UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both +UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on. + +The pointer to the PV of the dsv is returned. + + char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags) + +=for hackers +Found in file utf8.c + +=item sv_cat_decode + +The encoding is assumed to be an Encode object, the PV of the ssv is +assumed to be octets in that encoding and decoding the input starts +from the position which (PV + *offset) pointed to. The dsv will be +concatenated the decoded UTF-8 string from ssv. Decoding will terminate +when the string tstr appears in decoding output or the input ends on +the PV of the ssv. The value which the offset points will be modified +to the last input position on the ssv. + +Returns TRUE if the terminator was found, else returns FALSE. + + bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen) + +=for hackers +Found in file sv.c + +=item sv_recode_to_utf8 + +The encoding is assumed to be an Encode object, on entry the PV +of the sv is assumed to be octets in that encoding, and the sv +will be converted into Unicode (and UTF-8). + +If the sv already is UTF-8 (or if it is not POK), or if the encoding +is not a reference, nothing is done to the sv. If the encoding is not +an C Encoding object, bad things will happen. +(See F and L). + +The PV of the sv is returned. + + char* sv_recode_to_utf8(SV* sv, SV *encoding) + +=for hackers +Found in file sv.c + +=item sv_uni_display + +Build to the scalar dsv a displayable version of the scalar sv, +the displayable version being at most pvlim bytes long +(if longer, the rest is truncated and "..." will be appended). + +The flags argument is as in pv_uni_display(). + +The pointer to the PV of the dsv is returned. + + char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) + +=for hackers +Found in file utf8.c + +=item to_utf8_case -Works like C but copies the text into the SV instead of -appending it. +The "p" contains the pointer to the UTF-8 string encoding +the character that is being converted. -Usually used via one of its frontends C and C. +The "ustrp" is a pointer to the character buffer to put the +conversion result to. The "lenp" is a pointer to the length +of the result. - void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted) +The "swashp" is a pointer to the swash to use. -=for hackers -Found in file sv.c +Both the special and normal mappings are stored lib/unicore/To/Foo.pl, +and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually, +but not always, a multicharacter mapping), is tried first. -=item THIS +The "special" is a string like "utf8::ToSpecLower", which means the +hash %utf8::ToSpecLower. The access to the hash is through +Perl_to_utf8_case(). -Variable which is setup by C to designate the object in a C++ -XSUB. This is always the proper type for the C++ object. See C and -L. +The "normal" is a string like "ToLower" which means the swash +%utf8::ToLower. - (whatever) THIS + UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special) =for hackers -Found in file XSUB.h +Found in file utf8.c -=item toLOWER +=item to_utf8_fold -Converts the specified character to lowercase. +Convert the UTF-8 encoded character at p to its foldcase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the +foldcase version may be longer than the original character (up to +three characters). - char toLOWER(char ch) +The first character of the foldcased version is returned +(but note, as explained above, that there may be more.) + + UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp) =for hackers -Found in file handy.h +Found in file utf8.c -=item toUPPER +=item to_utf8_lower -Converts the specified character to uppercase. +Convert the UTF-8 encoded character at p to its lowercase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the +lowercase version may be longer than the original character (up to two +characters). - char toUPPER(char ch) +The first character of the lowercased version is returned +(but note, as explained above, that there may be more.) + + UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp) =for hackers -Found in file handy.h +Found in file utf8.c -=item to_utf8_case +=item to_utf8_title -The "p" contains the pointer to the UTF-8 string encoding -the character that is being converted. +Convert the UTF-8 encoded character at p to its titlecase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the +titlecase version may be longer than the original character (up to two +characters). -The "ustrp" is a pointer to the character buffer to put the -conversion result to. The "lenp" is a pointer to the length -of the result. +The first character of the titlecased version is returned +(but note, as explained above, that there may be more.) -The "swash" is a pointer to the swash to use. + UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp) -The "normal" is a string like "ToLower" which means the swash -$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl, -and loaded by SWASHGET, using lib/utf8_heavy.pl. +=for hackers +Found in file utf8.c -The "special" is a string like "utf8::ToSpecLower", which means -the hash %utf8::ToSpecLower, which is stored in the same file, -lib/unicore/To/Lower.pl, and also loaded by SWASHGET. The access -to the hash is by Perl_to_utf8_case(). +=item to_utf8_upper - UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special) +Convert the UTF-8 encoded character at p to its uppercase version and +store that in UTF-8 in ustrp and its length in bytes in lenp. Note +that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the +uppercase version may be longer than the original character (up to two +characters). + +The first character of the uppercased version is returned +(but note, as explained above, that there may be more.) + + UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp) =for hackers Found in file utf8.c @@ -4479,205 +5098,148 @@ is the recommended Unicode-aware way of saying =for hackers Found in file utf8.c -=item warn - -This is the XSUB-writer's interface to Perl's C function. Use this -function the same way you use the C C function. See -C. - - void warn(const char* pat, ...) - -=for hackers -Found in file util.c - -=item XPUSHi - -Push an integer onto the stack, extending the stack if necessary. Handles -'set' magic. See C. - - void XPUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item XPUSHn - -Push a double onto the stack, extending the stack if necessary. Handles -'set' magic. See C. - - void XPUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item XPUSHp - -Push a string onto the stack, extending the stack if necessary. The C -indicates the length of the string. Handles 'set' magic. See -C. - - void XPUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item XPUSHs - -Push an SV onto the stack, extending the stack if necessary. Does not -handle 'set' magic. See C. - - void XPUSHs(SV* sv) - -=for hackers -Found in file pp.h -=item XPUSHu +=back -Push an unsigned integer onto the stack, extending the stack if necessary. -See C. +=head1 Variables created by C and C internal functions - void XPUSHu(UV uv) +=over 8 -=for hackers -Found in file pp.h +=item ax -=item XS +Variable which is setup by C to indicate the stack base offset, +used by the C, C and C macros. The C macro +must be called prior to setup the C variable. -Macro to declare an XSUB and its C parameter list. This is handled by -C. + I32 ax =for hackers Found in file XSUB.h -=item XSRETURN +=item CLASS -Return from XSUB, indicating number of items on the stack. This is usually -handled by C. +Variable which is setup by C to indicate the +class name for a C++ XS constructor. This is always a C. See C. - void XSRETURN(int nitems) + char* CLASS =for hackers Found in file XSUB.h -=item XSRETURN_EMPTY +=item dAX -Return an empty list from an XSUB immediately. +Sets up the C variable. +This is usually handled automatically by C by calling C. - XSRETURN_EMPTY; + dAX; =for hackers Found in file XSUB.h -=item XSRETURN_IV +=item dITEMS -Return an integer from an XSUB immediately. Uses C. +Sets up the C variable. +This is usually handled automatically by C by calling C. - void XSRETURN_IV(IV iv) + dITEMS; =for hackers Found in file XSUB.h -=item XSRETURN_NO +=item dXSARGS -Return C<&PL_sv_no> from an XSUB immediately. Uses C. +Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. +Sets up the C and C variables by calling C and C. +This is usually handled automatically by C. - XSRETURN_NO; + dXSARGS; =for hackers Found in file XSUB.h -=item XSRETURN_NV +=item dXSI32 -Return a double from an XSUB immediately. Uses C. +Sets up the C variable for an XSUB which has aliases. This is usually +handled automatically by C. - void XSRETURN_NV(NV nv) + dXSI32; =for hackers Found in file XSUB.h -=item XSRETURN_PV +=item items -Return a copy of a string from an XSUB immediately. Uses C. +Variable which is setup by C to indicate the number of +items on the stack. See L. - void XSRETURN_PV(char* str) + I32 items =for hackers Found in file XSUB.h -=item XSRETURN_UNDEF +=item ix -Return C<&PL_sv_undef> from an XSUB immediately. Uses C. +Variable which is setup by C to indicate which of an +XSUB's aliases was used to invoke it. See L. - XSRETURN_UNDEF; + I32 ix =for hackers Found in file XSUB.h -=item XSRETURN_YES - -Return C<&PL_sv_yes> from an XSUB immediately. Uses C. +=item newXSproto - XSRETURN_YES; +Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to +the subs. =for hackers Found in file XSUB.h -=item XST_mIV +=item RETVAL -Place an integer into the specified position C on the stack. The -value is stored in a new mortal SV. +Variable which is setup by C to hold the return value for an +XSUB. This is always the proper type for the XSUB. See +L. - void XST_mIV(int pos, IV iv) + (whatever) RETVAL =for hackers Found in file XSUB.h -=item XST_mNO +=item ST -Place C<&PL_sv_no> into the specified position C on the -stack. +Used to access elements on the XSUB's stack. - void XST_mNO(int pos) + SV* ST(int ix) =for hackers Found in file XSUB.h -=item XST_mNV +=item THIS -Place a double into the specified position C on the stack. The value -is stored in a new mortal SV. +Variable which is setup by C to designate the object in a C++ +XSUB. This is always the proper type for the C++ object. See C and +L. - void XST_mNV(int pos, NV nv) + (whatever) THIS =for hackers Found in file XSUB.h -=item XST_mPV - -Place a copy of a string into the specified position C on the stack. -The value is stored in a new mortal SV. +=item XS - void XST_mPV(int pos, char* str) +Macro to declare an XSUB and its C parameter list. This is handled by +C. =for hackers Found in file XSUB.h -=item XST_mUNDEF - -Place C<&PL_sv_undef> into the specified position C on the -stack. - - void XST_mUNDEF(int pos) - -=for hackers -Found in file XSUB.h +=item XSRETURN_EMPTY -=item XST_mYES +Return an empty list from an XSUB immediately. -Place C<&PL_sv_yes> into the specified position C on the -stack. - void XST_mYES(int pos) + XSRETURN_EMPTY; =for hackers Found in file XSUB.h @@ -4701,15 +5263,42 @@ C. See L. =for hackers Found in file XSUB.h -=item Zero -The XSUB-writer's interface to the C C function. The C is the -destination, C is the number of items, and C is the type. +=back - void Zero(void* dest, int nitems, type) +=head1 Warning and Dieing + +=over 8 + +=item croak + +This is the XSUB-writer's interface to Perl's C function. +Normally use this function the same way you use the C C +function. See C. + +If you want to throw an exception object, assign the object to +C<$@> and then pass C to croak(): + + errsv = get_sv("@", TRUE); + sv_setsv(errsv, exception_object); + croak(Nullch); + + void croak(const char* pat, ...) =for hackers -Found in file handy.h +Found in file util.c + +=item warn + +This is the XSUB-writer's interface to Perl's C function. Use this +function the same way you use the C C function. See +C. + + void warn(const char* pat, ...) + +=for hackers +Found in file util.c + =back