X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=d608eef3c3c4003d765c503c95a60edf5a1de671;hb=77004dee2553ce034a8a58b2b2849e3656df46c3;hp=a915892a01169a2cb162426ea02264bc839a6421;hpb=8f42b153a33e87e34587f52f491b24c52b63b818;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index a915892..d608eef 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -3,6 +3,7 @@ perlapi - autogenerated documentation for the perl public API =head1 DESCRIPTION +X X X This file contains the documentation of the perl public API generated by embed.pl, specifically a listing of functions, macros, flags, and variables @@ -23,6 +24,7 @@ The listing is alphabetical, case insensitive. =over 8 =item GIMME +X A backward-compatible version of C which can only return C or C; in a void context, it returns C. @@ -34,6 +36,7 @@ Deprecated. Use C instead. Found in file op.h =item GIMME_V +X The XSUB-writer's equivalent to Perl's C. Returns C, C or C for void, scalar or list context, @@ -45,6 +48,7 @@ respectively. Found in file op.h =item G_ARRAY +X Used to indicate list context. See C, C and L. @@ -53,6 +57,7 @@ L. Found in file cop.h =item G_DISCARD +X Indicates that arguments returned from a callback should be discarded. See L. @@ -61,6 +66,7 @@ L. Found in file cop.h =item G_EVAL +X Used to force a Perl C wrapper around a callback. See L. @@ -69,6 +75,7 @@ L. Found in file cop.h =item G_NOARGS +X Indicates that no arguments are being sent to a callback. See L. @@ -77,6 +84,7 @@ L. Found in file cop.h =item G_SCALAR +X Used to indicate scalar context. See C, C, and L. @@ -85,6 +93,7 @@ L. Found in file cop.h =item G_VOID +X Used to indicate void context. See C and L. @@ -99,6 +108,7 @@ Found in file cop.h =over 8 =item AvFILL +X Same as C. Deprecated, use C instead. @@ -108,6 +118,7 @@ Same as C. Deprecated, use C instead. Found in file av.h =item av_clear +X Clears an array, making it empty. Does not free the memory used by the array itself. @@ -118,6 +129,7 @@ array itself. Found in file av.c =item av_delete +X Deletes the element indexed by C from the array. Returns the deleted element. If C equals C, the element is freed @@ -129,6 +141,7 @@ and null is returned. Found in file av.c =item av_exists +X Returns true if the element indexed by C has been initialized. @@ -141,6 +154,7 @@ C<&PL_sv_undef>. Found in file av.c =item av_extend +X Pre-extend an array. The C is the index to which the array should be extended. @@ -151,6 +165,7 @@ extended. Found in file av.c =item av_fetch +X Returns the SV at the specified index in the array. The C is the index. If C is set then the fetch will be part of a store. Check @@ -165,6 +180,7 @@ more information on how to use this function on tied arrays. Found in file av.c =item av_fill +X Ensure than an array has a given number of elements, equivalent to Perl's C<$#array = $fill;>. @@ -175,6 +191,7 @@ Perl's C<$#array = $fill;>. Found in file av.c =item av_len +X Returns the highest index in the array. Returns -1 if the array is empty. @@ -185,6 +202,7 @@ empty. Found in file av.c =item av_make +X Creates a new AV and populates it with a list of SVs. The SVs are copied into the array, so they may be freed after the call to av_make. The new AV @@ -196,6 +214,7 @@ will have a reference count of 1. Found in file av.c =item av_pop +X Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array is empty. @@ -206,6 +225,7 @@ is empty. Found in file av.c =item av_push +X Pushes an SV onto the end of the array. The array will grow automatically to accommodate the addition. @@ -216,6 +236,7 @@ to accommodate the addition. Found in file av.c =item av_shift +X Shifts an SV off the beginning of the array. @@ -225,6 +246,7 @@ Shifts an SV off the beginning of the array. Found in file av.c =item av_store +X Stores an SV in an array. The array index is specified as C. The return value will be NULL if the operation failed or if the value did not @@ -243,6 +265,7 @@ more information on how to use this function on tied arrays. Found in file av.c =item av_undef +X Undefines the array. Frees the memory used by the array itself. @@ -252,6 +275,7 @@ Undefines the array. Frees the memory used by the array itself. Found in file av.c =item av_unshift +X Unshift the given number of C values onto the beginning of the array. The array will grow automatically to accommodate the addition. You @@ -263,6 +287,7 @@ must then use C to assign values to these new elements. Found in file av.c =item get_av +X 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 @@ -276,6 +301,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item newAV +X Creates a new AV. The reference count is set to 1. @@ -285,14 +311,26 @@ Creates a new AV. The reference count is set to 1. Found in file av.c =item sortsv +X Sort an array. Here is an example: sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); -See lib/sort.pm for details about controlling the sorting algorithm. +Currently this always uses mergesort. See sortsv_flags for a more +flexible routine. - void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) + void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp) + +=for hackers +Found in file pp_sort.c + +=item sortsv_flags +X + +Sort an array, with various options. + + void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags) =for hackers Found in file pp_sort.c @@ -305,6 +343,7 @@ Found in file pp_sort.c =over 8 =item call_argv +X Performs a callback to the specified Perl sub. See L. @@ -316,6 +355,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item call_method +X Performs a callback to the specified Perl method. The blessed object must be on the stack. See L. @@ -328,6 +368,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item call_pv +X Performs a callback to the specified Perl sub. See L. @@ -339,6 +380,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item call_sv +X Performs a callback to the Perl sub whose name is in the SV. See L. @@ -351,6 +393,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item ENTER +X Opening bracket on a callback. See C and L. @@ -360,6 +403,7 @@ Opening bracket on a callback. See C and L. Found in file scope.h =item eval_pv +X Tells Perl to C the given string and return an SV* result. @@ -371,6 +415,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item eval_sv +X Tells Perl to C the string in the SV. @@ -382,6 +427,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item FREETMPS +X Closing bracket for temporaries on a callback. See C and L. @@ -392,6 +438,7 @@ L. Found in file scope.h =item LEAVE +X Closing bracket on a callback. See C and L. @@ -401,6 +448,7 @@ Closing bracket on a callback. See C and L. Found in file scope.h =item SAVETMPS +X Opening bracket for temporaries on a callback. See C and L. @@ -418,6 +466,7 @@ Found in file scope.h =over 8 =item isALNUM +X Returns a boolean indicating whether the C C is an ASCII alphanumeric character (including underscore) or digit. @@ -428,6 +477,7 @@ character (including underscore) or digit. Found in file handy.h =item isALPHA +X Returns a boolean indicating whether the C C is an ASCII alphabetic character. @@ -438,6 +488,7 @@ character. Found in file handy.h =item isDIGIT +X Returns a boolean indicating whether the C C is an ASCII digit. @@ -448,6 +499,7 @@ digit. Found in file handy.h =item isLOWER +X Returns a boolean indicating whether the C C is a lowercase character. @@ -458,6 +510,7 @@ character. Found in file handy.h =item isSPACE +X Returns a boolean indicating whether the C C is whitespace. @@ -467,6 +520,7 @@ Returns a boolean indicating whether the C C is whitespace. Found in file handy.h =item isUPPER +X Returns a boolean indicating whether the C C is an uppercase character. @@ -477,6 +531,7 @@ character. Found in file handy.h =item toLOWER +X Converts the specified character to lowercase. @@ -486,6 +541,7 @@ Converts the specified character to lowercase. Found in file handy.h =item toUPPER +X Converts the specified character to uppercase. @@ -502,6 +558,7 @@ Found in file handy.h =over 8 =item perl_clone +X Create and return a new interpreter by cloning the current one. @@ -547,6 +604,7 @@ Found in file sv.c =over 8 =item CvSTASH +X Returns the stash of the CV. @@ -556,6 +614,7 @@ Returns the stash of the CV. Found in file cv.h =item get_cv +X 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 @@ -577,6 +636,7 @@ Found in file perl.c =over 8 =item cv_undef +X 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. @@ -589,6 +649,7 @@ children can still follow the full lexical scope chain. Found in file op.c =item load_module +X 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. @@ -605,6 +666,7 @@ method, similar to C. Found in file op.c =item nothreadhook +X Stub that provides thread hook for perl_destruct when there are no threads. @@ -615,6 +677,7 @@ no threads. Found in file perl.c =item perl_alloc +X Allocates a new Perl interpreter. See L. @@ -624,6 +687,7 @@ Allocates a new Perl interpreter. See L. Found in file perl.c =item perl_construct +X Initializes a new Perl interpreter. See L. @@ -633,6 +697,7 @@ Initializes a new Perl interpreter. See L. Found in file perl.c =item perl_destruct +X Shuts down a Perl interpreter. See L. @@ -642,6 +707,7 @@ Shuts down a Perl interpreter. See L. Found in file perl.c =item perl_free +X Releases a Perl interpreter. See L. @@ -651,6 +717,7 @@ Releases a Perl interpreter. See L. Found in file perl.c =item perl_parse +X Tells a Perl interpreter to parse a Perl script. See L. @@ -660,6 +727,7 @@ Tells a Perl interpreter to parse a Perl script. See L. Found in file perl.c =item perl_run +X Tells a Perl interpreter to run. See L. @@ -669,6 +737,7 @@ Tells a Perl interpreter to run. See L. Found in file perl.c =item require_pv +X Tells Perl to C the file named by the string argument. It is analogous to the Perl code C. It's even @@ -684,47 +753,307 @@ Found in file perl.c =back -=head1 Functions in file pp_pack.c +=head1 Functions in file mathoms.c =over 8 -=item packlist +=item gv_fetchmethod +X -The engine implementing pack() Perl function. +See L. - void packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist) + GV* gv_fetchmethod(HV* stash, const char* name) =for hackers -Found in file pp_pack.c +Found in file mathoms.c =item pack_cat +X The engine implementing pack() Perl function. Note: parameters next_in_list and flags are not used. This call should not be used; use packlist instead. - void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) + void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) =for hackers -Found in file pp_pack.c +Found in file mathoms.c -=item unpackstring +=item sv_2pvbyte_nolen +X -The engine implementing unpack() Perl function. C puts the -extracted list items on the stack and returns the number of elements. -Issue C before and C after the call to this function. +Return a pointer to the byte-encoded representation of the SV. +May cause the SV to be downgraded from UTF-8 as a side-effect. + +Usually accessed via the C macro. - I32 unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags) + char* sv_2pvbyte_nolen(SV* sv) =for hackers -Found in file pp_pack.c +Found in file mathoms.c + +=item sv_2pvutf8_nolen +X + +Return a pointer to the UTF-8-encoded representation of the SV. +May cause the SV to be upgraded to UTF-8 as a side-effect. + +Usually accessed via the C macro. + + char* sv_2pvutf8_nolen(SV* sv) + +=for hackers +Found in file mathoms.c + +=item sv_2pv_nolen +X + +Like C, but doesn't return the length too. You should usually +use the macro wrapper C instead. + char* sv_2pv_nolen(SV* sv) + +=for hackers +Found in file mathoms.c + +=item sv_catpvn_mg +X + +Like C, but also handles 'set' magic. + + void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) + +=for hackers +Found in file mathoms.c + +=item sv_catsv_mg +X + +Like C, but also handles 'set' magic. + + void sv_catsv_mg(SV *dstr, SV *sstr) + +=for hackers +Found in file mathoms.c + +=item sv_force_normal +X + +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. See also C. + + void sv_force_normal(SV *sv) + +=for hackers +Found in file mathoms.c + +=item sv_iv +X + +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. + + IV sv_iv(SV* sv) + +=for hackers +Found in file mathoms.c + +=item sv_nolocking +X + +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. + +"Superseded" by sv_nosharing(). + + void sv_nolocking(SV *sv) + +=for hackers +Found in file mathoms.c + +=item sv_nounlocking +X + +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. + +"Superseded" by sv_nosharing(). + + void sv_nounlocking(SV *sv) + +=for hackers +Found in file mathoms.c + +=item sv_nv +X + +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. + + NV sv_nv(SV* sv) + +=for hackers +Found in file mathoms.c + +=item sv_pv +X + +Use the C macro instead + + char* sv_pv(SV *sv) + +=for hackers +Found in file mathoms.c + +=item sv_pvbyte +X + +Use C instead. + + char* sv_pvbyte(SV *sv) + +=for hackers +Found in file mathoms.c + +=item sv_pvbyten +X + +A private implementation of the C macro for compilers +which can't cope with complex macro expressions. Always use the macro +instead. + + char* sv_pvbyten(SV *sv, STRLEN *len) + +=for hackers +Found in file mathoms.c + +=item sv_pvn +X + +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. + + char* sv_pvn(SV *sv, STRLEN *len) + +=for hackers +Found in file mathoms.c + +=item sv_pvutf8 +X + +Use the C macro instead + + char* sv_pvutf8(SV *sv) + +=for hackers +Found in file mathoms.c + +=item sv_pvutf8n +X + +A private implementation of the C macro for compilers +which can't cope with complex macro expressions. Always use the macro +instead. + + char* sv_pvutf8n(SV *sv, STRLEN *len) + +=for hackers +Found in file mathoms.c + +=item sv_taint +X + +Taint an SV. Use C instead. + void sv_taint(SV* sv) + +=for hackers +Found in file mathoms.c + +=item sv_unref +X + +Unsets the RV status of the SV, and decrements the reference count of +whatever was being referenced by the RV. This can almost be thought of +as a reversal of C. This is C with the C +being zero. See C. + + void sv_unref(SV* sv) + +=for hackers +Found in file mathoms.c + +=item sv_usepvn +X + +Tells an SV to use C to find its string value. Implemented by +calling C with C of 0, hence does not handle 'set' +magic. See C. + + void sv_usepvn(SV* sv, char* ptr, STRLEN len) + +=for hackers +Found in file mathoms.c + +=item sv_usepvn_mg +X + +Like C, but also handles 'set' magic. + + void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) + +=for hackers +Found in file mathoms.c + +=item sv_uv +X + +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. + + UV sv_uv(SV* sv) + +=for hackers +Found in file mathoms.c =item unpack_str +X The engine implementing unpack() Perl function. Note: parameters strbeg, new_s and ocnt are not used. This call should not be used, use unpackstring instead. - I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags) + I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags) + +=for hackers +Found in file mathoms.c + + +=back + +=head1 Functions in file pp_pack.c + + +=over 8 + +=item packlist +X + +The engine implementing pack() Perl function. + + void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist) + +=for hackers +Found in file pp_pack.c + +=item unpackstring +X + +The engine implementing unpack() Perl function. C puts the +extracted list items on the stack and returns the number of elements. +Issue C before and C after the call to this function. + + I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags) =for hackers Found in file pp_pack.c @@ -737,6 +1066,7 @@ Found in file pp_pack.c =over 8 =item PL_modglobal +X C is a general purpose, interpreter global HV for use by extensions that need to keep information on a per-interpreter basis. @@ -750,6 +1080,7 @@ prefixed by the package name of the extension that owns the data. Found in file intrpvar.h =item PL_na +X 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 @@ -762,6 +1093,7 @@ C macro. Found in file thrdvar.h =item PL_sv_no +X This is the C SV. See C. Always refer to this as C<&PL_sv_no>. @@ -772,6 +1104,7 @@ C<&PL_sv_no>. Found in file intrpvar.h =item PL_sv_undef +X This is the C SV. Always refer to this as C<&PL_sv_undef>. @@ -781,6 +1114,7 @@ This is the C SV. Always refer to this as C<&PL_sv_undef>. Found in file intrpvar.h =item PL_sv_yes +X This is the C SV. See C. Always refer to this as C<&PL_sv_yes>. @@ -798,6 +1132,7 @@ Found in file intrpvar.h =over 8 =item GvSV +X Return the SV from the GV. @@ -806,7 +1141,21 @@ Return the SV from the GV. =for hackers Found in file gv.h +=item gv_const_sv +X + +If C is a typeglob whose subroutine entry is a constant sub eligible for +inlining, or C is a placeholder reference that would be promoted to such +a typeglob, then returns the value returned by the sub. Otherwise, returns +NULL. + + SV* gv_const_sv(GV* gv) + +=for hackers +Found in file gv.c + =item gv_fetchmeth +X Returns the glob with the given C and a defined subroutine or C. The glob lives in the given C, or in the stashes @@ -828,16 +1177,8 @@ obtained from the GV with the C macro. =for hackers Found in file gv.c -=item gv_fetchmethod - -See L. - - GV* gv_fetchmethod(HV* stash, const char* name) - -=for hackers -Found in file gv.c - =item gv_fetchmethod_autoload +X Returns the glob which contains the subroutine to call to invoke the method on the C. In fact in the presence of autoloading this may be the @@ -867,6 +1208,7 @@ C apply equally to these functions. Found in file gv.c =item gv_fetchmeth_autoload +X Same as gv_fetchmeth(), but looks for autoloaded subroutines too. Returns a glob for the subroutine. @@ -881,6 +1223,7 @@ of the result may be zero. Found in file gv.c =item gv_stashpv +X Returns a pointer to the stash for a specified package. C should be a valid UTF-8 string and must be null-terminated. If C is set @@ -893,6 +1236,7 @@ is not set and the package does not exist then NULL is returned. Found in file gv.c =item gv_stashpvn +X Returns a pointer to the stash for a specified package. C should be a valid UTF-8 string. The C parameter indicates the length of @@ -906,6 +1250,7 @@ package does not exist then NULL is returned. Found in file gv.c =item gv_stashsv +X Returns a pointer to the stash for a specified package, which must be a valid UTF-8 string. See C. @@ -923,6 +1268,7 @@ Found in file gv.c =over 8 =item Nullav +X Null AV pointer. @@ -930,6 +1276,7 @@ Null AV pointer. Found in file av.h =item Nullch +X Null character pointer. @@ -937,6 +1284,7 @@ Null character pointer. Found in file handy.h =item Nullcv +X Null CV pointer. @@ -944,6 +1292,7 @@ Null CV pointer. Found in file cv.h =item Nullhv +X Null HV pointer. @@ -951,6 +1300,7 @@ Null HV pointer. Found in file hv.h =item Nullsv +X Null SV pointer. @@ -965,6 +1315,7 @@ Found in file handy.h =over 8 =item get_hv +X 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 @@ -978,6 +1329,7 @@ NOTE: the perl_ form of this function is deprecated. Found in file perl.c =item HEf_SVKEY +X This flag, used in the length slot of hash entries and magic structures, specifies the structure contains an C pointer where a C pointer @@ -987,6 +1339,7 @@ is to be expected. (For information only--not to be used). Found in file hv.h =item HeHASH +X Returns the computed hash stored in the hash entry. @@ -996,6 +1349,7 @@ Returns the computed hash stored in the hash entry. Found in file hv.h =item HeKEY +X Returns the actual pointer stored in the key slot of the hash entry. The pointer may be either C or C, depending on the value of @@ -1008,6 +1362,7 @@ usually preferable for finding the value of a key. Found in file hv.h =item HeKLEN +X If this is negative, and amounts to C, it indicates the entry holds an C key. Otherwise, holds the actual length of the key. Can @@ -1020,6 +1375,7 @@ lengths. Found in file hv.h =item HePV +X Returns the key slot of the hash entry as a C value, doing any necessary dereferencing of possibly C keys. The length of the string @@ -1037,8 +1393,9 @@ described elsewhere in this document. Found in file hv.h =item HeSVKEY +X -Returns the key as an C, or C if the hash entry does not +Returns the key as an C, or C if the hash entry does not contain an C key. SV* HeSVKEY(HE* he) @@ -1047,6 +1404,7 @@ contain an C key. Found in file hv.h =item HeSVKEY_force +X Returns the key as an C. Will create and return a temporary mortal C if the hash entry contains only a C key. @@ -1057,6 +1415,7 @@ C if the hash entry contains only a C key. Found in file hv.h =item HeSVKEY_set +X Sets the key to a given C, taking care to set the appropriate flags to indicate the presence of an C key, and returns the same @@ -1068,6 +1427,7 @@ C. Found in file hv.h =item HeVAL +X Returns the value slot (type C) stored in the hash entry. @@ -1077,8 +1437,10 @@ Returns the value slot (type C) stored in the hash entry. Found in file hv.h =item HvNAME +X -Returns the package name of a stash. See C, C. +Returns the package name of a stash, or NULL if C isn't a stash. +See C, C. char* HvNAME(HV* stash) @@ -1086,6 +1448,7 @@ Returns the package name of a stash. See C, C. Found in file hv.h =item hv_assert +X Check that a hash is in an internally consistent state. @@ -1095,6 +1458,7 @@ Check that a hash is in an internally consistent state. Found in file hv.c =item hv_clear +X Clears a hash, making it empty. @@ -1104,6 +1468,7 @@ Clears a hash, making it empty. Found in file hv.c =item hv_clear_placeholders +X Clears any placeholders from a hash. If a restricted hash has any of its keys marked as readonly and the key is subsequently deleted, the key is not actually @@ -1119,6 +1484,7 @@ See Hash::Util::lock_keys() for an example of its use. Found in file hv.c =item hv_delete +X Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The C is the length of the key. @@ -1131,6 +1497,7 @@ will be returned. Found in file hv.c =item hv_delete_ent +X Deletes a key/value pair in the hash. The value SV is removed from the hash and returned to the caller. The C value will normally be zero; @@ -1143,6 +1510,7 @@ precomputed hash value, or 0 to ask for it to be computed. Found in file hv.c =item hv_exists +X Returns a boolean indicating whether the specified hash key exists. The C is the length of the key. @@ -1153,6 +1521,7 @@ C is the length of the key. Found in file hv.c =item hv_exists_ent +X Returns a boolean indicating whether the specified hash key exists. C can be a valid precomputed hash value, or 0 to ask for it to be @@ -1164,6 +1533,7 @@ computed. Found in file hv.c =item hv_fetch +X Returns the SV which corresponds to the specified key in the hash. The C is the length of the key. If C is set then the fetch will be @@ -1179,6 +1549,7 @@ information on how to use this function on tied hashes. Found in file hv.c =item hv_fetch_ent +X Returns the hash entry which corresponds to the specified key in the hash. C must be a valid precomputed hash number for the given C, or 0 @@ -1197,6 +1568,7 @@ information on how to use this function on tied hashes. Found in file hv.c =item hv_iterinit +X 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 @@ -1213,6 +1585,7 @@ value, you can get it through the macro C. Found in file hv.c =item hv_iterkey +X Returns the key from the current position of the hash iterator. See C. @@ -1223,6 +1596,7 @@ C. Found in file hv.c =item hv_iterkeysv +X 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 @@ -1234,6 +1608,7 @@ see C. Found in file hv.c =item hv_iternext +X Returns entries from a hash iterator. See C. @@ -1251,6 +1626,7 @@ trigger the resource deallocation. Found in file hv.c =item hv_iternextsv +X Performs an C, C, and C in one operation. @@ -1261,6 +1637,7 @@ operation. Found in file hv.c =item hv_iternext_flags +X Returns entries from a hash iterator. See C and C. The C value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is @@ -1280,6 +1657,7 @@ removed without notice. Found in file hv.c =item hv_iterval +X Returns the value from the current position of the hash iterator. See C. @@ -1290,6 +1668,7 @@ C. Found in file hv.c =item hv_magic +X Adds magic to a hash. See C. @@ -1299,6 +1678,7 @@ Adds magic to a hash. See C. Found in file hv.c =item hv_scalar +X Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied. @@ -1308,6 +1688,7 @@ Evaluates the hash in scalar context and returns the result. Handles magic when Found in file hv.c =item hv_store +X 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 @@ -1335,6 +1716,7 @@ information on how to use this function on tied hashes. Found in file hv.c =item hv_store_ent +X 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 @@ -1365,6 +1747,7 @@ information on how to use this function on tied hashes. Found in file hv.c =item hv_undef +X Undefines the hash. @@ -1374,6 +1757,7 @@ Undefines the hash. Found in file hv.c =item newHV +X Creates a new HV. The reference count is set to 1. @@ -1390,6 +1774,7 @@ Found in file hv.c =over 8 =item mg_clear +X Clear something magical that the SV represents. See C. @@ -1399,6 +1784,7 @@ Clear something magical that the SV represents. See C. Found in file mg.c =item mg_copy +X Copies the magic from one SV to another. See C. @@ -1408,6 +1794,7 @@ Copies the magic from one SV to another. See C. Found in file mg.c =item mg_find +X Finds the magic pointer for type matching the SV. See C. @@ -1417,6 +1804,7 @@ Finds the magic pointer for type matching the SV. See C. Found in file mg.c =item mg_free +X Free any magic storage used by the SV. See C. @@ -1426,6 +1814,7 @@ Free any magic storage used by the SV. See C. Found in file mg.c =item mg_get +X Do magic after a value is retrieved from the SV. See C. @@ -1435,6 +1824,7 @@ Do magic after a value is retrieved from the SV. See C. Found in file mg.c =item mg_length +X Report on the SV's length. See C. @@ -1444,6 +1834,7 @@ Report on the SV's length. See C. Found in file mg.c =item mg_magical +X Turns on the magical status of an SV. See C. @@ -1453,6 +1844,7 @@ Turns on the magical status of an SV. See C. Found in file mg.c =item mg_set +X Do magic after a value is assigned to the SV. See C. @@ -1462,6 +1854,7 @@ Do magic after a value is assigned to the SV. See C. Found in file mg.c =item SvGETMAGIC +X Invokes C on an SV if it has 'get' magic. This macro evaluates its argument more than once. @@ -1472,6 +1865,7 @@ argument more than once. Found in file sv.h =item SvLOCK +X Arranges for a mutual exclusion lock to be obtained on sv if a suitable module has been loaded. @@ -1482,6 +1876,7 @@ has been loaded. Found in file sv.h =item SvSETMAGIC +X Invokes C on an SV if it has 'set' magic. This macro evaluates its argument more than once. @@ -1492,6 +1887,7 @@ argument more than once. Found in file sv.h =item SvSetMagicSV +X Like C, but does any set magic required afterwards. @@ -1501,6 +1897,7 @@ Like C, but does any set magic required afterwards. Found in file sv.h =item SvSetMagicSV_nosteal +X Like C, but does any set magic required afterwards. @@ -1510,6 +1907,7 @@ Like C, but does any set magic required afterwards. Found in file sv.h =item SvSetSV +X Calls C if dsv is not the same as ssv. May evaluate arguments more than once. @@ -1520,6 +1918,7 @@ more than once. Found in file sv.h =item SvSetSV_nosteal +X Calls a non-destructive version of C if dsv is not the same as ssv. May evaluate arguments more than once. @@ -1530,6 +1929,7 @@ ssv. May evaluate arguments more than once. Found in file sv.h =item SvSHARE +X Arranges for sv to be shared between threads if a suitable module has been loaded. @@ -1540,6 +1940,7 @@ has been loaded. Found in file sv.h =item SvUNLOCK +X Releases a mutual exclusion lock on sv if a suitable module has been loaded. @@ -1557,6 +1958,7 @@ Found in file sv.h =over 8 =item Copy +X 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 @@ -1568,6 +1970,7 @@ the type. May fail on overlapping copies. See also C. Found in file handy.h =item CopyD +X Like C but returns dest. Useful for encouraging compilers to tail-call optimise. @@ -1578,6 +1981,7 @@ optimise. Found in file handy.h =item Move +X 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 @@ -1589,6 +1993,7 @@ the type. Can do overlapping moves. See also C. Found in file handy.h =item MoveD +X Like C but returns dest. Useful for encouraging compilers to tail-call optimise. @@ -1598,46 +2003,77 @@ optimise. =for hackers Found in file handy.h -=item New +=item Newx +X The XSUB-writer's interface to the C C function. - void New(int id, void* ptr, int nitems, type) +In 5.9.3, Newx() and friends replace the older New() API, and drops +the first parameter, I, a debug aid which allowed callers to identify +themselves. This aid has been superseded by a new build option, +PERL_MEM_LOG (see L). The older API is still +there for use in XS modules supporting older perls. + + void Newx(void* ptr, int nitems, type) =for hackers Found in file handy.h -=item Newc +=item Newxc +X The XSUB-writer's interface to the C C function, with -cast. +cast. See also C. - void Newc(int id, void* ptr, int nitems, type, cast) + void Newxc(void* ptr, int nitems, type, cast) =for hackers Found in file handy.h -=item Newz +=item Newxz +X The XSUB-writer's interface to the C C function. The allocated -memory is zeroed with C. +memory is zeroed with C. See also C. - void Newz(int id, void* ptr, int nitems, type) + void Newxz(void* ptr, int nitems, type) =for hackers Found in file handy.h =item Poison +X -Fill up memory with a pattern (byte 0xAB over and over again) that -hopefully catches attempts to access uninitialized memory. +PoisonWith(0xEF) for catching access to freed memory. void Poison(void* dest, int nitems, type) =for hackers Found in file handy.h +=item PoisonNew +X + +PoisonWith(0xAB) for catching access to allocated but uninitialized memory. + + void PoisonNew(void* dest, int nitems, type) + +=for hackers +Found in file handy.h + +=item PoisonWith +X + +Fill up memory with a byte pattern (a byte repeated over and over +again) that hopefully catches attempts to access uninitialized memory. + + void PoisonWith(void* dest, int nitems, type, U8 byte) + +=for hackers +Found in file handy.h + =item Renew +X The XSUB-writer's interface to the C C function. @@ -1647,6 +2083,7 @@ The XSUB-writer's interface to the C C function. Found in file handy.h =item Renewc +X The XSUB-writer's interface to the C C function, with cast. @@ -1657,6 +2094,7 @@ cast. Found in file handy.h =item Safefree +X The XSUB-writer's interface to the C C function. @@ -1666,6 +2104,7 @@ The XSUB-writer's interface to the C C function. Found in file handy.h =item savepv +X 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 @@ -1678,11 +2117,12 @@ be freed with the C function. Found in file util.c =item savepvn +X 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. +C bytes from C, plus a trailing NUL byte. The memory allocated for +the new string can be freed with the C function. char* savepvn(const char* pv, I32 len) @@ -1690,6 +2130,7 @@ freed with the C function. Found in file util.c =item savesharedpv +X A version of C which allocates the duplicate string in memory which is shared between threads. @@ -1700,6 +2141,7 @@ which is shared between threads. Found in file util.c =item savesvpv +X A version of C/C which gets the string to duplicate from the passed in SV using C @@ -1710,6 +2152,7 @@ the passed in SV using C Found in file util.c =item StructCopy +X This is an architecture-independent macro to copy one structure to another. @@ -1719,6 +2162,7 @@ This is an architecture-independent macro to copy one structure to another. Found in file handy.h =item Zero +X 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. @@ -1729,6 +2173,7 @@ destination, C is the number of items, and C is the type. Found in file handy.h =item ZeroD +X Like C but returns dest. Useful for encouraging compilers to tail-call optimise. @@ -1746,6 +2191,7 @@ Found in file handy.h =over 8 =item fbm_compile +X Analyses the string in order to make fast searches on it using fbm_instr() -- the Boyer-Moore algorithm. @@ -1756,9 +2202,10 @@ Analyses the string in order to make fast searches on it using fbm_instr() Found in file util.c =item fbm_instr +X 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 +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. @@ -1768,6 +2215,7 @@ then. Found in file util.c =item form +X
Takes a sprintf-style format pattern and conventional (non-SV) arguments and returns the formatted string. @@ -1788,6 +2236,7 @@ are done). Found in file util.c =item getcwd_sv +X Fill the sv with current working directory @@ -1796,11 +2245,24 @@ Fill the sv with current working directory =for hackers Found in file util.c -=item new_version +=item my_sprintf +X -Returns a new version object based on the passed in SV: +The C library C, wrapped if necessary, to ensure that it will return +the length of the string written to the buffer. Only rare pre-ANSI systems +need the wrapper function - usually this is a direct call to C. - SV *sv = new_version(SV *ver); + int my_sprintf(char *buffer, const char *pat, ...) + +=for hackers +Found in file util.c + +=item new_version +X + +Returns a new version object based on the passed in SV: + + SV *sv = new_version(SV *ver); Does not alter the passed in ver SV. See "upg_version" if you want to upgrade the SV. @@ -1811,6 +2273,7 @@ want to upgrade the SV. Found in file util.c =item scan_version +X Returns a pointer to the next character after the parsed version string, as well as upgrading the passed in SV to @@ -1828,12 +2291,13 @@ is a alpha version). The boolean qv denotes that the version should be interpreted as if it had multiple decimals, even if it doesn't. - char* scan_version(const char *vstr, SV *sv, bool qv) + const char* scan_version(const char *vstr, SV *sv, bool qv) =for hackers Found in file util.c =item strEQ +X Test two strings to see if they are equal. Returns true or false. @@ -1843,6 +2307,7 @@ Test two strings to see if they are equal. Returns true or false. Found in file handy.h =item strGE +X Test two strings to see if the first, C, is greater than or equal to the second, C. Returns true or false. @@ -1853,6 +2318,7 @@ the second, C. Returns true or false. Found in file handy.h =item strGT +X Test two strings to see if the first, C, is greater than the second, C. Returns true or false. @@ -1863,6 +2329,7 @@ C. Returns true or false. Found in file handy.h =item strLE +X Test two strings to see if the first, C, is less than or equal to the second, C. Returns true or false. @@ -1873,6 +2340,7 @@ second, C. Returns true or false. Found in file handy.h =item strLT +X Test two strings to see if the first, C, is less than the second, C. Returns true or false. @@ -1883,6 +2351,7 @@ C. Returns true or false. Found in file handy.h =item strNE +X Test two strings to see if they are different. Returns true or false. @@ -1893,6 +2362,7 @@ false. Found in file handy.h =item strnEQ +X 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 @@ -1904,6 +2374,7 @@ C). Found in file handy.h =item strnNE +X Test two strings to see if they are different. The C parameter indicates the number of bytes to compare. Returns true or false. (A @@ -1914,40 +2385,21 @@ wrapper for C). =for hackers Found in file handy.h -=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 +X 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. +Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument. +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 *) + void sv_nosharing(SV *sv) =for hackers Found in file util.c =item upg_version +X In-place upgrade of the supplied SV to a version object. @@ -1961,6 +2413,7 @@ Returns a pointer to the upgraded SV. Found in file util.c =item vcmp +X Version object aware cmp. Both operands must already have been converted into version objects. @@ -1971,6 +2424,7 @@ converted into version objects. Found in file util.c =item vnormal +X Accepts a version object and returns the normalized string representation. Call like: @@ -1986,6 +2440,7 @@ contained within the RV. Found in file util.c =item vnumify +X Accepts a version object and returns the normalized floating point representation. Call like: @@ -2001,6 +2456,7 @@ contained within the RV. Found in file util.c =item vstringify +X In order to maintain maximum compatibility with earlier versions of Perl, this function will return either the floating point @@ -2012,6 +2468,70 @@ the original version contained 1 or more dots, respectively =for hackers Found in file util.c +=item vverify +X + +Validates that the SV contains a valid version object. + + bool vverify(SV *vobj); + +Note that it only confirms the bare minimum structure (so as not to get +confused by derived classes which may contain additional hash entries): + + bool vverify(SV *vs) + +=for hackers +Found in file util.c + + +=back + +=head1 Multicall Functions + +=over 8 + +=item dMULTICALL +X + +Declare local variables for a multicall. See L. + + dMULTICALL; + +=for hackers +Found in file cop.h + +=item MULTICALL +X + +Make a lightweight callback. See L. + + MULTICALL; + +=for hackers +Found in file cop.h + +=item POP_MULTICALL +X + +Closing bracket for a lightweight callback. +See L. + + POP_MULTICALL; + +=for hackers +Found in file cop.h + +=item PUSH_MULTICALL +X + +Opening bracket for a lightweight callback. +See L. + + PUSH_MULTICALL; + +=for hackers +Found in file cop.h + =back @@ -2020,6 +2540,7 @@ Found in file util.c =over 8 =item grok_bin +X converts a string representing a binary number to numeric form. @@ -2042,12 +2563,13 @@ 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(const char* start, STRLEN* len, I32* flags, NV *result) + UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result) =for hackers Found in file numeric.c =item grok_hex +X converts a string representing a hex number to numeric form. @@ -2070,12 +2592,13 @@ 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. - UV grok_hex(const char* start, STRLEN* len, I32* flags, NV *result) + UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result) =for hackers Found in file numeric.c =item grok_number +X Recognise (or not) a number. The type of the number is returned (0 if unrecognised), otherwise it is a bit-ORed combination of @@ -2101,6 +2624,7 @@ number is larger than a UV. Found in file numeric.c =item grok_numeric_radix +X Scan and skip for a numeric decimal separator (radix). @@ -2110,6 +2634,7 @@ Scan and skip for a numeric decimal separator (radix). Found in file numeric.c =item grok_oct +X converts a string representing an octal number to numeric form. @@ -2130,34 +2655,37 @@ is NULL). If C is set in I<*flags> then the octal number may use '_' characters to separate digits. - UV grok_oct(const char* start, STRLEN* len, I32* flags, NV *result) + UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result) =for hackers Found in file numeric.c =item scan_bin +X For backwards compatibility. Use C instead. - NV scan_bin(char* start, STRLEN len, STRLEN* retlen) + NV scan_bin(const char* start, STRLEN len, STRLEN* retlen) =for hackers Found in file numeric.c =item scan_hex +X For backwards compatibility. Use C instead. - NV scan_hex(char* start, STRLEN len, STRLEN* retlen) + NV scan_hex(const char* start, STRLEN len, STRLEN* retlen) =for hackers Found in file numeric.c =item scan_oct +X For backwards compatibility. Use C instead. - NV scan_oct(char* start, STRLEN len, STRLEN* retlen) + NV scan_oct(const char* start, STRLEN len, STRLEN* retlen) =for hackers Found in file numeric.c @@ -2170,6 +2698,7 @@ Found in file numeric.c =over 8 =item cv_const_sv +X If C is a constant sub eligible for inlining. returns the constant value returned by the sub. Otherwise, returns NULL. @@ -2183,6 +2712,7 @@ L. Found in file op.c =item newCONSTSUB +X Creates a constant sub equivalent to Perl C which is eligible for inlining at compile-time. @@ -2193,8 +2723,10 @@ eligible for inlining at compile-time. Found in file op.c =item newXS +X -Used by C to hook up XSUBs as Perl subs. +Used by C to hook up XSUBs as Perl subs. I needs to be +static storage, as it is used directly as CvFILE(), without a copy being made. =for hackers Found in file op.c @@ -2207,6 +2739,7 @@ Found in file op.c =over 8 =item pad_sv +X Get the value at offset po in the current pad. Use macro PAD_SV instead of calling this function directly. @@ -2224,8 +2757,9 @@ Found in file pad.c =over 8 =item dXCPT +X -Set up neccessary local variables for exception handling. +Set up necessary local variables for exception handling. See L. dXCPT; @@ -2234,6 +2768,7 @@ See L. Found in file XSUB.h =item XCPT_CATCH +X Introduces a catch block. See L. @@ -2241,6 +2776,7 @@ Introduces a catch block. See L. Found in file XSUB.h =item XCPT_RETHROW +X Rethrows a previously caught exception. See L. @@ -2250,6 +2786,7 @@ Rethrows a previously caught exception. See L. Found in file XSUB.h =item XCPT_TRY_END +X Ends a try block. See L. @@ -2257,6 +2794,7 @@ Ends a try block. See L. Found in file XSUB.h =item XCPT_TRY_START +X Starts a try block. See L. @@ -2271,6 +2809,7 @@ Found in file XSUB.h =over 8 =item dMARK +X Declare a stack marker variable, C, for the XSUB. See C and C. @@ -2281,6 +2820,7 @@ C. Found in file pp.h =item dORIGMARK +X Saves the original stack mark for the XSUB. See C. @@ -2290,6 +2830,7 @@ Saves the original stack mark for the XSUB. See C. Found in file pp.h =item dSP +X Declares a local copy of perl's stack pointer for the XSUB, available via the C macro. See C. @@ -2300,6 +2841,7 @@ the C macro. See C. Found in file pp.h =item EXTEND +X 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 @@ -2311,6 +2853,7 @@ onto the stack. Found in file pp.h =item MARK +X Stack marker variable for the XSUB. See C. @@ -2318,6 +2861,7 @@ Stack marker variable for the XSUB. See C. Found in file pp.h =item mPUSHi +X Push an integer onto the stack. The stack must have room for this element. Handles 'set' magic. Does not use C. See also C, C @@ -2329,6 +2873,7 @@ and C. Found in file pp.h =item mPUSHn +X Push a double onto the stack. The stack must have room for this element. Handles 'set' magic. Does not use C. See also C, C @@ -2340,6 +2885,7 @@ and C. Found in file pp.h =item mPUSHp +X 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. Does @@ -2351,6 +2897,7 @@ not use C. See also C, C and C. Found in file pp.h =item mPUSHu +X Push an unsigned integer onto the stack. The stack must have room for this element. Handles 'set' magic. Does not use C. See also C, @@ -2362,6 +2909,7 @@ C and C. Found in file pp.h =item mXPUSHi +X Push an integer onto the stack, extending the stack if necessary. Handles 'set' magic. Does not use C. See also C, C and @@ -2373,6 +2921,7 @@ C. Found in file pp.h =item mXPUSHn +X Push a double onto the stack, extending the stack if necessary. Handles 'set' magic. Does not use C. See also C, C and @@ -2384,6 +2933,7 @@ C. Found in file pp.h =item mXPUSHp +X Push a string onto the stack, extending the stack if necessary. The C indicates the length of the string. Handles 'set' magic. Does not use @@ -2395,6 +2945,7 @@ C. See also C, C and C. Found in file pp.h =item mXPUSHu +X Push an unsigned integer onto the stack, extending the stack if necessary. Handles 'set' magic. Does not use C. See also C, C @@ -2406,6 +2957,7 @@ and C. Found in file pp.h =item ORIGMARK +X The original stack mark for the XSUB. See C. @@ -2413,6 +2965,7 @@ The original stack mark for the XSUB. See C. Found in file pp.h =item POPi +X Pops an integer off the stack. @@ -2422,6 +2975,7 @@ Pops an integer off the stack. Found in file pp.h =item POPl +X Pops a long off the stack. @@ -2431,6 +2985,7 @@ Pops a long off the stack. Found in file pp.h =item POPn +X Pops a double off the stack. @@ -2440,9 +2995,9 @@ Pops a double off the stack. Found in file pp.h =item POPp +X -Pops a string off the stack. Deprecated. New code should provide -a STRLEN n_a and use POPpx. +Pops a string off the stack. Deprecated. New code should use POPpx. char* POPp @@ -2450,9 +3005,9 @@ a STRLEN n_a and use POPpx. Found in file pp.h =item POPpbytex +X Pops a string off the stack which must consist of bytes i.e. characters < 256. -Requires a variable STRLEN n_a in scope. char* POPpbytex @@ -2460,9 +3015,9 @@ Requires a variable STRLEN n_a in scope. Found in file pp.h =item POPpx +X Pops a string off the stack. -Requires a variable STRLEN n_a in scope. char* POPpx @@ -2470,6 +3025,7 @@ Requires a variable STRLEN n_a in scope. Found in file pp.h =item POPs +X Pops an SV off the stack. @@ -2479,6 +3035,7 @@ Pops an SV off the stack. Found in file pp.h =item PUSHi +X Push an integer onto the stack. The stack must have room for this element. Handles 'set' magic. Uses C, so C or C should be @@ -2492,6 +3049,7 @@ C. Found in file pp.h =item PUSHMARK +X Opening bracket for arguments on a callback. See C and L. @@ -2502,6 +3060,7 @@ L. Found in file pp.h =item PUSHmortal +X Push a new mortal SV onto the stack. The stack must have room for this element. Does not handle 'set' magic. Does not use C. See also @@ -2513,6 +3072,7 @@ C, C and C. Found in file pp.h =item PUSHn +X Push a double onto the stack. The stack must have room for this element. Handles 'set' magic. Uses C, so C or C should be @@ -2526,6 +3086,7 @@ C. Found in file pp.h =item PUSHp +X 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. Uses @@ -2539,6 +3100,7 @@ C instead. See also C and C. Found in file pp.h =item PUSHs +X Push an SV onto the stack. The stack must have room for this element. Does not handle 'set' magic. Does not use C. See also C, @@ -2550,6 +3112,7 @@ C and C. Found in file pp.h =item PUSHu +X Push an unsigned integer onto the stack. The stack must have room for this element. Handles 'set' magic. Uses C, so C or C @@ -2563,6 +3126,7 @@ C and C. Found in file pp.h =item PUTBACK +X Closing bracket for XSUB arguments. This is usually handled by C. See C and L for other uses. @@ -2573,6 +3137,7 @@ See C and L for other uses. Found in file pp.h =item SP +X Stack pointer. This is usually handled by C. See C and C. @@ -2581,6 +3146,7 @@ C. Found in file pp.h =item SPAGAIN +X Refetch the stack pointer. Used after a callback. See L. @@ -2590,6 +3156,7 @@ Refetch the stack pointer. Used after a callback. See L. Found in file pp.h =item XPUSHi +X Push an integer onto the stack, extending the stack if necessary. Handles 'set' magic. Uses C, so C or C should be called to @@ -2602,6 +3169,7 @@ from XSUB's - see C instead. See also C and C. Found in file pp.h =item XPUSHmortal +X Push a new mortal SV onto the stack, extending the stack if necessary. Does not handle 'set' magic. Does not use C. See also C, @@ -2613,6 +3181,7 @@ C and C. Found in file pp.h =item XPUSHn +X Push a double onto the stack, extending the stack if necessary. Handles 'set' magic. Uses C, so C or C should be called to @@ -2625,6 +3194,7 @@ from XSUB's - see C instead. See also C and C. Found in file pp.h =item XPUSHp +X Push a string onto the stack, extending the stack if necessary. The C indicates the length of the string. Handles 'set' magic. Uses C, so @@ -2638,6 +3208,7 @@ C instead. See also C and C. Found in file pp.h =item XPUSHs +X Push an SV onto the stack, extending the stack if necessary. Does not handle 'set' magic. Does not use C. See also C, @@ -2649,6 +3220,7 @@ C and C. Found in file pp.h =item XPUSHu +X Push an unsigned integer onto the stack, extending the stack if necessary. Handles 'set' magic. Uses C, so C or C should be @@ -2662,6 +3234,7 @@ C. Found in file pp.h =item XSRETURN +X Return from XSUB, indicating number of items on the stack. This is usually handled by C. @@ -2672,6 +3245,7 @@ handled by C. Found in file XSUB.h =item XSRETURN_EMPTY +X Return an empty list from an XSUB immediately. @@ -2681,6 +3255,7 @@ Return an empty list from an XSUB immediately. Found in file XSUB.h =item XSRETURN_IV +X Return an integer from an XSUB immediately. Uses C. @@ -2690,6 +3265,7 @@ Return an integer from an XSUB immediately. Uses C. Found in file XSUB.h =item XSRETURN_NO +X Return C<&PL_sv_no> from an XSUB immediately. Uses C. @@ -2699,6 +3275,7 @@ Return C<&PL_sv_no> from an XSUB immediately. Uses C. Found in file XSUB.h =item XSRETURN_NV +X Return a double from an XSUB immediately. Uses C. @@ -2708,6 +3285,7 @@ Return a double from an XSUB immediately. Uses C. Found in file XSUB.h =item XSRETURN_PV +X Return a copy of a string from an XSUB immediately. Uses C. @@ -2717,6 +3295,7 @@ Return a copy of a string from an XSUB immediately. Uses C. Found in file XSUB.h =item XSRETURN_UNDEF +X Return C<&PL_sv_undef> from an XSUB immediately. Uses C. @@ -2726,6 +3305,7 @@ Return C<&PL_sv_undef> from an XSUB immediately. Uses C. Found in file XSUB.h =item XSRETURN_UV +X Return an integer from an XSUB immediately. Uses C. @@ -2735,6 +3315,7 @@ Return an integer from an XSUB immediately. Uses C. Found in file XSUB.h =item XSRETURN_YES +X Return C<&PL_sv_yes> from an XSUB immediately. Uses C. @@ -2744,6 +3325,7 @@ Return C<&PL_sv_yes> from an XSUB immediately. Uses C. Found in file XSUB.h =item XST_mIV +X Place an integer into the specified position C on the stack. The value is stored in a new mortal SV. @@ -2754,6 +3336,7 @@ value is stored in a new mortal SV. Found in file XSUB.h =item XST_mNO +X Place C<&PL_sv_no> into the specified position C on the stack. @@ -2764,6 +3347,7 @@ stack. Found in file XSUB.h =item XST_mNV +X Place a double into the specified position C on the stack. The value is stored in a new mortal SV. @@ -2774,6 +3358,7 @@ is stored in a new mortal SV. Found in file XSUB.h =item XST_mPV +X Place a copy of a string into the specified position C on the stack. The value is stored in a new mortal SV. @@ -2784,6 +3369,7 @@ The value is stored in a new mortal SV. Found in file XSUB.h =item XST_mUNDEF +X Place C<&PL_sv_undef> into the specified position C on the stack. @@ -2794,6 +3380,7 @@ stack. Found in file XSUB.h =item XST_mYES +X Place C<&PL_sv_yes> into the specified position C on the stack. @@ -2811,6 +3398,7 @@ Found in file XSUB.h =over 8 =item svtype +X 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. @@ -2819,6 +3407,7 @@ in the C enum. Test these flags with the C macro. Found in file sv.h =item SVt_IV +X Integer type flag for scalars. See C. @@ -2826,6 +3415,7 @@ Integer type flag for scalars. See C. Found in file sv.h =item SVt_NV +X Double type flag for scalars. See C. @@ -2833,6 +3423,7 @@ Double type flag for scalars. See C. Found in file sv.h =item SVt_PV +X Pointer type flag for scalars. See C. @@ -2840,6 +3431,7 @@ Pointer type flag for scalars. See C. Found in file sv.h =item SVt_PVAV +X Type flag for arrays. See C. @@ -2847,6 +3439,7 @@ Type flag for arrays. See C. Found in file sv.h =item SVt_PVCV +X Type flag for code refs. See C. @@ -2854,6 +3447,7 @@ Type flag for code refs. See C. Found in file sv.h =item SVt_PVHV +X Type flag for hashes. See C. @@ -2861,6 +3455,7 @@ Type flag for hashes. See C. Found in file sv.h =item SVt_PVMG +X Type flag for blessed scalars. See C. @@ -2875,6 +3470,7 @@ Found in file sv.h =over 8 =item get_sv +X 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 @@ -2887,18 +3483,8 @@ NOTE: the perl_ form of this function is deprecated. =for hackers Found in file perl.c -=item looks_like_number - -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. - - I32 looks_like_number(SV* sv) - -=for hackers -Found in file sv.c - =item newRV_inc +X Creates an RV wrapper for an SV. The reference count for the original SV is incremented. @@ -2908,141 +3494,8 @@ incremented. =for hackers Found in file sv.h -=item newRV_noinc - -Creates an RV wrapper for an SV. The reference count for the original -SV is B incremented. - - SV* newRV_noinc(SV *sv) - -=for hackers -Found in file sv.c - -=item NEWSV - -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). - - SV* NEWSV(int id, STRLEN len) - -=for hackers -Found in file handy.h - -=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. - - SV* newSV(STRLEN len) - -=for hackers -Found in file sv.c - -=item newSViv - -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. - - SV* newSViv(IV i) - -=for hackers -Found in file sv.c - -=item newSVnv - -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. - - SV* newSVnv(NV n) - -=for hackers -Found in file sv.c - -=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. - - SV* newSVpv(const char* s, STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvf - -Creates a new SV and initializes it with the string formatted like -C. - - SV* newSVpvf(const char* pat, ...) - -=for hackers -Found in file sv.c - -=item newSVpvn - -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. If the C argument is NULL the new SV will be undefined. - - SV* newSVpvn(const char* s, STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvn_share - -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. - - SV* newSVpvn_share(const char* s, I32 len, U32 hash) - -=for hackers -Found in file sv.c - -=item newSVrv - -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) - -=for hackers -Found in file sv.c - -=item newSVsv - -Creates a new SV which is an exact duplicate of the original SV. -(Uses C). - - SV* newSVsv(SV* old) - -=for hackers -Found in file sv.c - -=item newSVuv - -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. - - SV* newSVuv(UV u) - -=for hackers -Found in file sv.c - =item SvCUR +X Returns the length of the string which is in the SV. See C. @@ -3052,8 +3505,10 @@ Returns the length of the string which is in the SV. See C. Found in file sv.h =item SvCUR_set +X -Set the length of the string which is in the SV. See C. +Set the current length of the string which is in the SV. See C +and C. void SvCUR_set(SV* sv, STRLEN len) @@ -3061,6 +3516,7 @@ Set the length of the string which is in the SV. See C. Found in file sv.h =item SvEND +X Returns a pointer to the last character in the string which is in the SV. See C. Access the character as *(SvEND(sv)). @@ -3070,7 +3526,22 @@ See C. Access the character as *(SvEND(sv)). =for hackers Found in file sv.h +=item SvGAMAGIC +X + +Returns true if the SV has get magic or overloading. If either is true then +the scalar is active data, and has the potential to return a new value every +time it is accessed. Hence you must be careful to only read it once per user +logical operation and work with that returned value. If neither is true then +the scalar's value cannot change unless written to. + + char* SvGAMAGIC(SV* sv) + +=for hackers +Found in file sv.h + =item SvGROW +X Expands the character buffer in the SV so that it has room for the indicated number of bytes (remember to reserve space for an extra trailing @@ -3083,6 +3554,7 @@ Returns a pointer to the character buffer. Found in file sv.h =item SvIOK +X Returns a boolean indicating whether the SV contains an integer. @@ -3092,6 +3564,7 @@ Returns a boolean indicating whether the SV contains an integer. Found in file sv.h =item SvIOKp +X Returns a boolean indicating whether the SV contains an integer. Checks the B setting. Use C. @@ -3102,6 +3575,7 @@ the B setting. Use C. Found in file sv.h =item SvIOK_notUV +X Returns a boolean indicating whether the SV contains a signed integer. @@ -3111,6 +3585,7 @@ Returns a boolean indicating whether the SV contains a signed integer. Found in file sv.h =item SvIOK_off +X Unsets the IV status of an SV. @@ -3120,6 +3595,7 @@ Unsets the IV status of an SV. Found in file sv.h =item SvIOK_on +X Tells an SV that it is an integer. @@ -3129,6 +3605,7 @@ Tells an SV that it is an integer. Found in file sv.h =item SvIOK_only +X Tells an SV that it is an integer and disables all other OK bits. @@ -3138,6 +3615,7 @@ Tells an SV that it is an integer and disables all other OK bits. Found in file sv.h =item SvIOK_only_UV +X Tells and SV that it is an unsigned integer and disables all other OK bits. @@ -3147,6 +3625,7 @@ Tells and SV that it is an unsigned integer and disables all other OK bits. Found in file sv.h =item SvIOK_UV +X Returns a boolean indicating whether the SV contains an unsigned integer. @@ -3156,6 +3635,7 @@ Returns a boolean indicating whether the SV contains an unsigned integer. Found in file sv.h =item SvIsCOW +X Returns a boolean indicating whether the SV is Copy-On-Write. (either shared hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for @@ -3167,6 +3647,7 @@ COW) Found in file sv.h =item SvIsCOW_shared_hash +X Returns a boolean indicating whether the SV is Copy-On-Write shared hash key scalar. @@ -3177,6 +3658,7 @@ scalar. Found in file sv.h =item SvIV +X Coerces the given SV to an integer and returns it. See C for a version which guarantees to evaluate sv only once. @@ -3187,6 +3669,7 @@ version which guarantees to evaluate sv only once. Found in file sv.h =item SvIVX +X Returns the raw value in the SV's IV slot, without checks or conversions. Only use when you are sure SvIOK is true. See also C. @@ -3197,6 +3680,7 @@ Only use when you are sure SvIOK is true. See also C. Found in file sv.h =item SvIVx +X Coerces the given SV to an integer and returns it. Guarantees to evaluate sv only once. Use the more efficient C otherwise. @@ -3207,6 +3691,7 @@ sv only once. Use the more efficient C otherwise. Found in file sv.h =item SvIV_nomg +X Like C but doesn't process magic. @@ -3215,7 +3700,21 @@ Like C but doesn't process magic. =for hackers Found in file sv.h +=item SvIV_set +X + +Set the value of the IV pointer in sv to val. It is possible to perform +the same function of this macro with an lvalue assignment to C. +With future Perls, however, it will be more efficient to use +C instead of the lvalue assignment to C. + + void SvIV_set(SV* sv, IV val) + +=for hackers +Found in file sv.h + =item SvLEN +X Returns the size of the string buffer in the SV, not including any part attributable to C. See C. @@ -3225,7 +3724,28 @@ attributable to C. See C. =for hackers Found in file sv.h +=item SvLEN_set +X + +Set the actual length of the string which is in the SV. See C. + + void SvLEN_set(SV* sv, STRLEN len) + +=for hackers +Found in file sv.h + +=item SvMAGIC_set +X + +Set the value of the MAGIC pointer in sv to val. See C. + + void SvMAGIC_set(SV* sv, MAGIC* val) + +=for hackers +Found in file sv.h + =item SvNIOK +X Returns a boolean indicating whether the SV contains a number, integer or double. @@ -3236,6 +3756,7 @@ double. Found in file sv.h =item SvNIOKp +X Returns a boolean indicating whether the SV contains a number, integer or double. Checks the B setting. Use C. @@ -3246,6 +3767,7 @@ double. Checks the B setting. Use C. Found in file sv.h =item SvNIOK_off +X Unsets the NV/IV status of an SV. @@ -3255,6 +3777,7 @@ Unsets the NV/IV status of an SV. Found in file sv.h =item SvNOK +X Returns a boolean indicating whether the SV contains a double. @@ -3264,6 +3787,7 @@ Returns a boolean indicating whether the SV contains a double. Found in file sv.h =item SvNOKp +X Returns a boolean indicating whether the SV contains a double. Checks the B setting. Use C. @@ -3274,6 +3798,7 @@ B setting. Use C. Found in file sv.h =item SvNOK_off +X Unsets the NV status of an SV. @@ -3283,6 +3808,7 @@ Unsets the NV status of an SV. Found in file sv.h =item SvNOK_on +X Tells an SV that it is a double. @@ -3292,6 +3818,7 @@ Tells an SV that it is a double. Found in file sv.h =item SvNOK_only +X Tells an SV that it is a double and disables all other OK bits. @@ -3301,6 +3828,7 @@ Tells an SV that it is a double and disables all other OK bits. Found in file sv.h =item SvNV +X Coerce the given SV to a double and return it. See C for a version which guarantees to evaluate sv only once. @@ -3311,6 +3839,7 @@ which guarantees to evaluate sv only once. Found in file sv.h =item SvNVX +X 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. @@ -3321,6 +3850,7 @@ Only use when you are sure SvNOK is true. See also C. Found in file sv.h =item SvNVx +X Coerces the given SV to a double and returns it. Guarantees to evaluate sv only once. Use the more efficient C otherwise. @@ -3330,7 +3860,18 @@ sv only once. Use the more efficient C otherwise. =for hackers Found in file sv.h +=item SvNV_set +X + +Set the value of the NV pointer in sv to val. See C. + + void SvNV_set(SV* sv, NV val) + +=for hackers +Found in file sv.h + =item SvOK +X Returns a boolean indicating whether the value is an SV. It also tells whether the value is defined or not. @@ -3341,6 +3882,7 @@ whether the value is defined or not. Found in file sv.h =item SvOOK +X Returns a boolean indicating whether the SvIVX is a valid offset value for the SvPVX. This hack is used internally to speed up removal of characters @@ -3353,6 +3895,7 @@ allocated string buffer is really (SvPVX - SvIVX). Found in file sv.h =item SvPOK +X Returns a boolean indicating whether the SV contains a character string. @@ -3363,6 +3906,7 @@ string. Found in file sv.h =item SvPOKp +X Returns a boolean indicating whether the SV contains a character string. Checks the B setting. Use C. @@ -3373,6 +3917,7 @@ Checks the B setting. Use C. Found in file sv.h =item SvPOK_off +X Unsets the PV status of an SV. @@ -3382,6 +3927,7 @@ Unsets the PV status of an SV. Found in file sv.h =item SvPOK_on +X Tells an SV that it is a string. @@ -3391,6 +3937,7 @@ Tells an SV that it is a string. Found in file sv.h =item SvPOK_only +X Tells an SV that it is a string and disables all other OK bits. Will also turn off the UTF-8 status. @@ -3401,6 +3948,7 @@ Will also turn off the UTF-8 status. Found in file sv.h =item SvPOK_only_UTF8 +X Tells an SV that it is a string and disables all other OK bits, and leaves the UTF-8 status as it was. @@ -3411,6 +3959,7 @@ and leaves the UTF-8 status as it was. Found in file sv.h =item SvPV +X 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 @@ -3423,6 +3972,7 @@ C for a version which guarantees to evaluate sv only once. Found in file sv.h =item SvPVbyte +X Like C, but converts sv to byte representation first if necessary. @@ -3432,6 +3982,7 @@ Like C, but converts sv to byte representation first if necessary. Found in file sv.h =item SvPVbytex +X Like C, but converts sv to byte representation first if necessary. Guarantees to evaluate sv only once; use the more efficient C @@ -3443,6 +3994,7 @@ otherwise. Found in file sv.h =item SvPVbytex_force +X Like C, but converts sv to byte representation first if necessary. Guarantees to evaluate sv only once; use the more efficient C @@ -3454,6 +4006,7 @@ otherwise. Found in file sv.h =item SvPVbyte_force +X Like C, but converts sv to byte representation first if necessary. @@ -3463,6 +4016,7 @@ Like C, but converts sv to byte representation first if necessary. Found in file sv.h =item SvPVbyte_nolen +X Like C, but converts sv to byte representation first if necessary. @@ -3472,6 +4026,7 @@ Like C, but converts sv to byte representation first if necessary. Found in file sv.h =item SvPVutf8 +X Like C, but converts sv to utf8 first if necessary. @@ -3481,6 +4036,7 @@ Like C, but converts sv to utf8 first if necessary. Found in file sv.h =item SvPVutf8x +X Like C, but converts sv to utf8 first if necessary. Guarantees to evaluate sv only once; use the more efficient C @@ -3492,6 +4048,7 @@ otherwise. Found in file sv.h =item SvPVutf8x_force +X Like C, but converts sv to utf8 first if necessary. Guarantees to evaluate sv only once; use the more efficient C @@ -3503,6 +4060,7 @@ otherwise. Found in file sv.h =item SvPVutf8_force +X Like C, but converts sv to utf8 first if necessary. @@ -3512,6 +4070,7 @@ Like C, but converts sv to utf8 first if necessary. Found in file sv.h =item SvPVutf8_nolen +X Like C, but converts sv to utf8 first if necessary. @@ -3521,6 +4080,7 @@ Like C, but converts sv to utf8 first if necessary. Found in file sv.h =item SvPVX +X Returns a pointer to the physical string in the SV. The SV must contain a string. @@ -3531,6 +4091,7 @@ string. Found in file sv.h =item SvPVx +X A version of C which guarantees to evaluate sv only once. @@ -3540,6 +4101,7 @@ A version of C which guarantees to evaluate sv only once. Found in file sv.h =item SvPV_force +X Like C but will force the SV into containing just a string (C). You want force if you are going to update the C @@ -3551,6 +4113,7 @@ directly. Found in file sv.h =item SvPV_force_nomg +X Like C but will force the SV into containing just a string (C). You want force if you are going to update the C @@ -3562,6 +4125,7 @@ directly. Doesn't process magic. Found in file sv.h =item SvPV_nolen +X 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 @@ -3573,6 +4137,7 @@ stringified form becoming C. Handles 'get' magic. Found in file sv.h =item SvPV_nomg +X Like C but doesn't process magic. @@ -3581,7 +4146,18 @@ Like C but doesn't process magic. =for hackers Found in file sv.h +=item SvPV_set +X + +Set the value of the PV pointer in sv to val. See C. + + void SvPV_set(SV* sv, char* val) + +=for hackers +Found in file sv.h + =item SvREFCNT +X Returns the value of the object's reference count. @@ -3591,6 +4167,7 @@ Returns the value of the object's reference count. Found in file sv.h =item SvREFCNT_dec +X Decrements the reference count of the given SV. @@ -3600,6 +4177,7 @@ Decrements the reference count of the given SV. Found in file sv.h =item SvREFCNT_inc +X Increments the reference count of the given SV. @@ -3608,7 +4186,79 @@ Increments the reference count of the given SV. =for hackers Found in file sv.h +=item SvREFCNT_inc_NN +X + +Same as SvREFCNT_inc, but can only be used if you know I +is not NULL. Since we don't have to check the NULLness, it's faster +and smaller. + + SV* SvREFCNT_inc_NN(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple +X + +Same as SvREFCNT_inc, but can only be used with simple variables, not +expressions or pointer dereferences. Since we don't have to store a +temporary value, it's faster. + + SV* SvREFCNT_inc_simple(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple_NN +X + +Same as SvREFCNT_inc_simple, but can only be used if you know I +is not NULL. Since we don't have to check the NULLness, it's faster +and smaller. + + SV* SvREFCNT_inc_simple_NN(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple_void +X + +Same as SvREFCNT_inc_simple, but can only be used if you don't need the +return value. The macro doesn't need to return a meaningful value. + + SV* SvREFCNT_inc_simple_void(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_void +X + +Same as SvREFCNT_inc, but can only be used if you don't need the +return value. The macro doesn't need to return a meaningful value. + + SV* SvREFCNT_inc_void(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_void_NN +X + +Same as SvREFCNT_inc, but can only be used if you don't need the return +value, and you know that I is not NULL. The macro doesn't need +to return a meaningful value, or check for NULLness, so it's smaller +and faster. + + SV* SvREFCNT_inc_void_NN(SV* sv) + +=for hackers +Found in file sv.h + =item SvROK +X Tests if the SV is an RV. @@ -3618,6 +4268,7 @@ Tests if the SV is an RV. Found in file sv.h =item SvROK_off +X Unsets the RV status of an SV. @@ -3627,6 +4278,7 @@ Unsets the RV status of an SV. Found in file sv.h =item SvROK_on +X Tells an SV that it is an RV. @@ -3636,6 +4288,7 @@ Tells an SV that it is an RV. Found in file sv.h =item SvRV +X Dereferences an RV to return the SV. @@ -3644,7 +4297,18 @@ Dereferences an RV to return the SV. =for hackers Found in file sv.h +=item SvRV_set +X + +Set the value of the RV pointer in sv to val. See C. + + void SvRV_set(SV* sv, SV* val) + +=for hackers +Found in file sv.h + =item SvSTASH +X Returns the stash of the SV. @@ -3653,7 +4317,18 @@ Returns the stash of the SV. =for hackers Found in file sv.h +=item SvSTASH_set +X + +Set the value of the STASH pointer in sv to val. See C. + + void SvSTASH_set(SV* sv, STASH* val) + +=for hackers +Found in file sv.h + =item SvTAINT +X Taints an SV if tainting is enabled. @@ -3663,6 +4338,7 @@ Taints an SV if tainting is enabled. Found in file sv.h =item SvTAINTED +X Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if not. @@ -3673,6 +4349,7 @@ not. Found in file sv.h =item SvTAINTED_off +X Untaints an SV. Be I careful with this routine, as it short-circuits some of Perl's fundamental security features. XS module authors should not @@ -3687,6 +4364,7 @@ untainting variables. Found in file sv.h =item SvTAINTED_on +X Marks an SV as tainted if tainting is enabled. @@ -3696,6 +4374,7 @@ Marks an SV as tainted if tainting is enabled. Found in file sv.h =item SvTRUE +X Returns a boolean indicating whether Perl would evaluate the SV as true or false, defined or undefined. Does not handle 'get' magic. @@ -3706,6 +4385,7 @@ false, defined or undefined. Does not handle 'get' magic. Found in file sv.h =item SvTYPE +X Returns the type of the SV. See C. @@ -3715,6 +4395,7 @@ Returns the type of the SV. See C. Found in file sv.h =item SvUOK +X Returns a boolean indicating whether the SV contains an unsigned integer. @@ -3724,6 +4405,7 @@ Returns a boolean indicating whether the SV contains an unsigned integer. Found in file sv.h =item SvUPGRADE +X Used to upgrade an SV to a more complex form. Uses C to perform the upgrade if necessary. See C. @@ -3734,6 +4416,7 @@ perform the upgrade if necessary. See C. Found in file sv.h =item SvUTF8 +X Returns a boolean indicating whether the SV contains UTF-8 encoded data. @@ -3743,6 +4426,7 @@ Returns a boolean indicating whether the SV contains UTF-8 encoded data. Found in file sv.h =item SvUTF8_off +X Unsets the UTF-8 status of an SV. @@ -3752,6 +4436,7 @@ Unsets the UTF-8 status of an SV. Found in file sv.h =item SvUTF8_on +X Turn on the UTF-8 status of an SV (the data is not changed, just the flag). Do not use frivolously. @@ -3762,6 +4447,7 @@ Do not use frivolously. Found in file sv.h =item SvUV +X Coerces the given SV to an unsigned integer and returns it. See C for a version which guarantees to evaluate sv only once. @@ -3772,6 +4458,7 @@ for a version which guarantees to evaluate sv only once. Found in file sv.h =item SvUVX +X 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. @@ -3782,6 +4469,7 @@ Only use when you are sure SvIOK is true. See also C. Found in file sv.h =item SvUVx +X Coerces the given SV to an unsigned integer and returns it. Guarantees to evaluate sv only once. Use the more efficient C otherwise. @@ -3792,6 +4480,7 @@ evaluate sv only once. Use the more efficient C otherwise. Found in file sv.h =item SvUV_nomg +X Like C but doesn't process magic. @@ -3800,16 +4489,250 @@ Like C but doesn't process magic. =for hackers Found in file sv.h +=item SvUV_set +X + +Set the value of the UV pointer in sv to val. See C. + + void SvUV_set(SV* sv, UV val) + +=for hackers +Found in file sv.h + =item SvVOK +X Returns a boolean indicating whether the SV contains a v-string. - bool SvVOK(SV* sv) + bool SvVOK(SV* sv) + +=for hackers +Found in file sv.h + +=item sv_catpvn_nomg +X + +Like C but doesn't process magic. + + void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) + +=for hackers +Found in file sv.h + +=item sv_catsv_nomg +X + +Like C but doesn't process magic. + + void sv_catsv_nomg(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + +=item sv_derived_from +X + +Returns a boolean indicating whether the SV is derived from the specified +class. This is the function that implements C. It works +for class names as well as for objects. + + bool sv_derived_from(SV* sv, const char* name) + +=for hackers +Found in file universal.c + +=item sv_report_used +X + +Dump the contents of all SVs not yet freed. (Debugging aid). + + void sv_report_used() + +=for hackers +Found in file sv.c + +=item sv_setsv_nomg +X + +Like C but doesn't process magic. + + void sv_setsv_nomg(SV* dsv, SV* ssv) + +=for hackers +Found in file sv.h + + +=back + +=head1 SV-Body Allocation + +=over 8 + +=item looks_like_number +X + +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. + + I32 looks_like_number(SV* sv) + +=for hackers +Found in file sv.c + +=item newRV_noinc +X + +Creates an RV wrapper for an SV. The reference count for the original +SV is B incremented. + + SV* newRV_noinc(SV* sv) + +=for hackers +Found in file sv.c + +=item newSV +X + +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 +trailing 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. + +In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first +parameter, I, a debug aid which allowed callers to identify themselves. +This aid has been superseded by a new build option, PERL_MEM_LOG (see +L). The older API is still there for use in XS +modules supporting older perls. + + SV* newSV(STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVhek +X + +Creates a new SV from the hash key structure. It will generate scalars that +point to the shared string table where possible. Returns a new (undefined) +SV if the hek is NULL. + + SV* newSVhek(const HEK *hek) + +=for hackers +Found in file sv.c + +=item newSViv +X + +Creates a new SV and copies an integer into it. The reference count for the +SV is set to 1. + + SV* newSViv(IV i) + +=for hackers +Found in file sv.c + +=item newSVnv +X + +Creates a new SV and copies a floating point value into it. +The reference count for the SV is set to 1. + + SV* newSVnv(NV n) + +=for hackers +Found in file sv.c + +=item newSVpv +X + +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) + +=for hackers +Found in file sv.c + +=item newSVpvf +X + +Creates a new SV and initializes it with the string formatted like +C. + + SV* newSVpvf(const char* pat, ...) + +=for hackers +Found in file sv.c + +=item newSVpvn +X + +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. If the C argument is NULL the new SV will be undefined. + + SV* newSVpvn(const char* s, STRLEN len) + +=for hackers +Found in file sv.c + +=item newSVpvn_share +X + +Creates a new SV with its SvPVX_const 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_const == HeKEY and +hash lookup will avoid string compare. + + SV* newSVpvn_share(const char* s, I32 len, U32 hash) + +=for hackers +Found in file sv.c + +=item newSVrv +X + +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) + +=for hackers +Found in file sv.c + +=item newSVsv +X + +Creates a new SV which is an exact duplicate of the original SV. +(Uses C). + + SV* newSVsv(SV* old) + +=for hackers +Found in file sv.c + +=item newSVuv +X + +Creates a new SV and copies an unsigned integer into it. +The reference count for the SV is set to 1. + + SV* newSVuv(UV u) =for hackers -Found in file sv.h +Found in file sv.c =item sv_2bool +X This function is only called on magical items, and is only used by sv_true() or its macro equivalent. @@ -3820,9 +4743,11 @@ sv_true() or its macro equivalent. Found in file sv.c =item sv_2cv +X Using various gambits, try to get a CV from an SV; in addition, try if possible to set C<*st> and C<*gvp> to the stash and GV associated with it. +The flags in C are passed to sv_fetchsv. CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref) @@ -3830,6 +4755,7 @@ possible to set C<*st> and C<*gvp> to the stash and GV associated with it. Found in file sv.c =item sv_2io +X Using various gambits, try to get an IO from an SV: the IO slot if its a GV; or the recursive result if we're an RV; or the IO slot of the symbol @@ -3841,6 +4767,7 @@ named after the PV if we're a string. Found in file sv.c =item sv_2iv_flags +X Return the integer value of an SV, doing any necessary string conversion. If flags includes SV_GMAGIC, does an mg_get() first. @@ -3852,6 +4779,7 @@ Normally used via the C and C macros. Found in file sv.c =item sv_2mortal +X Marks an existing SV as mortal. The SV will be destroyed "soon", either by an explicit call to FREETMPS, or by an implicit call at places such as @@ -3865,6 +4793,7 @@ and C. Found in file sv.c =item sv_2nv +X Return the num value of an SV, doing any necessary string or integer conversion, magic etc. Normally used via the C and C @@ -3876,6 +4805,7 @@ macros. Found in file sv.c =item sv_2pvbyte +X Return a pointer to the byte-encoded representation of the SV, and set *lp to its length. May cause the SV to be downgraded from UTF-8 as a @@ -3888,19 +4818,8 @@ Usually accessed via the C macro. =for hackers Found in file sv.c -=item sv_2pvbyte_nolen - -Return a pointer to the byte-encoded representation of the SV. -May cause the SV to be downgraded from UTF-8 as a side-effect. - -Usually accessed via the C macro. - - char* sv_2pvbyte_nolen(SV* sv) - -=for hackers -Found in file sv.c - =item sv_2pvutf8 +X Return a pointer to the UTF-8-encoded representation of the SV, and set *lp to its length. May cause the SV to be upgraded to UTF-8 as a side-effect. @@ -3912,19 +4831,8 @@ Usually accessed via the C macro. =for hackers Found in file sv.c -=item sv_2pvutf8_nolen - -Return a pointer to the UTF-8-encoded representation of the SV. -May cause the SV to be upgraded to UTF-8 as a side-effect. - -Usually accessed via the C macro. - - char* sv_2pvutf8_nolen(SV* sv) - -=for hackers -Found in file sv.c - =item sv_2pv_flags +X Returns a pointer to the string value of an SV, and sets *lp to its length. If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string @@ -3937,16 +4845,8 @@ usually end up here too. =for hackers Found in file sv.c -=item sv_2pv_nolen - -Like C, but doesn't return the length too. You should usually -use the macro wrapper C instead. - char* sv_2pv_nolen(SV* sv) - -=for hackers -Found in file sv.c - =item sv_2uv_flags +X Return the unsigned integer value of an SV, doing any necessary string conversion. If flags includes SV_GMAGIC, does an mg_get() first. @@ -3958,6 +4858,7 @@ Normally used via the C and C macros. Found in file sv.c =item sv_backoff +X Remove any string offset. You should normally use the C macro wrapper instead. @@ -3968,6 +4869,7 @@ wrapper instead. Found in file sv.c =item sv_bless +X Blesses an SV into a specified package. The SV must be an RV. The package must be designated by its stash (see C). The reference count @@ -3979,6 +4881,7 @@ of the SV is unaffected. Found in file sv.c =item sv_catpv +X Concatenates the string onto the end of the string which is in the SV. If the SV has the UTF-8 status set, then the bytes appended should be @@ -3990,6 +4893,7 @@ valid UTF-8. Handles 'get' magic, but not 'set' magic. See C. Found in file sv.c =item sv_catpvf +X Processes its arguments like C and appends the formatted output to an SV. If the appended data contains "wide" characters @@ -4005,6 +4909,7 @@ valid UTF-8; if the original SV was bytes, the pattern should be too. Found in file sv.c =item sv_catpvf_mg +X Like C, but also handles 'set' magic. @@ -4014,6 +4919,7 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_catpvn +X Concatenates the string onto the end of the string which is in the SV. The C indicates number of bytes to copy. If the SV has the UTF-8 @@ -4026,6 +4932,7 @@ Handles 'get' magic, but not 'set' magic. See C. Found in file sv.c =item sv_catpvn_flags +X Concatenates the string onto the end of the string which is in the SV. The C indicates number of bytes to copy. If the SV has the UTF-8 @@ -4039,25 +4946,8 @@ in terms of this function. =for hackers Found in file sv.c -=item sv_catpvn_mg - -Like C, but also handles 'set' magic. - - void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) - -=for hackers -Found in file sv.c - -=item sv_catpvn_nomg - -Like C but doesn't process magic. - - void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) - -=for hackers -Found in file sv.h - =item sv_catpv_mg +X Like C, but also handles 'set' magic. @@ -4067,6 +4957,7 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_catsv +X Concatenates the string from SV C onto the end of the string in SV C. Modifies C but not C. Handles 'get' magic, but @@ -4078,6 +4969,7 @@ not 'set' magic. See C. Found in file sv.c =item sv_catsv_flags +X Concatenates the string from SV C onto the end of the string in SV C. Modifies C but not C. If C has C @@ -4089,39 +4981,23 @@ and C are implemented in terms of this function. =for hackers Found in file sv.c -=item sv_catsv_mg - -Like C, but also handles 'set' magic. - - void sv_catsv_mg(SV *dstr, SV *sstr) - -=for hackers -Found in file sv.c - -=item sv_catsv_nomg - -Like C but doesn't process magic. - - void sv_catsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item sv_chop +X Efficient removal of characters from the beginning of the string buffer. SvPOK(sv) must be true and the C must be a pointer to somewhere inside the string buffer. The C becomes the first character of the adjusted string. Uses the "OOK hack". -Beware: after this function returns, C and SvPVX(sv) may no longer +Beware: after this function returns, C and SvPVX_const(sv) may no longer refer to the same chunk of data. - void sv_chop(SV* sv, char* ptr) + void sv_chop(SV* sv, const char* ptr) =for hackers Found in file sv.c =item sv_clear +X Clear an SV: call any destructors, free up any memory used by the body, and free the body itself. The SV's head is I freed, although @@ -4137,6 +5013,7 @@ instead. Found in file sv.c =item sv_cmp +X Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the string in C is less than, equal to, or greater than the string in @@ -4149,6 +5026,7 @@ coerce its args to strings if necessary. See also C. Found in file sv.c =item sv_cmp_locale +X Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and 'use bytes' aware, handles get magic, and will coerce its args to strings @@ -4160,6 +5038,7 @@ if necessary. See also C. See also C. Found in file sv.c =item sv_collxfrm +X Add Collate Transform magic to an SV if it doesn't already have it. @@ -4174,6 +5053,7 @@ settings. Found in file sv.c =item sv_copypv +X Copies a stringified representation of the source SV into the destination SV. Automatically performs any necessary mg_get and @@ -4189,6 +5069,7 @@ would lose the UTF-8'ness of the PV. Found in file sv.c =item sv_dec +X Auto-decrement of the value in the SV, doing string to numeric conversion if necessary. Handles 'get' magic. @@ -4198,18 +5079,8 @@ if necessary. Handles 'get' magic. =for hackers Found in file sv.c -=item sv_derived_from - -Returns a boolean indicating whether the SV is derived from the specified -class. This is the function that implements C. It works -for class names as well as for objects. - - bool sv_derived_from(SV* sv, const char* name) - -=for hackers -Found in file universal.c - =item sv_eq +X Returns a boolean indicating whether the strings in the two SVs are identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will @@ -4220,18 +5091,8 @@ coerce its args to strings if necessary. =for hackers Found in file sv.c -=item sv_force_normal - -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. See also C. - - void sv_force_normal(SV *sv) - -=for hackers -Found in file sv.c - =item sv_force_normal_flags +X 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 @@ -4249,6 +5110,7 @@ with flags set to 0. Found in file sv.c =item sv_free +X Decrement an SV's reference count, and if it drops to zero, call C to invoke destructors and free up any memory used by @@ -4261,6 +5123,7 @@ Normally called via a wrapper macro C. Found in file sv.c =item sv_gets +X Get a line from the filehandle and store it into the SV, optionally appending to the currently-stored string. @@ -4271,6 +5134,7 @@ appending to the currently-stored string. Found in file sv.c =item sv_grow +X Expands the character buffer in the SV. If necessary, uses C and upgrades the SV to C. Returns a pointer to the character buffer. @@ -4282,6 +5146,7 @@ Use the C wrapper instead. Found in file sv.c =item sv_inc +X Auto-increment of the value in the SV, doing string to numeric conversion if necessary. Handles 'get' magic. @@ -4292,6 +5157,7 @@ if necessary. Handles 'get' magic. Found in file sv.c =item sv_insert +X Inserts a string at the specified offset/length within the SV. Similar to the Perl substr() function. @@ -4302,6 +5168,7 @@ the Perl substr() function. Found in file sv.c =item sv_isa +X Returns a boolean indicating whether the SV is blessed into the specified class. This does not check for subtypes; use C to verify @@ -4313,6 +5180,7 @@ an inheritance relationship. Found in file sv.c =item sv_isobject +X Returns a boolean indicating whether the SV is an RV pointing to a blessed object. If the SV is not an RV, or if the object is not blessed, then this @@ -4323,17 +5191,8 @@ will return false. =for hackers Found in file sv.c -=item sv_iv - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - IV sv_iv(SV* sv) - -=for hackers -Found in file sv.c - =item sv_len +X Returns the length of the string in the SV. Handles magic and type coercion. See also C, which gives raw access to the xpv_cur slot. @@ -4344,6 +5203,7 @@ coercion. See also C, which gives raw access to the xpv_cur slot. Found in file sv.c =item sv_len_utf8 +X Returns the number of characters in the string in an SV, counting wide UTF-8 bytes as a single character. Handles magic and type coercion. @@ -4354,6 +5214,7 @@ UTF-8 bytes as a single character. Handles magic and type coercion. Found in file sv.c =item sv_magic +X 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. @@ -4370,6 +5231,7 @@ to add more than one instance of the same 'how'. Found in file sv.c =item sv_magicext +X Adds magic to an SV, upgrading it if necessary. Applies the supplied vtable and returns a pointer to the magic added. @@ -4385,12 +5247,13 @@ to contain an C and is stored as-is with its REFCNT incremented. (This is now used as a subroutine by C.) - MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen) + 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 +X Creates a new SV which is a copy of the original SV (using C). The new SV is marked as mortal. It will be destroyed "soon", either by an @@ -4403,6 +5266,7 @@ statement boundaries. See also C and C. Found in file sv.c =item sv_newmortal +X Creates a new null SV which is mortal. The reference count of the SV is set to 1. It will be destroyed "soon", either by an explicit call to @@ -4415,6 +5279,7 @@ See also C and C. Found in file sv.c =item sv_newref +X Increment an SV's reference count. Use the C wrapper instead. @@ -4424,17 +5289,8 @@ instead. =for hackers Found in file sv.c -=item sv_nv - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - NV sv_nv(SV* sv) - -=for hackers -Found in file sv.c - =item sv_pos_b2u +X Converts the value pointed to by offsetp from a count of bytes from the start of the string, to a count of the equivalent number of UTF-8 chars. @@ -4446,6 +5302,7 @@ Handles magic and type coercion. Found in file sv.c =item sv_pos_u2b +X Converts the value pointed to by offsetp from a count of UTF-8 chars from the start of the string, to a count of the equivalent number of bytes; if @@ -4458,57 +5315,18 @@ type coercion. =for hackers Found in file sv.c -=item sv_pv - -Use the C macro instead - - char* sv_pv(SV *sv) - -=for hackers -Found in file sv.c - -=item sv_pvbyte - -Use C instead. - - char* sv_pvbyte(SV *sv) - -=for hackers -Found in file sv.c - -=item sv_pvbyten - -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. - - char* sv_pvbyten(SV *sv, STRLEN *len) - -=for hackers -Found in file sv.c - =item sv_pvbyten_force +X -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. +The backend for the C macro. Always use the macro instead. char* sv_pvbyten_force(SV* sv, STRLEN* lp) =for hackers Found in file sv.c -=item sv_pvn - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - char* sv_pvn(SV *sv, STRLEN *len) - -=for hackers -Found in file sv.c - =item sv_pvn_force +X Get a sensible string out of the SV somehow. A private implementation of the C macro for compilers which @@ -4520,6 +5338,7 @@ can't cope with complex macro expressions. Always use the macro instead. Found in file sv.c =item sv_pvn_force_flags +X Get a sensible string out of the SV somehow. If C has C bit set, will C on C if @@ -4533,31 +5352,10 @@ C and C =for hackers Found in file sv.c -=item sv_pvutf8 - -Use the C macro instead - - char* sv_pvutf8(SV *sv) - -=for hackers -Found in file sv.c - -=item sv_pvutf8n - -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. - - char* sv_pvutf8n(SV *sv, STRLEN *len) - -=for hackers -Found in file sv.c - =item sv_pvutf8n_force +X -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. +The backend for the C macro. Always use the macro instead. char* sv_pvutf8n_force(SV* sv, STRLEN* lp) @@ -4565,15 +5363,17 @@ instead. Found in file sv.c =item sv_reftype +X Returns a string describing what the SV is a reference to. - const char* sv_reftype(const SV* sv, int ob) + char* sv_reftype(const SV* sv, int ob) =for hackers Found in file sv.c =item sv_replace +X Make the first argument a copy of the second, then delete the original. The target SV physically takes over ownership of the body of the source SV @@ -4587,16 +5387,8 @@ time you'll want to use C or one of its many macro front-ends. =for hackers Found in file sv.c -=item sv_report_used - -Dump the contents of all SVs not yet freed. (Debugging aid). - - void sv_report_used() - -=for hackers -Found in file sv.c - =item sv_reset +X Underlying implementation for the C Perl function. Note that the perl-level function is vaguely deprecated. @@ -4607,6 +5399,7 @@ Note that the perl-level function is vaguely deprecated. Found in file sv.c =item sv_rvweaken +X Weaken a reference: set the C flag on this RV; give the referred-to SV C magic if it hasn't already; and @@ -4619,6 +5412,7 @@ associated with that magic. Found in file sv.c =item sv_setiv +X Copies an integer into the given SV, upgrading first if necessary. Does not handle 'set' magic. See also C. @@ -4629,6 +5423,7 @@ Does not handle 'set' magic. See also C. Found in file sv.c =item sv_setiv_mg +X Like C, but also handles 'set' magic. @@ -4638,6 +5433,7 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_setnv +X Copies a double into the given SV, upgrading first if necessary. Does not handle 'set' magic. See also C. @@ -4648,6 +5444,7 @@ Does not handle 'set' magic. See also C. Found in file sv.c =item sv_setnv_mg +X Like C, but also handles 'set' magic. @@ -4657,6 +5454,7 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_setpv +X Copies a string into an SV. The string must be null-terminated. Does not handle 'set' magic. See C. @@ -4667,6 +5465,7 @@ handle 'set' magic. See C. Found in file sv.c =item sv_setpvf +X Works like C but copies the text into the SV instead of appending it. Does not handle 'set' magic. See C. @@ -4677,6 +5476,7 @@ appending it. Does not handle 'set' magic. See C. Found in file sv.c =item sv_setpvf_mg +X Like C, but also handles 'set' magic. @@ -4686,6 +5486,7 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_setpviv +X Copies an integer into the given SV, also updating its string value. Does not handle 'set' magic. See C. @@ -4696,6 +5497,7 @@ Does not handle 'set' magic. See C. Found in file sv.c =item sv_setpviv_mg +X Like C, but also handles 'set' magic. @@ -4705,6 +5507,7 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_setpvn +X Copies a string into an SV. The C parameter indicates the number of bytes to be copied. If the C argument is NULL the SV will become @@ -4716,6 +5519,7 @@ undefined. Does not handle 'set' magic. See C. Found in file sv.c =item sv_setpvn_mg +X Like C, but also handles 'set' magic. @@ -4725,6 +5529,7 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_setpv_mg +X Like C, but also handles 'set' magic. @@ -4734,11 +5539,12 @@ Like C, but also handles 'set' magic. Found in file sv.c =item sv_setref_iv +X Copies an integer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_iv(SV* rv, const char* classname, IV iv) @@ -4747,11 +5553,12 @@ will have a reference count of 1, and the RV will be returned. Found in file sv.c =item sv_setref_nv +X Copies a double into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_nv(SV* rv, const char* classname, NV nv) @@ -4760,12 +5567,13 @@ will have a reference count of 1, and the RV will be returned. Found in file sv.c =item sv_setref_pv +X Copies a pointer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. If the C argument is NULL then C will be placed into the SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. Do not use with other Perl types such as HV, AV, SV, CV, because those @@ -4779,27 +5587,29 @@ Note that C copies the string while this copies the pointer. Found in file sv.c =item sv_setref_pvn +X Copies a string into a new SV, optionally blessing the SV. The length of the string must be specified with C. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the blessing. Set C to -C to avoid the blessing. The new SV will have a reference count +C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. Note that C copies the pointer while this copies the string. - SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n) + SV* sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n) =for hackers Found in file sv.c =item sv_setref_uv +X Copies an unsigned integer into a new SV, optionally blessing the SV. The C argument will be upgraded to an RV. That RV will be modified to point to the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV +blessing. Set C to C to avoid the blessing. The new SV will have a reference count of 1, and the RV will be returned. SV* sv_setref_uv(SV* rv, const char* classname, UV uv) @@ -4808,6 +5618,7 @@ will have a reference count of 1, and the RV will be returned. Found in file sv.c =item sv_setsv +X Copies the contents of the source SV C into the destination SV C. The source SV may be destroyed if it is mortal, so don't use this @@ -4825,6 +5636,7 @@ C. Found in file sv.c =item sv_setsv_flags +X Copies the contents of the source SV C into the destination SV C. The source SV may be destroyed if it is mortal, so don't use this @@ -4849,6 +5661,7 @@ copy-ish functions and macros use this underneath. Found in file sv.c =item sv_setsv_mg +X Like C, but also handles 'set' magic. @@ -4857,16 +5670,8 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c -=item sv_setsv_nomg - -Like C but doesn't process magic. - - void sv_setsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - =item sv_setuv +X Copies an unsigned integer into the given SV, upgrading first if necessary. Does not handle 'set' magic. See also C. @@ -4877,6 +5682,7 @@ Does not handle 'set' magic. See also C. Found in file sv.c =item sv_setuv_mg +X Like C, but also handles 'set' magic. @@ -4885,15 +5691,8 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c -=item sv_taint - -Taint an SV. Use C instead. - void sv_taint(SV* sv) - -=for hackers -Found in file sv.c - =item sv_tainted +X Test an SV for taintedness. Use C instead. bool sv_tainted(SV* sv) @@ -4902,6 +5701,7 @@ Test an SV for taintedness. Use C instead. Found in file sv.c =item sv_true +X Returns true if the SV has a true value by Perl's rules. Use the C macro instead, which may call C or may @@ -4913,6 +5713,7 @@ instead use an in-line version. Found in file sv.c =item sv_unmagic +X Removes all magic of type C from an SV. @@ -4921,19 +5722,8 @@ Removes all magic of type C from an SV. =for hackers Found in file sv.c -=item sv_unref - -Unsets the RV status of the SV, and decrements the reference count of -whatever was being referenced by the RV. This can almost be thought of -as a reversal of C. This is C with the C -being zero. See C. - - void sv_unref(SV* sv) - -=for hackers -Found in file sv.c - =item sv_unref_flags +X Unsets the RV status of the SV, and decrements the reference count of whatever was being referenced by the RV. This can almost be thought of @@ -4949,6 +5739,7 @@ See C. Found in file sv.c =item sv_untaint +X Untaint an SV. Use C instead. void sv_untaint(SV* sv) @@ -4957,41 +5748,41 @@ Untaint an SV. Use C instead. Found in file sv.c =item sv_upgrade +X Upgrade an SV to a more complex form. Generally adds a new body type to the SV, then copies across as much information as possible from the old body. You generally want to use the C macro wrapper. See also C. - bool sv_upgrade(SV* sv, U32 mt) + void sv_upgrade(SV* sv, U32 mt) =for hackers Found in file sv.c -=item sv_usepvn - -Tells an SV to use C to find its string value. Normally the string is -stored inside the SV but sv_usepvn allows the SV to use an outside string. -The C should point to memory that was allocated by C. The -string length, C, must be supplied. This function will realloc the -memory pointed to by C, so that pointer should not be freed or used by -the programmer after giving it to sv_usepvn. Does not handle 'set' magic. -See C. - - void sv_usepvn(SV* sv, char* ptr, STRLEN len) - -=for hackers -Found in file sv.c +=item sv_usepvn_flags +X -=item sv_usepvn_mg +Tells an SV to use C to find its string value. Normally the +string is stored inside the SV but sv_usepvn allows the SV to use an +outside string. The C should point to memory that was allocated +by C. The string length, C, must be supplied. By default +this function will realloc (i.e. move) the memory pointed to by C, +so that pointer should not be freed or used by the programmer after +giving it to sv_usepvn, and neither should any pointers from "behind" +that pointer (e.g. ptr + 1) be used. -Like C, but also handles 'set' magic. +If C & SV_SMAGIC is true, will call SvSETMAGIC. If C & +SV_HAS_TRAILING_NUL is true, then C must be NUL, and the realloc +will be skipped. (i.e. the buffer is actually at least 1 byte longer than +C, and already meets the requirements for storing in C) - void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) + void sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags) =for hackers Found in file sv.c =item sv_utf8_decode +X If the PV of the SV is an octet sequence in UTF-8 and contains a multiple-byte character, the C flag is turned on @@ -5008,6 +5799,7 @@ removed without notice. Found in file sv.c =item sv_utf8_downgrade +X Attempts to convert the PV of an SV from characters to bytes. If the PV contains a character beyond byte, this conversion will fail; @@ -5026,6 +5818,7 @@ removed without notice. Found in file sv.c =item sv_utf8_encode +X Converts the PV of an SV to UTF-8, but then turns the C flag off so that it looks like octets again. @@ -5036,6 +5829,7 @@ flag off so that it looks like octets again. Found in file sv.c =item sv_utf8_upgrade +X Converts the PV of an SV to its UTF-8-encoded form. Forces the SV to string form if it is not already. @@ -5051,6 +5845,7 @@ use the Encode extension for that. Found in file sv.c =item sv_utf8_upgrade_flags +X Converts the PV of an SV to its UTF-8-encoded form. Forces the SV to string form if it is not already. @@ -5067,17 +5862,8 @@ use the Encode extension for that. =for hackers Found in file sv.c -=item sv_uv - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - UV sv_uv(SV* sv) - -=for hackers -Found in file sv.c - =item sv_vcatpvf +X Processes its arguments like C and appends the formatted output to an SV. Does not handle 'set' magic. See C. @@ -5090,6 +5876,7 @@ Usually used via its frontend C. Found in file sv.c =item sv_vcatpvfn +X Processes its arguments like C and appends the formatted output to an SV. Uses an array of SVs if the C style variable argument list is @@ -5105,6 +5892,7 @@ Usually used via one of its frontends C and C. Found in file sv.c =item sv_vcatpvf_mg +X Like C, but also handles 'set' magic. @@ -5116,6 +5904,7 @@ Usually used via its frontend C. Found in file sv.c =item sv_vsetpvf +X Works like C but copies the text into the SV instead of appending it. Does not handle 'set' magic. See C. @@ -5128,6 +5917,7 @@ Usually used via its frontend C. Found in file sv.c =item sv_vsetpvfn +X Works like C but copies the text into the SV instead of appending it. @@ -5140,6 +5930,7 @@ Usually used via one of its frontends C and C. Found in file sv.c =item sv_vsetpvf_mg +X Like C, but also handles 'set' magic. @@ -5158,6 +5949,7 @@ Found in file sv.c =over 8 =item bytes_from_utf8 +X Converts a string C of length C from UTF-8 into byte encoding. Unlike C but like C, returns a pointer to @@ -5175,6 +5967,7 @@ removed without notice. Found in file utf8.c =item bytes_to_utf8 +X Converts a string C of length C from ASCII into UTF-8 encoding. Returns a pointer to the newly-created string, and sets C to @@ -5192,6 +5985,7 @@ removed without notice. Found in file utf8.c =item ibcmp_utf8 +X 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 @@ -5220,6 +6014,7 @@ http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). Found in file utf8.c =item is_utf8_char +X 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 @@ -5232,28 +6027,51 @@ will be returned if it is valid, otherwise 0. Found in file utf8.c =item is_utf8_string +X Returns true if first C bytes of the given string form a valid UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does not mean 'a string that contains code points above 0x7F encoded in UTF-8' because a valid ASCII string is a valid UTF-8 string. +See also is_utf8_string_loclen() and is_utf8_string_loc(). + bool is_utf8_string(const U8 *s, STRLEN len) =for hackers Found in file utf8.c =item is_utf8_string_loc +X -Like is_ut8_string but store the location of the failure in -the last argument. +Like is_utf8_string() but stores the location of the failure (in the +case of "utf8ness failure") or the location s+len (in the case of +"utf8ness success") in the C. + +See also is_utf8_string_loclen() and is_utf8_string(). bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p) =for hackers Found in file utf8.c +=item is_utf8_string_loclen +X + +Like is_utf8_string() but stores the location of the failure (in the +case of "utf8ness failure") or the location s+len (in the case of +"utf8ness success") in the C, and the number of UTF-8 +encoded characters in the C. + +See also is_utf8_string_loc() and is_utf8_string(). + + bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el) + +=for hackers +Found in file utf8.c + =item pv_uni_display +X Build to the scalar dsv a displayable version of the string spv, length len, the displayable version being at most pvlim bytes long @@ -5274,6 +6092,7 @@ The pointer to the PV of the dsv is returned. Found in file utf8.c =item sv_cat_decode +X 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 @@ -5291,6 +6110,7 @@ Returns TRUE if the terminator was found, else returns FALSE. Found in file sv.c =item sv_recode_to_utf8 +X 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 @@ -5309,6 +6129,7 @@ The PV of the sv is returned. Found in file sv.c =item sv_uni_display +X Build to the scalar dsv a displayable version of the scalar sv, the displayable version being at most pvlim bytes long @@ -5324,6 +6145,7 @@ The pointer to the PV of the dsv is returned. Found in file utf8.c =item to_utf8_case +X The "p" contains the pointer to the UTF-8 string encoding the character that is being converted. @@ -5335,7 +6157,7 @@ of the result. The "swashp" is a pointer to the swash to use. 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, +and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually, but not always, a multicharacter mapping), is tried first. The "special" is a string like "utf8::ToSpecLower", which means the @@ -5345,12 +6167,13 @@ Perl_to_utf8_case(). The "normal" is a string like "ToLower" which means the swash %utf8::ToLower. - UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, const char *normal, const char *special) + UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special) =for hackers Found in file utf8.c =item to_utf8_fold +X 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 @@ -5367,6 +6190,7 @@ The first character of the foldcased version is returned Found in file utf8.c =item to_utf8_lower +X 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 @@ -5382,6 +6206,7 @@ The first character of the lowercased version is returned Found in file utf8.c =item to_utf8_title +X 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 @@ -5397,6 +6222,7 @@ The first character of the titlecased version is returned Found in file utf8.c =item to_utf8_upper +X 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 @@ -5412,19 +6238,24 @@ The first character of the uppercased version is returned Found in file utf8.c =item utf8n_to_uvchr +X -Returns the native character value of the first character in the string C +flags + +Returns the native character value of the first character in the string +C which is assumed to be in UTF-8 encoding; C will be set to the length, in bytes, of that character. Allows length and flags to be passed to low level routine. - UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) + UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) =for hackers Found in file utf8.c =item utf8n_to_uvuni +X Bottom level UTF-8 decode routine. Returns the unicode code point value of the first character in the string C @@ -5444,12 +6275,13 @@ the strict UTF-8 encoding (see F). Most code should use utf8_to_uvchr() rather than call this directly. - UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags) + UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) =for hackers Found in file utf8.c =item utf8_distance +X Returns the number of UTF-8 characters between the UTF-8 pointers C and C. @@ -5463,6 +6295,7 @@ same UTF-8 buffer. Found in file utf8.c =item utf8_hop +X Return the UTF-8 pointer C displaced by C characters, either forward or backward. @@ -5471,12 +6304,13 @@ WARNING: do not use the following unless you *know* C is within the UTF-8 data pointed to by C *and* that on entry C is aligned on the first byte of character or just after the last byte of a character. - U8* utf8_hop(U8 *s, I32 off) + U8* utf8_hop(const U8 *s, I32 off) =for hackers Found in file utf8.c =item utf8_length +X Return the length of the UTF-8 char encoded string C in characters. Stops at C (inclusive). If C s> or if the scan would end @@ -5488,12 +6322,15 @@ up past C, croaks. Found in file utf8.c =item utf8_to_bytes +X Converts a string C of length C from UTF-8 into byte encoding. Unlike C, this over-writes the original string, and updates len to contain the new length. Returns zero on failure, setting C to -1. +If you need a copy of the string, see C. + NOTE: this function is experimental and may change or be removed without notice. @@ -5503,6 +6340,7 @@ removed without notice. Found in file utf8.c =item utf8_to_uvchr +X Returns the native character value of the first character in the string C which is assumed to be in UTF-8 encoding; C will be set to the @@ -5511,12 +6349,13 @@ length, in bytes, of that character. If C does not point to a well-formed UTF-8 character, zero is returned and retlen is set, if possible, to -1. - UV utf8_to_uvchr(const U8 *s, STRLEN* retlen) + UV utf8_to_uvchr(const U8 *s, STRLEN *retlen) =for hackers Found in file utf8.c =item utf8_to_uvuni +X Returns the Unicode code point of the first character in the string C which is assumed to be in UTF-8 encoding; C will be set to the @@ -5528,12 +6367,13 @@ an index into the Unicode semantic tables (e.g. swashes). If C does not point to a well-formed UTF-8 character, zero is returned and retlen is set, if possible, to -1. - UV utf8_to_uvuni(const U8 *s, STRLEN* retlen) + UV utf8_to_uvuni(const U8 *s, STRLEN *retlen) =for hackers Found in file utf8.c =item uvchr_to_utf8 +X Adds the UTF-8 representation of the Native codepoint C to the end of the string C; C should be have at least C free @@ -5552,6 +6392,7 @@ is the recommended wide native character-aware way of saying Found in file utf8.c =item uvuni_to_utf8_flags +X Adds the UTF-8 representation of the Unicode codepoint C to the end of the string C; C should be have at least C free @@ -5585,6 +6426,7 @@ Found in file utf8.c =over 8 =item ax +X Variable which is setup by C to indicate the stack base offset, used by the C, C and C macros. The C macro @@ -5596,6 +6438,7 @@ must be called prior to setup the C variable. Found in file XSUB.h =item CLASS +X Variable which is setup by C to indicate the class name for a C++ XS constructor. This is always a C. See C. @@ -5606,6 +6449,7 @@ class name for a C++ XS constructor. This is always a C. See C. Found in file XSUB.h =item dAX +X Sets up the C variable. This is usually handled automatically by C by calling C. @@ -5615,7 +6459,19 @@ This is usually handled automatically by C by calling C. =for hackers Found in file XSUB.h +=item dAXMARK +X + +Sets up the C variable and stack marker variable C. +This is usually handled automatically by C by calling C. + + dAXMARK; + +=for hackers +Found in file XSUB.h + =item dITEMS +X Sets up the C variable. This is usually handled automatically by C by calling C. @@ -5626,6 +6482,7 @@ This is usually handled automatically by C by calling C. Found in file XSUB.h =item dUNDERBAR +X Sets up the C variable for an XSUB that wishes to use C. @@ -5636,6 +6493,7 @@ C. Found in file XSUB.h =item dXSARGS +X 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. @@ -5647,6 +6505,7 @@ This is usually handled automatically by C. Found in file XSUB.h =item dXSI32 +X Sets up the C variable for an XSUB which has aliases. This is usually handled automatically by C. @@ -5657,6 +6516,7 @@ handled automatically by C. Found in file XSUB.h =item items +X Variable which is setup by C to indicate the number of items on the stack. See L. @@ -5667,6 +6527,7 @@ items on the stack. See L. Found in file XSUB.h =item ix +X Variable which is setup by C to indicate which of an XSUB's aliases was used to invoke it. See L. @@ -5677,6 +6538,7 @@ XSUB's aliases was used to invoke it. See L. Found in file XSUB.h =item newXSproto +X Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to the subs. @@ -5685,6 +6547,7 @@ the subs. Found in file XSUB.h =item RETVAL +X Variable which is setup by C to hold the return value for an XSUB. This is always the proper type for the XSUB. See @@ -5696,6 +6559,7 @@ L. Found in file XSUB.h =item ST +X Used to access elements on the XSUB's stack. @@ -5705,6 +6569,7 @@ Used to access elements on the XSUB's stack. Found in file XSUB.h =item THIS +X 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 @@ -5716,6 +6581,7 @@ L. Found in file XSUB.h =item UNDERBAR +X The SV* corresponding to the $_ variable. Works even if there is a lexical $_ in scope. @@ -5724,6 +6590,7 @@ is a lexical $_ in scope. Found in file XSUB.h =item XS +X Macro to declare an XSUB and its C parameter list. This is handled by C. @@ -5732,6 +6599,7 @@ C. Found in file XSUB.h =item XS_VERSION +X The version identifier for an XS module. This is usually handled automatically by C. See C. @@ -5740,6 +6608,7 @@ handled automatically by C. See C. Found in file XSUB.h =item XS_VERSION_BOOTCHECK +X Macro to verify that a PM module's $VERSION variable matches the XS module's C variable. This is usually handled automatically by @@ -5758,6 +6627,7 @@ Found in file XSUB.h =over 8 =item croak +X This is the XSUB-writer's interface to Perl's C function. Normally call this function the same way you call the C C @@ -5765,11 +6635,11 @@ function. Calling C returns control directly to Perl, sidestepping the normal C order of execution. See C. If you want to throw an exception object, assign the object to -C<$@> and then pass C to croak(): +C<$@> and then pass C to croak(): errsv = get_sv("@", TRUE); sv_setsv(errsv, exception_object); - croak(Nullch); + croak(NULL); void croak(const char* pat, ...) @@ -5777,6 +6647,7 @@ C<$@> and then pass C to croak(): Found in file util.c =item warn +X This is the XSUB-writer's interface to Perl's C function. Call this function the same way you call the C C function. See C.