X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlapi.pod;h=3ea050e9434e2f9192e6a229bd9940596a15b327;hb=bd95ae50406ae1b55da3f57111cd4644d9d82c6a;hp=6b603bf77475618777bae468d55b42f87411af10;hpb=1b6737cc10a847650f574c35f419cbd680a5a5ef;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 6b603bf..3ea050e 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -1,8 +1,15 @@ +-*- buffer-read-only: t -*- + +!!!!!!! DO NOT EDIT THIS FILE !!!!!!! +This file is built by autodoc.pl extracting documentation from the C source +files. + =head1 NAME 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 +30,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 +42,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 +54,7 @@ respectively. Found in file op.h =item G_ARRAY +X Used to indicate list context. See C, C and L. @@ -53,6 +63,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 +72,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 +81,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 +90,7 @@ L. Found in file cop.h =item G_SCALAR +X Used to indicate scalar context. See C, C, and L. @@ -85,6 +99,7 @@ L. Found in file cop.h =item G_VOID +X Used to indicate void context. See C and L. @@ -99,6 +114,7 @@ Found in file cop.h =over 8 =item AvFILL +X Same as C. Deprecated, use C instead. @@ -108,6 +124,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 +135,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 +147,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 +160,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 +171,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,19 +186,27 @@ 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 +Set the highest index in the array to the given number, equivalent to Perl's C<$#array = $fill;>. +The number of elements in the an array will be C after +av_fill() returns. If the array was previously shorter then the +additional elements appended are set to C. If the array +was longer, then the excess elements are freed. C is +the same as C. + void av_fill(AV* ar, I32 fill) =for hackers Found in file av.c =item av_len +X -Returns the highest index in the array. Returns -1 if the array is -empty. +Returns the highest index in the array. The number of elements in the +array is C. Returns -1 if the array is empty. I32 av_len(const AV* ar) @@ -185,6 +214,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 +226,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 +237,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 +248,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 +258,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 +277,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 +287,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 +299,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 +313,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 +323,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) + +=for hackers +Found in file pp_sort.c + +=item sortsv_flags +X - void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp) +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 +355,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 +367,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 +380,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 +392,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 +405,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 +415,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 +427,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 +439,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 +450,7 @@ L. Found in file scope.h =item LEAVE +X Closing bracket on a callback. See C and L. @@ -401,6 +460,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 +478,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 +489,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 +500,7 @@ character. Found in file handy.h =item isDIGIT +X Returns a boolean indicating whether the C C is an ASCII digit. @@ -448,6 +511,7 @@ digit. Found in file handy.h =item isLOWER +X Returns a boolean indicating whether the C C is a lowercase character. @@ -458,6 +522,7 @@ character. Found in file handy.h =item isSPACE +X Returns a boolean indicating whether the C C is whitespace. @@ -467,6 +532,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 +543,7 @@ character. Found in file handy.h =item toLOWER +X Converts the specified character to lowercase. @@ -486,6 +553,7 @@ Converts the specified character to lowercase. Found in file handy.h =item toUPPER +X Converts the specified character to uppercase. @@ -502,6 +570,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 +616,7 @@ Found in file sv.c =over 8 =item CvSTASH +X Returns the stash of the CV. @@ -556,6 +626,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 +648,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 +661,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 +678,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 +689,7 @@ no threads. Found in file perl.c =item perl_alloc +X Allocates a new Perl interpreter. See L. @@ -624,6 +699,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 +709,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 +719,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 +729,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 +739,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 +749,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,287 +765,683 @@ Found in file perl.c =back -=head1 Functions in file pp_pack.c +=head1 Functions in file dump.c =over 8 -=item packlist +=item pv_display +X -The engine implementing pack() Perl function. + char *pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, + STRLEN pvlim, U32 flags) - void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist) +Similar to -=for hackers -Found in file pp_pack.c + pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE); -=item pack_cat +except that an additional "\0" will be appended to the string when +len > cur and pv[cur] is "\0". -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. +Note that the final string may be up to 7 chars longer than pvlim. - void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags) + char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim) =for hackers -Found in file pp_pack.c +Found in file dump.c -=item unpackstring - -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. +=item pv_escape +X - I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags) + |const STRLEN count|const STRLEN max + |STRLEN const *escaped, const U32 flags -=for hackers -Found in file pp_pack.c +Escapes at most the first "count" chars of pv and puts the results into +dsv such that the size of the escaped string will not exceed "max" chars +and will not contain any incomplete escape sequences. -=item unpack_str +If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string +will also be escaped. -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. +Normally the SV will be cleared before the escaped string is prepared, +but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur. - 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) +If PERL_PV_ESCAPE_UNI is set then the input string is treated as unicode, +if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned +using C to determine if it is unicode. -=for hackers -Found in file pp_pack.c +If PERL_PV_ESCAPE_ALL is set then all input chars will be output +using C<\x01F1> style escapes, otherwise only chars above 255 will be +escaped using this style, other non printable chars will use octal or +common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH +then all chars below 255 will be treated as printable and +will be output as literals. +If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the +string will be escaped, regardles of max. If the string is utf8 and +the chars value is >255 then it will be returned as a plain hex +sequence. Thus the output will either be a single char, +an octal escape sequence, a special escape like C<\n> or a 3 or +more digit hex value. -=back +Returns a pointer to the escaped text as held by dsv. -=head1 Global Variables +NOTE: the perl_ form of this function is deprecated. -=over 8 + char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags) -=item PL_modglobal +=for hackers +Found in file dump.c -C is a general purpose, interpreter global HV for use by -extensions that need to keep information on a per-interpreter basis. -In a pinch, it can also be used as a symbol table for extensions -to share data among each other. It is a good idea to use keys -prefixed by the package name of the extension that owns the data. +=item pv_pretty +X - HV* PL_modglobal + |const STRLEN count|const STRLEN max\ + |const char const *start_color| const char const *end_color\ + |const U32 flags -=for hackers -Found in file intrpvar.h +Converts a string into something presentable, handling escaping via +pv_escape() and supporting quoting and elipses. -=item PL_na +If the PERL_PV_PRETTY_QUOTE flag is set then the result will be +double quoted with any double quotes in the string escaped. Otherwise +if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in +angle brackets. + +If the PERL_PV_PRETTY_ELIPSES flag is set and not all characters in +string were output then an elipses C<...> will be appended to the +string. Note that this happens AFTER it has been quoted. + +If start_color is non-null then it will be inserted after the opening +quote (if there is one) but before the escaped text. If end_color +is non-null then it will be inserted after the escaped text but before +any quotes or elipses. -A convenience variable which is typically used with C when one -doesn't care about the length of the string. It is usually more efficient -to either declare a local variable and use that instead or to use the -C macro. +Returns a pointer to the prettified text as held by dsv. + +NOTE: the perl_ form of this function is deprecated. - STRLEN PL_na + char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags) =for hackers -Found in file thrdvar.h +Found in file dump.c -=item PL_sv_no -This is the C SV. See C. Always refer to this as -C<&PL_sv_no>. +=back - SV PL_sv_no +=head1 Functions in file mathoms.c -=for hackers -Found in file intrpvar.h -=item PL_sv_undef +=over 8 -This is the C SV. Always refer to this as C<&PL_sv_undef>. +=item gv_fetchmethod +X - SV PL_sv_undef +See L. + + GV* gv_fetchmethod(HV* stash, const char* name) =for hackers -Found in file intrpvar.h +Found in file mathoms.c -=item PL_sv_yes +=item pack_cat +X -This is the C SV. See C. Always refer to this as -C<&PL_sv_yes>. +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. - SV PL_sv_yes + 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 intrpvar.h +Found in file mathoms.c +=item sv_2pvbyte_nolen +X -=back +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. -=head1 GV Functions +Usually accessed via the C macro. -=over 8 + char* sv_2pvbyte_nolen(SV* sv) -=item GvSV +=for hackers +Found in file mathoms.c -Return the SV from the GV. +=item sv_2pvutf8_nolen +X - SV* GvSV(GV* gv) +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 gv.h +Found in file mathoms.c -=item gv_fetchmeth +=item sv_2pv_nolen +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 -accessible via @ISA and UNIVERSAL::. +Like C, but doesn't return the length too. You should usually +use the macro wrapper C instead. + char* sv_2pv_nolen(SV* sv) -The argument C should be either 0 or -1. If C, as a -side-effect creates a glob with the given C in the given C -which in the case of success contains an alias for the subroutine, and sets -up caching info for this glob. Similarly for all the searched stashes. +=for hackers +Found in file mathoms.c -This function grants C<"SUPER"> token as a postfix of the stash name. The -GV returned from C may be a method cache entry, which is not -visible to Perl code. So when calling C, you should not use -the GV directly; instead, you should use the method's CV, which can be -obtained from the GV with the C macro. +=item sv_catpvn_mg +X - GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) +Like C, but also handles 'set' magic. + + void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) =for hackers -Found in file gv.c +Found in file mathoms.c -=item gv_fetchmethod +=item sv_catsv_mg +X -See L. +Like C, but also handles 'set' magic. - GV* gv_fetchmethod(HV* stash, const char* name) + void sv_catsv_mg(SV *dstr, SV *sstr) =for hackers -Found in file gv.c +Found in file mathoms.c -=item gv_fetchmethod_autoload +=item sv_force_normal +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 -glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is -already setup. +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. -The third parameter of C determines whether -AUTOLOAD lookup is performed if the given method is not present: non-zero -means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. -Calling C is equivalent to calling C -with a non-zero C parameter. + void sv_force_normal(SV *sv) -These functions grant C<"SUPER"> token as a prefix of the method name. Note -that if you want to keep the returned glob for a long time, you need to -check for it being "AUTOLOAD", since at the later time the call may load a -different subroutine due to $AUTOLOAD changing its value. Use the glob -created via a side effect to do this. +=for hackers +Found in file mathoms.c -These functions have the same side-effects and as C with -C. C should be writable if contains C<':'> or C<' -''>. The warning against passing the GV returned by C to -C apply equally to these functions. +=item sv_iv +X - GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) +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 gv.c +Found in file mathoms.c -=item gv_fetchmeth_autoload +=item sv_nolocking +X -Same as gv_fetchmeth(), but looks for autoloaded subroutines too. -Returns a glob for the subroutine. +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. -For an autoloaded subroutine without a GV, will create a GV even -if C. For an autoloaded subroutine without a stub, GvCV() -of the result may be zero. +"Superseded" by sv_nosharing(). - GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) + void sv_nolocking(SV *sv) =for hackers -Found in file gv.c +Found in file mathoms.c -=item gv_stashpv +=item sv_nounlocking +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 -then the package will be created if it does not already exist. If C -is not set and the package does not exist then NULL is returned. +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. - HV* gv_stashpv(const char* name, I32 create) +"Superseded" by sv_nosharing(). + + void sv_nounlocking(SV *sv) =for hackers -Found in file gv.c +Found in file mathoms.c -=item gv_stashpvn +=item sv_nv +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 -the C, in bytes. If C is set then the package will be -created if it does not already exist. If C is not set and the -package does not exist then NULL is returned. +A private implementation of the C macro for compilers which can't +cope with complex macro expressions. Always use the macro instead. - HV* gv_stashpvn(const char* name, U32 namelen, I32 create) + NV sv_nv(SV* sv) =for hackers -Found in file gv.c +Found in file mathoms.c -=item gv_stashsv +=item sv_pv +X -Returns a pointer to the stash for a specified package, which must be a -valid UTF-8 string. See C. +Use the C macro instead - HV* gv_stashsv(SV* sv, I32 create) + char* sv_pv(SV *sv) =for hackers -Found in file gv.c +Found in file mathoms.c +=item sv_pvbyte +X -=back +Use C instead. -=head1 Handy Values + char* sv_pvbyte(SV *sv) -=over 8 +=for hackers +Found in file mathoms.c -=item Nullav +=item sv_pvbyten +X -Null AV pointer. +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 av.h +Found in file mathoms.c -=item Nullch +=item sv_pvn +X -Null character pointer. +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 handy.h +Found in file mathoms.c -=item Nullcv +=item sv_pvutf8 +X -Null CV pointer. +Use the C macro instead + + char* sv_pvutf8(SV *sv) =for hackers -Found in file cv.h +Found in file mathoms.c -=item Nullhv +=item sv_pvutf8n +X -Null HV pointer. +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 hv.h +Found in file mathoms.c -=item Nullsv +=item sv_taint +X -Null SV pointer. +Taint an SV. Use C instead. + void sv_taint(SV* sv) =for hackers -Found in file handy.h +Found in file mathoms.c +=item sv_unref +X -=back +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(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 + + +=back + +=head1 Global Variables + +=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. +In a pinch, it can also be used as a symbol table for extensions +to share data among each other. It is a good idea to use keys +prefixed by the package name of the extension that owns the data. + + HV* PL_modglobal + +=for hackers +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 +to either declare a local variable and use that instead or to use the +C macro. + + STRLEN PL_na + +=for hackers +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>. + + SV PL_sv_no + +=for hackers +Found in file intrpvar.h + +=item PL_sv_undef +X + +This is the C SV. Always refer to this as C<&PL_sv_undef>. + + SV PL_sv_undef + +=for hackers +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>. + + SV PL_sv_yes + +=for hackers +Found in file intrpvar.h + + +=back + +=head1 GV Functions + +=over 8 + +=item GvSV +X + +Return the SV from the GV. + + SV* GvSV(GV* 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 +accessible via @ISA and UNIVERSAL::. + +The argument C should be either 0 or -1. If C, as a +side-effect creates a glob with the given C in the given C +which in the case of success contains an alias for the subroutine, and sets +up caching info for this glob. Similarly for all the searched stashes. + +This function grants C<"SUPER"> token as a postfix of the stash name. The +GV returned from C may be a method cache entry, which is not +visible to Perl code. So when calling C, you should not use +the GV directly; instead, you should use the method's CV, which can be +obtained from the GV with the C macro. + + GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) + +=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 +glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is +already setup. + +The third parameter of C determines whether +AUTOLOAD lookup is performed if the given method is not present: non-zero +means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. +Calling C is equivalent to calling C +with a non-zero C parameter. + +These functions grant C<"SUPER"> token as a prefix of the method name. Note +that if you want to keep the returned glob for a long time, you need to +check for it being "AUTOLOAD", since at the later time the call may load a +different subroutine due to $AUTOLOAD changing its value. Use the glob +created via a side effect to do this. + +These functions have the same side-effects and as C with +C. C should be writable if contains C<':'> or C<' +''>. The warning against passing the GV returned by C to +C apply equally to these functions. + + GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) + +=for hackers +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. + +For an autoloaded subroutine without a GV, will create a GV even +if C. For an autoloaded subroutine without a stub, GvCV() +of the result may be zero. + + GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) + +=for hackers +Found in file gv.c + +=item gv_stashpv +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 +then the package will be created if it does not already exist. If C +is not set and the package does not exist then NULL is returned. + + HV* gv_stashpv(const char* name, I32 create) + +=for hackers +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 +the C, in bytes. If C is set then the package will be +created if it does not already exist. If C is not set and the +package does not exist then NULL is returned. + + HV* gv_stashpvn(const char* name, U32 namelen, I32 create) + +=for hackers +Found in file gv.c + +=item gv_stashpvs +X + +Like C, but takes a literal string instead of a string/length pair. + + HV* gv_stashpvs(const char* name, I32 create) + +=for hackers +Found in file handy.h + +=item gv_stashsv +X + +Returns a pointer to the stash for a specified package, which must be a +valid UTF-8 string. See C. + + HV* gv_stashsv(SV* sv, I32 create) + +=for hackers +Found in file gv.c + + +=back + +=head1 Handy Values + +=over 8 + +=item Nullav +X + +Null AV pointer. + +=for hackers +Found in file av.h + +=item Nullch +X + +Null character pointer. + +=for hackers +Found in file handy.h + +=item Nullcv +X + +Null CV pointer. + +=for hackers +Found in file cv.h + +=item Nullhv +X + +Null HV pointer. + +=for hackers +Found in file hv.h + +=item Nullsv +X + +Null SV pointer. + +=for hackers +Found in file handy.h + + +=back =head1 Hash Manipulation Functions =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 +1455,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 +1465,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 +1475,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 +1488,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 +1501,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 +1519,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 +1530,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 +1541,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 +1553,7 @@ C. Found in file hv.h =item HeVAL +X Returns the value slot (type C) stored in the hash entry. @@ -1077,8 +1563,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 +1574,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 +1584,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 +1594,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 +1610,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 +1623,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 +1636,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 +1647,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 +1659,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 @@ -1178,7 +1674,18 @@ information on how to use this function on tied hashes. =for hackers Found in file hv.c +=item hv_fetchs +X + +Like C, but takes a literal string instead of a string/length pair. + + SV** hv_fetchs(HV* tb, const char* key, I32 lval) + +=for hackers +Found in file handy.h + =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 +1704,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 +1721,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 +1732,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 +1744,7 @@ see C. Found in file hv.c =item hv_iternext +X Returns entries from a hash iterator. See C. @@ -1251,6 +1762,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 +1773,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 +1793,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 +1804,7 @@ C. Found in file hv.c =item hv_magic +X Adds magic to a hash. See C. @@ -1299,6 +1814,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 +1824,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 @@ -1334,7 +1851,19 @@ information on how to use this function on tied hashes. =for hackers Found in file hv.c +=item hv_stores +X + +Like C, but takes a literal string instead of a string/length pair +and omits the hash parameter. + + SV** hv_stores(HV* tb, const char* key, NULLOK SV* val) + +=for hackers +Found in file handy.h + =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 +1894,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 +1904,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 +1921,7 @@ Found in file hv.c =over 8 =item mg_clear +X Clear something magical that the SV represents. See C. @@ -1399,6 +1931,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 +1941,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 +1951,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 +1961,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 +1971,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 +1981,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 +1991,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 +2001,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 +2012,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 +2023,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 +2034,7 @@ argument more than once. Found in file sv.h =item SvSetMagicSV +X Like C, but does any set magic required afterwards. @@ -1501,6 +2044,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 +2054,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 +2065,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 +2076,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 +2087,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 +2105,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 +2117,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 +2128,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 +2140,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 +2150,87 @@ 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 PoisonFree +X + +PoisonWith(0xEF) for catching access to freed memory. + + void PoisonFree(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 +2240,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 +2251,7 @@ cast. Found in file handy.h =item Safefree +X The XSUB-writer's interface to the C C function. @@ -1666,6 +2261,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,18 +2274,30 @@ 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) =for hackers Found in file util.c +=item savepvs +X + +Like C, but takes a literal string instead of a string/length pair. + + char* savepvs(const char* s) + +=for hackers +Found in file handy.h + =item savesharedpv +X A version of C which allocates the duplicate string in memory which is shared between threads. @@ -1700,6 +2308,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 +2319,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 +2329,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 +2340,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 +2358,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 +2369,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 +2382,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 +2403,7 @@ are done). Found in file util.c =item getcwd_sv +X Fill the sv with current working directory @@ -1796,7 +2412,49 @@ Fill the sv with current working directory =for hackers Found in file util.c +=item my_snprintf +X + +The C library C functionality, if available and +standards-compliant (uses C, actually). However, if the +C is not available, will unfortunately use the unsafe +C which can overrun the buffer (there is an overrun check, +but that may be too late). Consider using C instead, or +getting C. + + int my_snprintf(char *buffer, const Size_t len, const char *format, ...) + +=for hackers +Found in file util.c + +=item my_sprintf +X + +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. + + int my_sprintf(char *buffer, const char *pat, ...) + +=for hackers +Found in file util.c + +=item my_vsnprintf +X + +The C library C if available and standards-compliant. +However, if if the C is not available, will unfortunately +use the unsafe C which can overrun the buffer (there is an +overrun check, but that may be too late). Consider using +C instead, or getting C. + + int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap) + +=for hackers +Found in file util.c + =item new_version +X Returns a new version object based on the passed in SV: @@ -1811,6 +2469,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 @@ -1834,6 +2493,7 @@ it doesn't. Found in file util.c =item strEQ +X Test two strings to see if they are equal. Returns true or false. @@ -1843,6 +2503,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 +2514,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 +2525,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 +2536,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 +2547,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 +2558,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 +2570,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 +2581,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. - - 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. +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_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 +2609,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 +2620,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 +2636,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 +2652,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 +2664,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 +2736,7 @@ Found in file util.c =over 8 =item grok_bin +X converts a string representing a binary number to numeric form. @@ -2048,6 +2765,7 @@ number may use '_' characters to separate digits. Found in file numeric.c =item grok_hex +X converts a string representing a hex number to numeric form. @@ -2076,6 +2794,7 @@ number may use '_' characters to separate digits. 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 +2820,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 +2830,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. @@ -2136,6 +2857,7 @@ number may use '_' characters to separate digits. Found in file numeric.c =item scan_bin +X For backwards compatibility. Use C instead. @@ -2145,6 +2867,7 @@ For backwards compatibility. Use C instead. Found in file numeric.c =item scan_hex +X For backwards compatibility. Use C instead. @@ -2154,6 +2877,7 @@ For backwards compatibility. Use C instead. Found in file numeric.c =item scan_oct +X For backwards compatibility. Use C instead. @@ -2170,6 +2894,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 +2908,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 +2919,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 +2935,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 +2953,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 +2964,7 @@ See L. Found in file XSUB.h =item XCPT_CATCH +X Introduces a catch block. See L. @@ -2241,6 +2972,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 +2982,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 +2990,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 +3005,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 +3016,7 @@ C. Found in file pp.h =item dORIGMARK +X Saves the original stack mark for the XSUB. See C. @@ -2290,6 +3026,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 +3037,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 +3049,7 @@ onto the stack. Found in file pp.h =item MARK +X Stack marker variable for the XSUB. See C. @@ -2318,6 +3057,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 +3069,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 +3081,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 +3093,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 +3105,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 +3117,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 +3129,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 +3141,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 +3153,7 @@ and C. Found in file pp.h =item ORIGMARK +X The original stack mark for the XSUB. See C. @@ -2413,6 +3161,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 +3171,7 @@ Pops an integer off the stack. Found in file pp.h =item POPl +X Pops a long off the stack. @@ -2431,6 +3181,7 @@ Pops a long off the stack. Found in file pp.h =item POPn +X Pops a double off the stack. @@ -2440,6 +3191,7 @@ Pops a double off the stack. Found in file pp.h =item POPp +X Pops a string off the stack. Deprecated. New code should use POPpx. @@ -2449,6 +3201,7 @@ Pops a string off the stack. Deprecated. New code should 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. @@ -2458,6 +3211,7 @@ Pops a string off the stack which must consist of bytes i.e. characters < 256. Found in file pp.h =item POPpx +X Pops a string off the stack. @@ -2467,6 +3221,7 @@ Pops a string off the stack. Found in file pp.h =item POPs +X Pops an SV off the stack. @@ -2476,6 +3231,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 @@ -2489,6 +3245,7 @@ C. Found in file pp.h =item PUSHMARK +X Opening bracket for arguments on a callback. See C and L. @@ -2499,6 +3256,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 @@ -2510,6 +3268,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 @@ -2523,6 +3282,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 @@ -2536,6 +3296,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, @@ -2547,6 +3308,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 @@ -2560,6 +3322,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. @@ -2570,6 +3333,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. @@ -2578,6 +3342,7 @@ C. Found in file pp.h =item SPAGAIN +X Refetch the stack pointer. Used after a callback. See L. @@ -2587,6 +3352,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 @@ -2599,6 +3365,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, @@ -2610,6 +3377,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 @@ -2622,6 +3390,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 @@ -2635,6 +3404,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, @@ -2646,6 +3416,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 @@ -2659,6 +3430,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. @@ -2669,6 +3441,7 @@ handled by C. Found in file XSUB.h =item XSRETURN_EMPTY +X Return an empty list from an XSUB immediately. @@ -2678,6 +3451,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. @@ -2687,6 +3461,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. @@ -2696,6 +3471,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. @@ -2705,6 +3481,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. @@ -2714,6 +3491,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. @@ -2723,6 +3501,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. @@ -2732,6 +3511,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. @@ -2741,6 +3521,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. @@ -2751,6 +3532,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. @@ -2761,6 +3543,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. @@ -2771,6 +3554,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. @@ -2781,6 +3565,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. @@ -2791,6 +3576,7 @@ stack. Found in file XSUB.h =item XST_mYES +X Place C<&PL_sv_yes> into the specified position C on the stack. @@ -2808,6 +3594,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. @@ -2816,6 +3603,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. @@ -2823,6 +3611,7 @@ Integer type flag for scalars. See C. Found in file sv.h =item SVt_NV +X Double type flag for scalars. See C. @@ -2830,6 +3619,7 @@ Double type flag for scalars. See C. Found in file sv.h =item SVt_PV +X Pointer type flag for scalars. See C. @@ -2837,6 +3627,7 @@ Pointer type flag for scalars. See C. Found in file sv.h =item SVt_PVAV +X Type flag for arrays. See C. @@ -2844,6 +3635,7 @@ Type flag for arrays. See C. Found in file sv.h =item SVt_PVCV +X Type flag for code refs. See C. @@ -2851,6 +3643,7 @@ Type flag for code refs. See C. Found in file sv.h =item SVt_PVHV +X Type flag for hashes. See C. @@ -2858,6 +3651,7 @@ Type flag for hashes. See C. Found in file sv.h =item SVt_PVMG +X Type flag for blessed scalars. See C. @@ -2872,6 +3666,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 @@ -2884,18 +3679,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. @@ -2905,152 +3690,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 newSVhek - -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 - -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_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 - -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. @@ -3060,6 +3701,7 @@ Returns the length of the string which is in the SV. See C. Found in file sv.h =item SvCUR_set +X Set the current length of the string which is in the SV. See C and C. @@ -3069,17 +3711,33 @@ and C. =for hackers Found in file sv.h -=item SvEND +=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)). + + char* SvEND(SV* sv) + +=for hackers +Found in file sv.h + +=item SvGAMAGIC +X -Returns a pointer to the last character in the string which is in the SV. -See C. Access the character as *(SvEND(sv)). +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* SvEND(SV* sv) + 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 @@ -3092,6 +3750,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. @@ -3101,6 +3760,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. @@ -3111,6 +3771,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. @@ -3120,6 +3781,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. @@ -3129,6 +3791,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. @@ -3138,6 +3801,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. @@ -3147,6 +3811,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. @@ -3156,6 +3821,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. @@ -3165,6 +3831,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 @@ -3176,6 +3843,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. @@ -3186,6 +3854,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. @@ -3196,6 +3865,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. @@ -3206,6 +3876,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. @@ -3216,6 +3887,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. @@ -3225,6 +3897,7 @@ Like C but doesn't process magic. 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. @@ -3237,6 +3910,7 @@ C instead of the lvalue assignment to C. 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. @@ -3247,6 +3921,7 @@ attributable to C. See C. Found in file sv.h =item SvLEN_set +X Set the actual length of the string which is in the SV. See C. @@ -3256,6 +3931,7 @@ Set the actual length of the string which is in the SV. See C. Found in file sv.h =item SvMAGIC_set +X Set the value of the MAGIC pointer in sv to val. See C. @@ -3265,6 +3941,7 @@ Set the value of the MAGIC pointer in sv to val. See C. Found in file sv.h =item SvNIOK +X Returns a boolean indicating whether the SV contains a number, integer or double. @@ -3275,6 +3952,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. @@ -3285,6 +3963,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. @@ -3294,6 +3973,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. @@ -3303,6 +3983,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. @@ -3313,6 +3994,7 @@ B setting. Use C. Found in file sv.h =item SvNOK_off +X Unsets the NV status of an SV. @@ -3322,6 +4004,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. @@ -3331,6 +4014,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. @@ -3340,6 +4024,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. @@ -3350,6 +4035,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. @@ -3360,6 +4046,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. @@ -3370,6 +4057,7 @@ sv only once. Use the more efficient C otherwise. Found in file sv.h =item SvNV_set +X Set the value of the NV pointer in sv to val. See C. @@ -3379,6 +4067,7 @@ Set the value of the NV pointer in sv to val. See C. 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. @@ -3389,6 +4078,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 @@ -3401,6 +4091,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. @@ -3411,6 +4102,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. @@ -3421,6 +4113,7 @@ Checks the B setting. Use C. Found in file sv.h =item SvPOK_off +X Unsets the PV status of an SV. @@ -3430,6 +4123,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. @@ -3439,6 +4133,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. @@ -3449,6 +4144,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. @@ -3459,6 +4155,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 @@ -3471,6 +4168,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. @@ -3480,6 +4178,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 @@ -3491,6 +4190,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 @@ -3502,6 +4202,7 @@ otherwise. Found in file sv.h =item SvPVbyte_force +X Like C, but converts sv to byte representation first if necessary. @@ -3511,6 +4212,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. @@ -3520,6 +4222,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. @@ -3529,6 +4232,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 @@ -3540,6 +4244,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 @@ -3551,6 +4256,7 @@ otherwise. Found in file sv.h =item SvPVutf8_force +X Like C, but converts sv to utf8 first if necessary. @@ -3560,6 +4266,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. @@ -3569,6 +4276,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. @@ -3579,6 +4287,7 @@ string. Found in file sv.h =item SvPVx +X A version of C which guarantees to evaluate sv only once. @@ -3588,6 +4297,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 @@ -3599,6 +4309,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 @@ -3610,6 +4321,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 @@ -3621,6 +4333,7 @@ stringified form becoming C. Handles 'get' magic. Found in file sv.h =item SvPV_nomg +X Like C but doesn't process magic. @@ -3630,6 +4343,7 @@ Like C but doesn't process magic. Found in file sv.h =item SvPV_set +X Set the value of the PV pointer in sv to val. See C. @@ -3639,6 +4353,7 @@ Set the value of the PV pointer in sv to val. See C. Found in file sv.h =item SvREFCNT +X Returns the value of the object's reference count. @@ -3648,6 +4363,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. @@ -3657,15 +4373,104 @@ 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. +All of the following SvREFCNT_inc* macros are optimized versions of +SvREFCNT_inc, and can be replaced with SvREFCNT_inc. + SV* SvREFCNT_inc(SV* 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. + + void SvREFCNT_inc_simple_void(SV* sv) + +=for hackers +Found in file sv.h + +=item SvREFCNT_inc_simple_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. + + void SvREFCNT_inc_simple_void_NN(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. + + void 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. + + void SvREFCNT_inc_void_NN(SV* sv) + +=for hackers +Found in file sv.h + =item SvROK +X Tests if the SV is an RV. @@ -3675,6 +4480,7 @@ Tests if the SV is an RV. Found in file sv.h =item SvROK_off +X Unsets the RV status of an SV. @@ -3684,6 +4490,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. @@ -3693,6 +4500,7 @@ Tells an SV that it is an RV. Found in file sv.h =item SvRV +X Dereferences an RV to return the SV. @@ -3702,6 +4510,7 @@ Dereferences an RV to return the SV. Found in file sv.h =item SvRV_set +X Set the value of the RV pointer in sv to val. See C. @@ -3711,6 +4520,7 @@ Set the value of the RV pointer in sv to val. See C. Found in file sv.h =item SvSTASH +X Returns the stash of the SV. @@ -3720,15 +4530,17 @@ Returns the stash of the SV. 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) + void SvSTASH_set(SV* sv, HV* val) =for hackers Found in file sv.h =item SvTAINT +X Taints an SV if tainting is enabled. @@ -3738,6 +4550,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. @@ -3748,6 +4561,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 @@ -3762,6 +4576,7 @@ untainting variables. Found in file sv.h =item SvTAINTED_on +X Marks an SV as tainted if tainting is enabled. @@ -3771,6 +4586,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. @@ -3781,6 +4597,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. @@ -3790,6 +4607,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. @@ -3799,6 +4617,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. @@ -3809,6 +4628,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. @@ -3818,6 +4638,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. @@ -3827,6 +4648,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. @@ -3837,6 +4659,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. @@ -3847,6 +4670,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. @@ -3857,6 +4681,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. @@ -3867,33 +4692,291 @@ 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. UV SvUV_nomg(SV* sv) =for hackers -Found in file sv.h +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) + +=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 +I. To check derivation at the Perl level, call C as a +normal Perl method. + + bool sv_derived_from(SV* sv, const char* name) + +=for hackers +Found in file universal.c + +=item sv_does +X + +Returns a boolean indicating whether the SV performs a specific, named role. +The SV can be a Perl object or the name of a Perl class. + + bool sv_does(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 newSVpvs +X + +Like C, but takes a literal string instead of a string/length pair. + + SV* newSVpvs(const char* s) + +=for hackers +Found in file handy.h + +=item newSVpvs_share +X + +Like C, but takes a literal string instead of a string/length +pair and omits the hash parameter. + + SV* newSVpvs_share(const char* s) + +=for hackers +Found in file handy.h + +=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 SvUV_set +=item newSVsv +X -Set the value of the UV pointer in sv to val. See C. +Creates a new SV which is an exact duplicate of the original SV. +(Uses C). - void SvUV_set(SV* sv, UV val) + SV* newSVsv(SV* old) =for hackers -Found in file sv.h +Found in file sv.c -=item SvVOK +=item newSVuv +X -Returns a boolean indicating whether the SV contains a v-string. +Creates a new SV and copies an unsigned integer into it. +The reference count for the SV is set to 1. - bool SvVOK(SV* sv) + 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. @@ -3904,9 +4987,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) @@ -3914,6 +4999,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 @@ -3925,6 +5011,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. @@ -3936,6 +5023,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 @@ -3949,6 +5037,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 @@ -3960,6 +5049,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 @@ -3972,19 +5062,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. @@ -3996,19 +5075,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 @@ -4021,16 +5089,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. @@ -4042,6 +5102,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. @@ -4052,6 +5113,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 @@ -4063,6 +5125,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 @@ -4074,6 +5137,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 @@ -4089,6 +5153,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. @@ -4098,6 +5163,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 @@ -4110,6 +5176,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 @@ -4123,25 +5190,18 @@ 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 +=item sv_catpvs +X -Like C but doesn't process magic. +Like C, but takes a literal string instead of a string/length pair. - void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) + void sv_catpvs(SV* sv, const char* s) =for hackers -Found in file sv.h +Found in file handy.h =item sv_catpv_mg +X Like C, but also handles 'set' magic. @@ -4151,6 +5211,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 @@ -4162,6 +5223,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 @@ -4173,25 +5235,8 @@ 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 @@ -4206,6 +5251,7 @@ refer to the same chunk of data. 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 @@ -4221,6 +5267,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 @@ -4233,6 +5280,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 @@ -4244,6 +5292,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. @@ -4258,6 +5307,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 @@ -4273,6 +5323,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. @@ -4282,18 +5333,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 @@ -4304,18 +5345,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 @@ -4333,6 +5364,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 @@ -4345,6 +5377,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. @@ -4355,6 +5388,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. @@ -4366,6 +5400,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. @@ -4376,6 +5411,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. @@ -4386,6 +5422,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 @@ -4397,6 +5434,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 @@ -4407,17 +5445,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. @@ -4428,6 +5457,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. @@ -4438,6 +5468,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. @@ -4454,6 +5485,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. @@ -4469,12 +5501,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 @@ -4487,6 +5520,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 @@ -4499,6 +5533,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. @@ -4508,17 +5543,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. @@ -4530,6 +5556,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 @@ -4542,57 +5569,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 @@ -4604,6 +5592,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 @@ -4617,31 +5606,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) @@ -4649,15 +5617,17 @@ instead. Found in file sv.c =item sv_reftype +X Returns a string describing what the SV is a reference to. - char* sv_reftype(const SV* sv, int ob) + const 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 @@ -4671,16 +5641,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. @@ -4691,11 +5653,13 @@ 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 push a back-reference to this RV onto the array of backreferences -associated with that magic. +associated with that magic. If the RV is magical, set magic will be +called after the RV is cleared. SV* sv_rvweaken(SV *sv) @@ -4703,6 +5667,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. @@ -4713,6 +5678,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. @@ -4722,6 +5688,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. @@ -4732,6 +5699,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. @@ -4741,6 +5709,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. @@ -4751,6 +5720,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. @@ -4761,6 +5731,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. @@ -4770,6 +5741,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. @@ -4780,6 +5752,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. @@ -4789,6 +5762,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 @@ -4800,6 +5774,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. @@ -4808,7 +5783,18 @@ Like C, but also handles 'set' magic. =for hackers Found in file sv.c +=item sv_setpvs +X + +Like C, but takes a literal string instead of a string/length pair. + + void sv_setpvs(SV* sv, const char* s) + +=for hackers +Found in file handy.h + =item sv_setpv_mg +X Like C, but also handles 'set' magic. @@ -4818,11 +5804,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) @@ -4831,11 +5818,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) @@ -4844,12 +5832,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 @@ -4863,12 +5852,13 @@ 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. @@ -4879,11 +5869,12 @@ Note that C copies the pointer while this copies the string. 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) @@ -4892,6 +5883,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 @@ -4909,6 +5901,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 @@ -4933,6 +5926,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. @@ -4941,16 +5935,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. @@ -4961,6 +5947,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. @@ -4969,15 +5956,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) @@ -4986,6 +5966,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 @@ -4997,6 +5978,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. @@ -5005,19 +5987,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 @@ -5033,6 +6004,7 @@ See C. Found in file sv.c =item sv_untaint +X Untaint an SV. Use C instead. void sv_untaint(SV* sv) @@ -5041,41 +6013,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. - void sv_upgrade(SV* sv, U32 mt) + void sv_upgrade(SV* sv, svtype new_type) =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) +=item sv_usepvn_flags +X -=for hackers -Found in file sv.c - -=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 @@ -5092,6 +6064,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; @@ -5110,6 +6083,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. @@ -5120,6 +6094,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. @@ -5135,6 +6110,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. @@ -5151,17 +6127,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. @@ -5174,6 +6141,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 @@ -5189,6 +6157,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. @@ -5200,6 +6169,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. @@ -5212,6 +6182,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. @@ -5224,6 +6195,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. @@ -5242,6 +6214,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 @@ -5259,6 +6232,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 @@ -5276,6 +6250,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 @@ -5304,6 +6279,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 @@ -5316,6 +6292,7 @@ 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 @@ -5330,8 +6307,9 @@ See also is_utf8_string_loclen() and is_utf8_string_loc(). Found in file utf8.c =item is_utf8_string_loc +X -Like is_ut8_string() but stores the location of the failure (in the +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. @@ -5343,8 +6321,9 @@ See also is_utf8_string_loclen() and is_utf8_string(). Found in file utf8.c =item is_utf8_string_loclen +X -Like is_ut8_string() but stores the location of the failure (in the +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. @@ -5357,6 +6336,7 @@ See also is_utf8_string_loc() and is_utf8_string(). 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 @@ -5377,6 +6357,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 @@ -5394,6 +6375,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 @@ -5412,6 +6394,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 @@ -5427,6 +6410,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. @@ -5438,7 +6422,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 @@ -5448,12 +6432,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 @@ -5470,6 +6455,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 @@ -5485,6 +6471,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 @@ -5500,6 +6487,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 @@ -5515,19 +6503,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 @@ -5547,12 +6540,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. @@ -5566,6 +6560,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. @@ -5580,6 +6575,7 @@ on the first byte of character or just after the last byte of a character. 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 @@ -5591,12 +6587,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. @@ -5606,6 +6605,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 @@ -5614,12 +6614,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 @@ -5631,12 +6632,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 @@ -5655,6 +6657,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 @@ -5688,6 +6691,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 @@ -5699,6 +6703,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. @@ -5709,6 +6714,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. @@ -5719,6 +6725,7 @@ This is usually handled automatically by C by calling C. 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. @@ -5729,6 +6736,7 @@ This is usually handled automatically by C by calling C. Found in file XSUB.h =item dITEMS +X Sets up the C variable. This is usually handled automatically by C by calling C. @@ -5739,6 +6747,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. @@ -5749,6 +6758,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. @@ -5760,6 +6770,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. @@ -5770,6 +6781,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. @@ -5780,6 +6792,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. @@ -5790,6 +6803,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. @@ -5798,6 +6812,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 @@ -5809,6 +6824,7 @@ L. Found in file XSUB.h =item ST +X Used to access elements on the XSUB's stack. @@ -5818,6 +6834,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 @@ -5829,6 +6846,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. @@ -5837,6 +6855,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. @@ -5845,6 +6864,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. @@ -5853,6 +6873,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 @@ -5871,6 +6892,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 @@ -5878,11 +6900,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, ...) @@ -5890,6 +6912,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. @@ -5920,3 +6943,6 @@ Updated to be autogenerated from comments in the source by Benjamin Stuhl. perlguts(1), perlxs(1), perlxstut(1), perlintern(1) +=cut + + ex: set ro: