diff options
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlapi.pod')
-rw-r--r-- | Master/tlpkg/tlperl/lib/pods/perlapi.pod | 12932 |
1 files changed, 0 insertions, 12932 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlapi.pod b/Master/tlpkg/tlperl/lib/pods/perlapi.pod deleted file mode 100644 index 57ddb06f97f..00000000000 --- a/Master/tlpkg/tlperl/lib/pods/perlapi.pod +++ /dev/null @@ -1,12932 +0,0 @@ --*- 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<Perl API> X<API> X<api> - -This file contains the documentation of the perl public API generated by -F<embed.pl>, specifically a listing of functions, macros, flags, and variables -that may be used by extension writers. L<At the end|/Undocumented functions> -is a list of functions which have yet to be documented. The interfaces of -those are subject to change without notice. Any functions not listed here are -not part of the public API, and should not be used by extension writers at -all. For these reasons, blindly using functions listed in proto.h is to be -avoided when writing extensions. - -Note that all Perl API global variables must be referenced with the C<PL_> -prefix. Some macros are provided for compatibility with the older, -unadorned names, but this support may be disabled in a future release. - -Perl was originally written to handle US-ASCII only (that is characters -whose ordinal numbers are in the range 0 - 127). -And documentation and comments may still use the term ASCII, when -sometimes in fact the entire range from 0 - 255 is meant. - -Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>) -or ASCII. Most of the documentation (and even comments in the code) -ignore the EBCDIC possibility. -For almost all purposes the differences are transparent. -As an example, under EBCDIC, -instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so -whenever this documentation refers to C<utf8> -(and variants of that name, including in function names), -it also (essentially transparently) means C<UTF-EBCDIC>. -But the ordinals of characters differ between ASCII, EBCDIC, and -the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes -than in UTF-8. - -Also, on some EBCDIC machines, functions that are documented as operating on -US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all -256 characters in the EBCDIC range, not just the subset corresponding to -US-ASCII. - -The listing below is alphabetical, case insensitive. - - -=head1 "Gimme" Values - -=over 8 - -=item GIMME -X<GIMME> - -A backward-compatible version of C<GIMME_V> which can only return -C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>. -Deprecated. Use C<GIMME_V> instead. - - U32 GIMME - -=for hackers -Found in file op.h - -=item GIMME_V -X<GIMME_V> - -The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>, -C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context, -respectively. See L<perlcall> for a usage example. - - U32 GIMME_V - -=for hackers -Found in file op.h - -=item G_ARRAY -X<G_ARRAY> - -Used to indicate list context. See C<GIMME_V>, C<GIMME> and -L<perlcall>. - -=for hackers -Found in file cop.h - -=item G_DISCARD -X<G_DISCARD> - -Indicates that arguments returned from a callback should be discarded. See -L<perlcall>. - -=for hackers -Found in file cop.h - -=item G_EVAL -X<G_EVAL> - -Used to force a Perl C<eval> wrapper around a callback. See -L<perlcall>. - -=for hackers -Found in file cop.h - -=item G_NOARGS -X<G_NOARGS> - -Indicates that no arguments are being sent to a callback. See -L<perlcall>. - -=for hackers -Found in file cop.h - -=item G_SCALAR -X<G_SCALAR> - -Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and -L<perlcall>. - -=for hackers -Found in file cop.h - -=item G_VOID -X<G_VOID> - -Used to indicate void context. See C<GIMME_V> and L<perlcall>. - -=for hackers -Found in file cop.h - - -=back - -=head1 Array Manipulation Functions - -=over 8 - -=item AvFILL -X<AvFILL> - -Same as C<av_len()>. Deprecated, use C<av_len()> instead. - - int AvFILL(AV* av) - -=for hackers -Found in file av.h - -=item av_clear -X<av_clear> - -Clears an array, making it empty. Does not free the memory the av uses to -store its list of scalars. If any destructors are triggered as a result, -the av itself may be freed when this function returns. - -Perl equivalent: C<@myarray = ();>. - - void av_clear(AV *av) - -=for hackers -Found in file av.c - -=item av_create_and_push -X<av_create_and_push> - -Push an SV onto the end of the array, creating the array if necessary. -A small internal helper function to remove a commonly duplicated idiom. - -NOTE: this function is experimental and may change or be -removed without notice. - - void av_create_and_push(AV **const avp, - SV *const val) - -=for hackers -Found in file av.c - -=item av_create_and_unshift_one -X<av_create_and_unshift_one> - -Unshifts an SV onto the beginning of the array, creating the array if -necessary. -A small internal helper function to remove a commonly duplicated idiom. - -NOTE: this function is experimental and may change or be -removed without notice. - - SV** av_create_and_unshift_one(AV **const avp, - SV *const val) - -=for hackers -Found in file av.c - -=item av_delete -X<av_delete> - -Deletes the element indexed by C<key> from the array, makes the element mortal, -and returns it. If C<flags> equals C<G_DISCARD>, the element is freed and null -is returned. Perl equivalent: C<my $elem = delete($myarray[$idx]);> for the -non-C<G_DISCARD> version and a void-context C<delete($myarray[$idx]);> for the -C<G_DISCARD> version. - - SV* av_delete(AV *av, I32 key, I32 flags) - -=for hackers -Found in file av.c - -=item av_exists -X<av_exists> - -Returns true if the element indexed by C<key> has been initialized. - -This relies on the fact that uninitialized array elements are set to -C<&PL_sv_undef>. - -Perl equivalent: C<exists($myarray[$key])>. - - bool av_exists(AV *av, I32 key) - -=for hackers -Found in file av.c - -=item av_extend -X<av_extend> - -Pre-extend an array. The C<key> is the index to which the array should be -extended. - - void av_extend(AV *av, I32 key) - -=for hackers -Found in file av.c - -=item av_fetch -X<av_fetch> - -Returns the SV at the specified index in the array. The C<key> is the -index. If lval is true, you are guaranteed to get a real SV back (in case -it wasn't real before), which you can then modify. Check that the return -value is non-null before dereferencing it to a C<SV*>. - -See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for -more information on how to use this function on tied arrays. - -The rough perl equivalent is C<$myarray[$idx]>. - - SV** av_fetch(AV *av, I32 key, I32 lval) - -=for hackers -Found in file av.c - -=item av_fill -X<av_fill> - -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<fill + 1> after -av_fill() returns. If the array was previously shorter, then the -additional elements appended are set to C<PL_sv_undef>. If the array -was longer, then the excess elements are freed. C<av_fill(av, -1)> is -the same as C<av_clear(av)>. - - void av_fill(AV *av, I32 fill) - -=for hackers -Found in file av.c - -=item av_len -X<av_len> - -Returns the highest index in the array. The number of elements in the -array is C<av_len(av) + 1>. Returns -1 if the array is empty. - -The Perl equivalent for this is C<$#myarray>. - - I32 av_len(AV *av) - -=for hackers -Found in file av.c - -=item av_make -X<av_make> - -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 -will have a reference count of 1. - -Perl equivalent: C<my @new_array = ($scalar1, $scalar2, $scalar3...);> - - AV* av_make(I32 size, SV **strp) - -=for hackers -Found in file av.c - -=item av_pop -X<av_pop> - -Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array -is empty. - -Perl equivalent: C<pop(@myarray);> - - SV* av_pop(AV *av) - -=for hackers -Found in file av.c - -=item av_push -X<av_push> - -Pushes an SV onto the end of the array. The array will grow automatically -to accommodate the addition. This takes ownership of one reference count. - -Perl equivalent: C<push @myarray, $elem;>. - - void av_push(AV *av, SV *val) - -=for hackers -Found in file av.c - -=item av_shift -X<av_shift> - -Shifts an SV off the beginning of the -array. Returns C<&PL_sv_undef> if the -array is empty. - -Perl equivalent: C<shift(@myarray);> - - SV* av_shift(AV *av) - -=for hackers -Found in file av.c - -=item av_store -X<av_store> - -Stores an SV in an array. The array index is specified as C<key>. The -return value will be NULL if the operation failed or if the value did not -need to be actually stored within the array (as in the case of tied -arrays). Otherwise, it can be dereferenced -to get the C<SV*> that was stored -there (= C<val>)). - -Note that the caller is responsible for suitably incrementing the reference -count of C<val> before the call, and decrementing it if the function -returned NULL. - -Approximate Perl equivalent: C<$myarray[$key] = $val;>. - -See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for -more information on how to use this function on tied arrays. - - SV** av_store(AV *av, I32 key, SV *val) - -=for hackers -Found in file av.c - -=item av_undef -X<av_undef> - -Undefines the array. Frees the memory used by the av to store its list of -scalars. If any destructors are triggered as a result, the av itself may -be freed. - - void av_undef(AV *av) - -=for hackers -Found in file av.c - -=item av_unshift -X<av_unshift> - -Unshift the given number of C<undef> values onto the beginning of the -array. The array will grow automatically to accommodate the addition. You -must then use C<av_store> to assign values to these new elements. - -Perl equivalent: C<unshift @myarray, ( (undef) x $n );> - - void av_unshift(AV *av, I32 num) - -=for hackers -Found in file av.c - -=item get_av -X<get_av> - -Returns the AV of the specified Perl global or package array with the given -name (so it won't work on lexical variables). C<flags> are passed -to C<gv_fetchpv>. If C<GV_ADD> is set and the -Perl variable does not exist then it will be created. If C<flags> is zero -and the variable does not exist then NULL is returned. - -Perl equivalent: C<@{"$name"}>. - -NOTE: the perl_ form of this function is deprecated. - - AV* get_av(const char *name, I32 flags) - -=for hackers -Found in file perl.c - -=item newAV -X<newAV> - -Creates a new AV. The reference count is set to 1. - -Perl equivalent: C<my @array;>. - - AV* newAV() - -=for hackers -Found in file av.h - -=item sortsv -X<sortsv> - -Sort an array. Here is an example: - - sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale); - -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<sortsv_flags> - -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 - - -=back - -=head1 Callback Functions - -=over 8 - -=item call_argv -X<call_argv> - -Performs a callback to the specified named and package-scoped Perl subroutine -with C<argv> (a NULL-terminated array of strings) as arguments. See L<perlcall>. - -Approximate Perl equivalent: C<&{"$sub_name"}(@$argv)>. - -NOTE: the perl_ form of this function is deprecated. - - I32 call_argv(const char* sub_name, I32 flags, - char** argv) - -=for hackers -Found in file perl.c - -=item call_method -X<call_method> - -Performs a callback to the specified Perl method. The blessed object must -be on the stack. See L<perlcall>. - -NOTE: the perl_ form of this function is deprecated. - - I32 call_method(const char* methname, I32 flags) - -=for hackers -Found in file perl.c - -=item call_pv -X<call_pv> - -Performs a callback to the specified Perl sub. See L<perlcall>. - -NOTE: the perl_ form of this function is deprecated. - - I32 call_pv(const char* sub_name, I32 flags) - -=for hackers -Found in file perl.c - -=item call_sv -X<call_sv> - -Performs a callback to the Perl sub whose name is in the SV. See -L<perlcall>. - -NOTE: the perl_ form of this function is deprecated. - - I32 call_sv(SV* sv, VOL I32 flags) - -=for hackers -Found in file perl.c - -=item ENTER -X<ENTER> - -Opening bracket on a callback. See C<LEAVE> and L<perlcall>. - - ENTER; - -=for hackers -Found in file scope.h - -=item eval_pv -X<eval_pv> - -Tells Perl to C<eval> the given string and return an SV* result. - -NOTE: the perl_ form of this function is deprecated. - - SV* eval_pv(const char* p, I32 croak_on_error) - -=for hackers -Found in file perl.c - -=item eval_sv -X<eval_sv> - -Tells Perl to C<eval> the string in the SV. It supports the same flags -as C<call_sv>, with the obvious exception of G_EVAL. See L<perlcall>. - -NOTE: the perl_ form of this function is deprecated. - - I32 eval_sv(SV* sv, I32 flags) - -=for hackers -Found in file perl.c - -=item FREETMPS -X<FREETMPS> - -Closing bracket for temporaries on a callback. See C<SAVETMPS> and -L<perlcall>. - - FREETMPS; - -=for hackers -Found in file scope.h - -=item LEAVE -X<LEAVE> - -Closing bracket on a callback. See C<ENTER> and L<perlcall>. - - LEAVE; - -=for hackers -Found in file scope.h - -=item SAVETMPS -X<SAVETMPS> - -Opening bracket for temporaries on a callback. See C<FREETMPS> and -L<perlcall>. - - SAVETMPS; - -=for hackers -Found in file scope.h - - -=back - -=head1 Character case changing - -=over 8 - -=item toLOWER -X<toLOWER> - -Converts the specified character to lowercase in the platform's native -character set, if possible; otherwise returns the input character itself. - - char toLOWER(char ch) - -=for hackers -Found in file handy.h - -=item toUPPER -X<toUPPER> - -Converts the specified character to uppercase in the platform's native -character set, if possible; otherwise returns the input character itself. - - char toUPPER(char ch) - -=for hackers -Found in file handy.h - - -=back - -=head1 Character classes - -There are three variants for all the functions in this section. The base ones -operate using the character set of the platform Perl is running on. The ones -with an C<_A> suffix operate on the ASCII character set, and the ones with an -C<_L1> suffix operate on the full Latin1 character set. All are unaffected by -locale and by C<use bytes>. - -For ASCII platforms, the base function with no suffix and the one with the -C<_A> suffix are identical. The function with the C<_L1> suffix imposes the -Latin-1 character set onto the platform. That is, the code points that are -ASCII are unaffected, since ASCII is a subset of Latin-1. But the non-ASCII -code points are treated as if they are Latin-1 characters. For example, -C<isSPACE_L1()> will return true when called with the code point 0xA0, which is -the Latin-1 NO-BREAK SPACE. - -For EBCDIC platforms, the base function with no suffix and the one with the -C<_L1> suffix should be identical, since, as of this writing, the EBCDIC code -pages that Perl knows about all are equivalent to Latin-1. The function that -ends in an C<_A> suffix will not return true unless the specified character also -has an ASCII equivalent. - - -=over 8 - -=item isALPHA -X<isALPHA> - -Returns a boolean indicating whether the specified character is an -alphabetic character in the platform's native character set. -See the L<top of this section|/Character classes> for an explanation of variants -C<isALPHA_A> and C<isALPHA_L1>. - - bool isALPHA(char ch) - -=for hackers -Found in file handy.h - -=item isASCII -X<isASCII> - -Returns a boolean indicating whether the specified character is one of the 128 -characters in the ASCII character set. On non-ASCII platforms, it is if this -character corresponds to an ASCII character. Variants C<isASCII_A()> and -C<isASCII_L1()> are identical to C<isASCII()>. - - bool isASCII(char ch) - -=for hackers -Found in file handy.h - -=item isDIGIT -X<isDIGIT> - -Returns a boolean indicating whether the specified character is a -digit in the platform's native character set. -Variants C<isDIGIT_A> and C<isDIGIT_L1> are identical to C<isDIGIT>. - - bool isDIGIT(char ch) - -=for hackers -Found in file handy.h - -=item isLOWER -X<isLOWER> - -Returns a boolean indicating whether the specified character is a -lowercase character in the platform's native character set. -See the L<top of this section|/Character classes> for an explanation of variants -C<isLOWER_A> and C<isLOWER_L1>. - - bool isLOWER(char ch) - -=for hackers -Found in file handy.h - -=item isOCTAL -X<isOCTAL> - -Returns a boolean indicating whether the specified character is an -octal digit, [0-7] in the platform's native character set. -Variants C<isOCTAL_A> and C<isOCTAL_L1> are identical to C<isOCTAL>. - - bool isOCTAL(char ch) - -=for hackers -Found in file handy.h - -=item isSPACE -X<isSPACE> - -Returns a boolean indicating whether the specified character is a -whitespace character in the platform's native character set. This is the same -as what C<\s> matches in a regular expression. -See the L<top of this section|/Character classes> for an explanation of variants -C<isSPACE_A> and C<isSPACE_L1>. - - bool isSPACE(char ch) - -=for hackers -Found in file handy.h - -=item isUPPER -X<isUPPER> - -Returns a boolean indicating whether the specified character is an -uppercase character in the platform's native character set. -See the L<top of this section|/Character classes> for an explanation of variants -C<isUPPER_A> and C<isUPPER_L1>. - - bool isUPPER(char ch) - -=for hackers -Found in file handy.h - -=item isWORDCHAR -X<isWORDCHAR> - -Returns a boolean indicating whether the specified character is a -character that is any of: alphabetic, numeric, or an underscore. This is the -same as what C<\w> matches in a regular expression. -C<isALNUM()> is a synonym provided for backward compatibility. Note that it -does not have the standard C language meaning of alphanumeric, since it matches -an underscore and the standard meaning does not. -See the L<top of this section|/Character classes> for an explanation of variants -C<isWORDCHAR_A> and C<isWORDCHAR_L1>. - - bool isWORDCHAR(char ch) - -=for hackers -Found in file handy.h - -=item isXDIGIT -X<isXDIGIT> - -Returns a boolean indicating whether the specified character is a hexadecimal -digit, [0-9A-Fa-f]. Variants C<isXDIGIT_A()> and C<isXDIGIT_L1()> are -identical to C<isXDIGIT()>. - - bool isXDIGIT(char ch) - -=for hackers -Found in file handy.h - - -=back - -=head1 Cloning an interpreter - -=over 8 - -=item perl_clone -X<perl_clone> - -Create and return a new interpreter by cloning the current one. - -perl_clone takes these flags as parameters: - -CLONEf_COPY_STACKS - is used to, well, copy the stacks also, -without it we only clone the data and zero the stacks, -with it we copy the stacks and the new perl interpreter is -ready to run at the exact same point as the previous one. -The pseudo-fork code uses COPY_STACKS while the -threads->create doesn't. - -CLONEf_KEEP_PTR_TABLE - -perl_clone keeps a ptr_table with the pointer of the old -variable as a key and the new variable as a value, -this allows it to check if something has been cloned and not -clone it again but rather just use the value and increase the -refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill -the ptr_table using the function -C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>, -reason to keep it around is if you want to dup some of your own -variable who are outside the graph perl scans, example of this -code is in threads.xs create. - -CLONEf_CLONE_HOST - -This is a win32 thing, it is ignored on unix, it tells perls -win32host code (which is c++) to clone itself, this is needed on -win32 if you want to run two threads at the same time, -if you just want to do some stuff in a separate perl interpreter -and then throw it away and return to the original one, -you don't need to do anything. - - PerlInterpreter* perl_clone( - PerlInterpreter *proto_perl, - UV flags - ) - -=for hackers -Found in file sv.c - - -=back - -=head1 Compile-time scope hooks - -=over 8 - -=item BhkDISABLE -X<BhkDISABLE> - -Temporarily disable an entry in this BHK structure, by clearing the -appropriate flag. I<which> is a preprocessor token indicating which -entry to disable. - -NOTE: this function is experimental and may change or be -removed without notice. - - void BhkDISABLE(BHK *hk, which) - -=for hackers -Found in file op.h - -=item BhkENABLE -X<BhkENABLE> - -Re-enable an entry in this BHK structure, by setting the appropriate -flag. I<which> is a preprocessor token indicating which entry to enable. -This will assert (under -DDEBUGGING) if the entry doesn't contain a valid -pointer. - -NOTE: this function is experimental and may change or be -removed without notice. - - void BhkENABLE(BHK *hk, which) - -=for hackers -Found in file op.h - -=item BhkENTRY_set -X<BhkENTRY_set> - -Set an entry in the BHK structure, and set the flags to indicate it is -valid. I<which> is a preprocessing token indicating which entry to set. -The type of I<ptr> depends on the entry. - -NOTE: this function is experimental and may change or be -removed without notice. - - void BhkENTRY_set(BHK *hk, which, void *ptr) - -=for hackers -Found in file op.h - -=item blockhook_register -X<blockhook_register> - -Register a set of hooks to be called when the Perl lexical scope changes -at compile time. See L<perlguts/"Compile-time scope hooks">. - -NOTE: this function is experimental and may change or be -removed without notice. - -NOTE: this function must be explicitly called as Perl_blockhook_register with an aTHX_ parameter. - - void Perl_blockhook_register(pTHX_ BHK *hk) - -=for hackers -Found in file op.c - - -=back - -=head1 COP Hint Hashes - -=over 8 - -=item cophh_2hv -X<cophh_2hv> - -Generates and returns a standard Perl hash representing the full set of -key/value pairs in the cop hints hash I<cophh>. I<flags> is currently -unused and must be zero. - -NOTE: this function is experimental and may change or be -removed without notice. - - HV * cophh_2hv(const COPHH *cophh, U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_copy -X<cophh_copy> - -Make and return a complete copy of the cop hints hash I<cophh>. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_copy(COPHH *cophh) - -=for hackers -Found in file cop.h - -=item cophh_delete_pv -X<cophh_delete_pv> - -Like L</cophh_delete_pvn>, but takes a nul-terminated string instead of -a string/length pair. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_delete_pv(const COPHH *cophh, - const char *key, U32 hash, - U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_delete_pvn -X<cophh_delete_pvn> - -Delete a key and its associated value from the cop hints hash I<cophh>, -and returns the modified hash. The returned hash pointer is in general -not the same as the hash pointer that was passed in. The input hash is -consumed by the function, and the pointer to it must not be subsequently -used. Use L</cophh_copy> if you need both hashes. - -The key is specified by I<keypv> and I<keylen>. If I<flags> has the -C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8, -otherwise they are interpreted as Latin-1. I<hash> is a precomputed -hash of the key string, or zero if it has not been precomputed. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_delete_pvn(COPHH *cophh, - const char *keypv, - STRLEN keylen, U32 hash, - U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_delete_pvs -X<cophh_delete_pvs> - -Like L</cophh_delete_pvn>, but takes a literal string instead of a -string/length pair, and no precomputed hash. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_delete_pvs(const COPHH *cophh, - const char *key, U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_delete_sv -X<cophh_delete_sv> - -Like L</cophh_delete_pvn>, but takes a Perl scalar instead of a -string/length pair. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_delete_sv(const COPHH *cophh, SV *key, - U32 hash, U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_fetch_pv -X<cophh_fetch_pv> - -Like L</cophh_fetch_pvn>, but takes a nul-terminated string instead of -a string/length pair. - -NOTE: this function is experimental and may change or be -removed without notice. - - SV * cophh_fetch_pv(const COPHH *cophh, - const char *key, U32 hash, - U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_fetch_pvn -X<cophh_fetch_pvn> - -Look up the entry in the cop hints hash I<cophh> with the key specified by -I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set, -the key octets are interpreted as UTF-8, otherwise they are interpreted -as Latin-1. I<hash> is a precomputed hash of the key string, or zero if -it has not been precomputed. Returns a mortal scalar copy of the value -associated with the key, or C<&PL_sv_placeholder> if there is no value -associated with the key. - -NOTE: this function is experimental and may change or be -removed without notice. - - SV * cophh_fetch_pvn(const COPHH *cophh, - const char *keypv, - STRLEN keylen, U32 hash, - U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_fetch_pvs -X<cophh_fetch_pvs> - -Like L</cophh_fetch_pvn>, but takes a literal string instead of a -string/length pair, and no precomputed hash. - -NOTE: this function is experimental and may change or be -removed without notice. - - SV * cophh_fetch_pvs(const COPHH *cophh, - const char *key, U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_fetch_sv -X<cophh_fetch_sv> - -Like L</cophh_fetch_pvn>, but takes a Perl scalar instead of a -string/length pair. - -NOTE: this function is experimental and may change or be -removed without notice. - - SV * cophh_fetch_sv(const COPHH *cophh, SV *key, - U32 hash, U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_free -X<cophh_free> - -Discard the cop hints hash I<cophh>, freeing all resources associated -with it. - -NOTE: this function is experimental and may change or be -removed without notice. - - void cophh_free(COPHH *cophh) - -=for hackers -Found in file cop.h - -=item cophh_new_empty -X<cophh_new_empty> - -Generate and return a fresh cop hints hash containing no entries. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_new_empty() - -=for hackers -Found in file cop.h - -=item cophh_store_pv -X<cophh_store_pv> - -Like L</cophh_store_pvn>, but takes a nul-terminated string instead of -a string/length pair. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_store_pv(const COPHH *cophh, - const char *key, U32 hash, - SV *value, U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_store_pvn -X<cophh_store_pvn> - -Stores a value, associated with a key, in the cop hints hash I<cophh>, -and returns the modified hash. The returned hash pointer is in general -not the same as the hash pointer that was passed in. The input hash is -consumed by the function, and the pointer to it must not be subsequently -used. Use L</cophh_copy> if you need both hashes. - -The key is specified by I<keypv> and I<keylen>. If I<flags> has the -C<COPHH_KEY_UTF8> bit set, the key octets are interpreted as UTF-8, -otherwise they are interpreted as Latin-1. I<hash> is a precomputed -hash of the key string, or zero if it has not been precomputed. - -I<value> is the scalar value to store for this key. I<value> is copied -by this function, which thus does not take ownership of any reference -to it, and later changes to the scalar will not be reflected in the -value visible in the cop hints hash. Complex types of scalar will not -be stored with referential integrity, but will be coerced to strings. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv, - STRLEN keylen, U32 hash, - SV *value, U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_store_pvs -X<cophh_store_pvs> - -Like L</cophh_store_pvn>, but takes a literal string instead of a -string/length pair, and no precomputed hash. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_store_pvs(const COPHH *cophh, - const char *key, SV *value, - U32 flags) - -=for hackers -Found in file cop.h - -=item cophh_store_sv -X<cophh_store_sv> - -Like L</cophh_store_pvn>, but takes a Perl scalar instead of a -string/length pair. - -NOTE: this function is experimental and may change or be -removed without notice. - - COPHH * cophh_store_sv(const COPHH *cophh, SV *key, - U32 hash, SV *value, U32 flags) - -=for hackers -Found in file cop.h - - -=back - -=head1 COP Hint Reading - -=over 8 - -=item cop_hints_2hv -X<cop_hints_2hv> - -Generates and returns a standard Perl hash representing the full set of -hint entries in the cop I<cop>. I<flags> is currently unused and must -be zero. - - HV * cop_hints_2hv(const COP *cop, U32 flags) - -=for hackers -Found in file cop.h - -=item cop_hints_fetch_pv -X<cop_hints_fetch_pv> - -Like L</cop_hints_fetch_pvn>, but takes a nul-terminated string instead -of a string/length pair. - - SV * cop_hints_fetch_pv(const COP *cop, - const char *key, U32 hash, - U32 flags) - -=for hackers -Found in file cop.h - -=item cop_hints_fetch_pvn -X<cop_hints_fetch_pvn> - -Look up the hint entry in the cop I<cop> with the key specified by -I<keypv> and I<keylen>. If I<flags> has the C<COPHH_KEY_UTF8> bit set, -the key octets are interpreted as UTF-8, otherwise they are interpreted -as Latin-1. I<hash> is a precomputed hash of the key string, or zero if -it has not been precomputed. Returns a mortal scalar copy of the value -associated with the key, or C<&PL_sv_placeholder> if there is no value -associated with the key. - - SV * cop_hints_fetch_pvn(const COP *cop, - const char *keypv, - STRLEN keylen, U32 hash, - U32 flags) - -=for hackers -Found in file cop.h - -=item cop_hints_fetch_pvs -X<cop_hints_fetch_pvs> - -Like L</cop_hints_fetch_pvn>, but takes a literal string instead of a -string/length pair, and no precomputed hash. - - SV * cop_hints_fetch_pvs(const COP *cop, - const char *key, U32 flags) - -=for hackers -Found in file cop.h - -=item cop_hints_fetch_sv -X<cop_hints_fetch_sv> - -Like L</cop_hints_fetch_pvn>, but takes a Perl scalar instead of a -string/length pair. - - SV * cop_hints_fetch_sv(const COP *cop, SV *key, - U32 hash, U32 flags) - -=for hackers -Found in file cop.h - - -=back - -=head1 Custom Operators - -=over 8 - -=item custom_op_register -X<custom_op_register> - -Register a custom op. See L<perlguts/"Custom Operators">. - -NOTE: this function must be explicitly called as Perl_custom_op_register with an aTHX_ parameter. - - void Perl_custom_op_register(pTHX_ - Perl_ppaddr_t ppaddr, - const XOP *xop) - -=for hackers -Found in file op.c - -=item custom_op_xop -X<custom_op_xop> - -Return the XOP structure for a given custom op. This function should be -considered internal to OP_NAME and the other access macros: use them instead. - -NOTE: this function must be explicitly called as Perl_custom_op_xop with an aTHX_ parameter. - - const XOP * Perl_custom_op_xop(pTHX_ const OP *o) - -=for hackers -Found in file op.c - -=item XopDISABLE -X<XopDISABLE> - -Temporarily disable a member of the XOP, by clearing the appropriate flag. - - void XopDISABLE(XOP *xop, which) - -=for hackers -Found in file op.h - -=item XopENABLE -X<XopENABLE> - -Reenable a member of the XOP which has been disabled. - - void XopENABLE(XOP *xop, which) - -=for hackers -Found in file op.h - -=item XopENTRY -X<XopENTRY> - -Return a member of the XOP structure. I<which> is a cpp token indicating -which entry to return. If the member is not set this will return a -default value. The return type depends on I<which>. - - XopENTRY(XOP *xop, which) - -=for hackers -Found in file op.h - -=item XopENTRY_set -X<XopENTRY_set> - -Set a member of the XOP structure. I<which> is a cpp token indicating -which entry to set. See L<perlguts/"Custom Operators"> for details about -the available members and how they are used. - - void XopENTRY_set(XOP *xop, which, value) - -=for hackers -Found in file op.h - -=item XopFLAGS -X<XopFLAGS> - -Return the XOP's flags. - - U32 XopFLAGS(XOP *xop) - -=for hackers -Found in file op.h - - -=back - -=head1 CV Manipulation Functions - -=over 8 - -=item CvSTASH -X<CvSTASH> - -Returns the stash of the CV. A stash is the symbol table hash, containing -the package-scoped variables in the package where the subroutine was defined. -For more information, see L<perlguts>. - -This also has a special use with XS AUTOLOAD subs. -See L<perlguts/Autoloading with XSUBs>. - - HV* CvSTASH(CV* cv) - -=for hackers -Found in file cv.h - -=item get_cv -X<get_cv> - -Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>. - -NOTE: the perl_ form of this function is deprecated. - - CV* get_cv(const char* name, I32 flags) - -=for hackers -Found in file perl.c - -=item get_cvn_flags -X<get_cvn_flags> - -Returns the CV of the specified Perl subroutine. C<flags> are passed to -C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not -exist then it will be declared (which has the same effect as saying -C<sub name;>). If C<GV_ADD> is not set and the subroutine does not exist -then NULL is returned. - -NOTE: the perl_ form of this function is deprecated. - - CV* get_cvn_flags(const char* name, STRLEN len, - I32 flags) - -=for hackers -Found in file perl.c - - -=back - -=head1 Embedding Functions - -=over 8 - -=item cv_clone -X<cv_clone> - -Clone a CV, making a lexical closure. I<proto> supplies the prototype -of the function: its code, pad structure, and other attributes. -The prototype is combined with a capture of outer lexicals to which the -code refers, which are taken from the currently-executing instance of -the immediately surrounding code. - - CV * cv_clone(CV *proto) - -=for hackers -Found in file pad.c - -=item cv_undef -X<cv_undef> - -Clear out all the active components of a CV. This can happen either -by an explicit C<undef &foo>, or by the reference count going to zero. -In the former case, we keep the CvOUTSIDE pointer, so that any anonymous -children can still follow the full lexical scope chain. - - void cv_undef(CV* cv) - -=for hackers -Found in file pad.c - -=item find_rundefsv -X<find_rundefsv> - -Find and return the variable that is named C<$_> in the lexical scope -of the currently-executing function. This may be a lexical C<$_>, -or will otherwise be the global one. - - SV * find_rundefsv() - -=for hackers -Found in file pad.c - -=item find_rundefsvoffset -X<find_rundefsvoffset> - -Find the position of the lexical C<$_> in the pad of the -currently-executing function. Returns the offset in the current pad, -or C<NOT_IN_PAD> if there is no lexical C<$_> in scope (in which case -the global one should be used instead). -L</find_rundefsv> is likely to be more convenient. - -NOTE: the perl_ form of this function is deprecated. - - PADOFFSET find_rundefsvoffset() - -=for hackers -Found in file pad.c - -=item load_module -X<load_module> - -Loads the module whose name is pointed to by the string part of name. -Note that the actual module name, not its filename, should be given. -Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of -PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS -(or 0 for no flags). ver, if specified and not NULL, provides version semantics -similar to C<use Foo::Bar VERSION>. The optional trailing SV* -arguments can be used to specify arguments to the module's import() -method, similar to C<use Foo::Bar VERSION LIST>. They must be -terminated with a final NULL pointer. Note that this list can only -be omitted when the PERL_LOADMOD_NOIMPORT flag has been used. -Otherwise at least a single NULL pointer to designate the default -import list is required. - -The reference count for each specified C<SV*> parameter is decremented. - - void load_module(U32 flags, SV* name, SV* ver, ...) - -=for hackers -Found in file op.c - -=item nothreadhook -X<nothreadhook> - -Stub that provides thread hook for perl_destruct when there are -no threads. - - int nothreadhook() - -=for hackers -Found in file perl.c - -=item pad_add_anon -X<pad_add_anon> - -Allocates a place in the currently-compiling pad (via L</pad_alloc>) -for an anonymous function that is lexically scoped inside the -currently-compiling function. -The function I<func> is linked into the pad, and its C<CvOUTSIDE> link -to the outer scope is weakened to avoid a reference loop. - -I<optype> should be an opcode indicating the type of operation that the -pad entry is to support. This doesn't affect operational semantics, -but is used for debugging. - - PADOFFSET pad_add_anon(CV *func, I32 optype) - -=for hackers -Found in file pad.c - -=item pad_add_name_pv -X<pad_add_name_pv> - -Exactly like L</pad_add_name_pvn>, but takes a nul-terminated string -instead of a string/length pair. - - PADOFFSET pad_add_name_pv(const char *name, U32 flags, - HV *typestash, HV *ourstash) - -=for hackers -Found in file pad.c - -=item pad_add_name_pvn -X<pad_add_name_pvn> - -Allocates a place in the currently-compiling pad for a named lexical -variable. Stores the name and other metadata in the name part of the -pad, and makes preparations to manage the variable's lexical scoping. -Returns the offset of the allocated pad slot. - -I<namepv>/I<namelen> specify the variable's name, including leading sigil. -If I<typestash> is non-null, the name is for a typed lexical, and this -identifies the type. If I<ourstash> is non-null, it's a lexical reference -to a package variable, and this identifies the package. The following -flags can be OR'ed together: - - padadd_OUR redundantly specifies if it's a package var - padadd_STATE variable will retain value persistently - padadd_NO_DUP_CHECK skip check for lexical shadowing - - PADOFFSET pad_add_name_pvn(const char *namepv, - STRLEN namelen, U32 flags, - HV *typestash, HV *ourstash) - -=for hackers -Found in file pad.c - -=item pad_add_name_sv -X<pad_add_name_sv> - -Exactly like L</pad_add_name_pvn>, but takes the name string in the form -of an SV instead of a string/length pair. - - PADOFFSET pad_add_name_sv(SV *name, U32 flags, - HV *typestash, HV *ourstash) - -=for hackers -Found in file pad.c - -=item pad_alloc -X<pad_alloc> - -Allocates a place in the currently-compiling pad, -returning the offset of the allocated pad slot. -No name is initially attached to the pad slot. -I<tmptype> is a set of flags indicating the kind of pad entry required, -which will be set in the value SV for the allocated pad entry: - - SVs_PADMY named lexical variable ("my", "our", "state") - SVs_PADTMP unnamed temporary store - -I<optype> should be an opcode indicating the type of operation that the -pad entry is to support. This doesn't affect operational semantics, -but is used for debugging. - -NOTE: this function is experimental and may change or be -removed without notice. - - PADOFFSET pad_alloc(I32 optype, U32 tmptype) - -=for hackers -Found in file pad.c - -=item pad_compname_type -X<pad_compname_type> - -Looks up the type of the lexical variable at position I<po> in the -currently-compiling pad. If the variable is typed, the stash of the -class to which it is typed is returned. If not, C<NULL> is returned. - - HV * pad_compname_type(PADOFFSET po) - -=for hackers -Found in file pad.c - -=item pad_findmy_pv -X<pad_findmy_pv> - -Exactly like L</pad_findmy_pvn>, but takes a nul-terminated string -instead of a string/length pair. - - PADOFFSET pad_findmy_pv(const char *name, U32 flags) - -=for hackers -Found in file pad.c - -=item pad_findmy_pvn -X<pad_findmy_pvn> - -Given the name of a lexical variable, find its position in the -currently-compiling pad. -I<namepv>/I<namelen> specify the variable's name, including leading sigil. -I<flags> is reserved and must be zero. -If it is not in the current pad but appears in the pad of any lexically -enclosing scope, then a pseudo-entry for it is added in the current pad. -Returns the offset in the current pad, -or C<NOT_IN_PAD> if no such lexical is in scope. - - PADOFFSET pad_findmy_pvn(const char *namepv, - STRLEN namelen, U32 flags) - -=for hackers -Found in file pad.c - -=item pad_findmy_sv -X<pad_findmy_sv> - -Exactly like L</pad_findmy_pvn>, but takes the name string in the form -of an SV instead of a string/length pair. - - PADOFFSET pad_findmy_sv(SV *name, U32 flags) - -=for hackers -Found in file pad.c - -=item pad_setsv -X<pad_setsv> - -Set the value at offset I<po> in the current (compiling or executing) pad. -Use the macro PAD_SETSV() rather than calling this function directly. - - void pad_setsv(PADOFFSET po, SV *sv) - -=for hackers -Found in file pad.c - -=item pad_sv -X<pad_sv> - -Get the value at offset I<po> in the current (compiling or executing) pad. -Use macro PAD_SV instead of calling this function directly. - - SV * pad_sv(PADOFFSET po) - -=for hackers -Found in file pad.c - -=item pad_tidy -X<pad_tidy> - -Tidy up a pad at the end of compilation of the code to which it belongs. -Jobs performed here are: remove most stuff from the pads of anonsub -prototypes; give it a @_; mark temporaries as such. I<type> indicates -the kind of subroutine: - - padtidy_SUB ordinary subroutine - padtidy_SUBCLONE prototype for lexical closure - padtidy_FORMAT format - -NOTE: this function is experimental and may change or be -removed without notice. - - void pad_tidy(padtidy_type type) - -=for hackers -Found in file pad.c - -=item perl_alloc -X<perl_alloc> - -Allocates a new Perl interpreter. See L<perlembed>. - - PerlInterpreter* perl_alloc() - -=for hackers -Found in file perl.c - -=item perl_construct -X<perl_construct> - -Initializes a new Perl interpreter. See L<perlembed>. - - void perl_construct(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item perl_destruct -X<perl_destruct> - -Shuts down a Perl interpreter. See L<perlembed>. - - int perl_destruct(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item perl_free -X<perl_free> - -Releases a Perl interpreter. See L<perlembed>. - - void perl_free(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item perl_parse -X<perl_parse> - -Tells a Perl interpreter to parse a Perl script. See L<perlembed>. - - int perl_parse(PerlInterpreter *my_perl, - XSINIT_t xsinit, int argc, - char** argv, char** env) - -=for hackers -Found in file perl.c - -=item perl_run -X<perl_run> - -Tells a Perl interpreter to run. See L<perlembed>. - - int perl_run(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item require_pv -X<require_pv> - -Tells Perl to C<require> the file named by the string argument. It is -analogous to the Perl code C<eval "require '$file'">. It's even -implemented that way; consider using load_module instead. - -NOTE: the perl_ form of this function is deprecated. - - void require_pv(const char* pv) - -=for hackers -Found in file perl.c - - -=back - -=head1 Functions in file dump.c - - -=over 8 - -=item pv_display -X<pv_display> - -Similar to - - pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE); - -except that an additional "\0" will be appended to the string when -len > cur and pv[cur] is "\0". - -Note that the final string may be up to 7 chars longer than pvlim. - - char* pv_display(SV *dsv, const char *pv, STRLEN cur, - STRLEN len, STRLEN pvlim) - -=for hackers -Found in file dump.c - -=item pv_escape -X<pv_escape> - -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. - -If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string -will also be escaped. - -Normally the SV will be cleared before the escaped string is prepared, -but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur. - -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<is_utf8_string()> to determine if it is Unicode. - -If PERL_PV_ESCAPE_ALL is set then all input chars will be output -using C<\x01F1> style escapes, otherwise if PERL_PV_ESCAPE_NONASCII is set, only -chars above 127 will be escaped using this style; otherwise, only chars above -255 will be so escaped; other non printable chars will use octal or -common escaped patterns like C<\n>. Otherwise, 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, regardless of max. If the output is to be in hex, -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 hex value. - -If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and -not a '\\'. This is because regexes very often contain backslashed -sequences, whereas '%' is not a particularly common character in patterns. - -Returns a pointer to the escaped text as held by dsv. - - char* pv_escape(SV *dsv, char const * const str, - const STRLEN count, const STRLEN max, - STRLEN * const escaped, - const U32 flags) - -=for hackers -Found in file dump.c - -=item pv_pretty -X<pv_pretty> - -Converts a string into something presentable, handling escaping via -pv_escape() and supporting quoting and ellipses. - -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_ELLIPSES flag is set and not all characters in -string were output then an ellipsis 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 ellipses. - -Returns a pointer to the prettified text as held by dsv. - - 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 dump.c - - -=back - -=head1 Functions in file mathoms.c - - -=over 8 - -=item custom_op_desc -X<custom_op_desc> - -Return the description of a given custom op. This was once used by the -OP_DESC macro, but is no longer: it has only been kept for -compatibility, and should not be used. - - const char * custom_op_desc(const OP *o) - -=for hackers -Found in file mathoms.c - -=item custom_op_name -X<custom_op_name> - -Return the name for a given custom op. This was once used by the OP_NAME -macro, but is no longer: it has only been kept for compatibility, and -should not be used. - - const char * custom_op_name(const OP *o) - -=for hackers -Found in file mathoms.c - -=item gv_fetchmethod -X<gv_fetchmethod> - -See L</gv_fetchmethod_autoload>. - - GV* gv_fetchmethod(HV* stash, const char* name) - -=for hackers -Found in file mathoms.c - -=item pack_cat -X<pack_cat> - -The engine implementing pack() Perl function. Note: parameters next_in_list and -flags are not used. This call should not be used; use packlist instead. - - void pack_cat(SV *cat, const char *pat, - const char *patend, SV **beglist, - SV **endlist, SV ***next_in_list, - U32 flags) - -=for hackers -Found in file mathoms.c - -=item sv_2pvbyte_nolen -X<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<SvPVbyte_nolen> macro. - - char* sv_2pvbyte_nolen(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_2pvutf8_nolen -X<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<SvPVutf8_nolen> macro. - - char* sv_2pvutf8_nolen(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_2pv_nolen -X<sv_2pv_nolen> - -Like C<sv_2pv()>, but doesn't return the length too. You should usually -use the macro wrapper C<SvPV_nolen(sv)> instead. - - char* sv_2pv_nolen(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_catpvn_mg -X<sv_catpvn_mg> - -Like C<sv_catpvn>, but also handles 'set' magic. - - void sv_catpvn_mg(SV *sv, const char *ptr, - STRLEN len) - -=for hackers -Found in file mathoms.c - -=item sv_catsv_mg -X<sv_catsv_mg> - -Like C<sv_catsv>, but also handles 'set' magic. - - void sv_catsv_mg(SV *dsv, SV *ssv) - -=for hackers -Found in file mathoms.c - -=item sv_force_normal -X<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<sv_force_normal_flags>. - - void sv_force_normal(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_iv -X<sv_iv> - -A private implementation of the C<SvIVx> macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - IV sv_iv(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_nolocking -X<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. - -"Superseded" by sv_nosharing(). - - void sv_nolocking(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_nounlocking -X<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. - -"Superseded" by sv_nosharing(). - - void sv_nounlocking(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_nv -X<sv_nv> - -A private implementation of the C<SvNVx> macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - NV sv_nv(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_pv -X<sv_pv> - -Use the C<SvPV_nolen> macro instead - - char* sv_pv(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_pvbyte -X<sv_pvbyte> - -Use C<SvPVbyte_nolen> instead. - - char* sv_pvbyte(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_pvbyten -X<sv_pvbyten> - -A private implementation of the C<SvPVbyte> macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. - - char* sv_pvbyten(SV *sv, STRLEN *lp) - -=for hackers -Found in file mathoms.c - -=item sv_pvn -X<sv_pvn> - -A private implementation of the C<SvPV> macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - char* sv_pvn(SV *sv, STRLEN *lp) - -=for hackers -Found in file mathoms.c - -=item sv_pvutf8 -X<sv_pvutf8> - -Use the C<SvPVutf8_nolen> macro instead - - char* sv_pvutf8(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_pvutf8n -X<sv_pvutf8n> - -A private implementation of the C<SvPVutf8> macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. - - char* sv_pvutf8n(SV *sv, STRLEN *lp) - -=for hackers -Found in file mathoms.c - -=item sv_taint -X<sv_taint> - -Taint an SV. Use C<SvTAINTED_on> instead. - - void sv_taint(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_unref -X<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<newSVrv>. This is C<sv_unref_flags> with the C<flag> -being zero. See C<SvROK_off>. - - void sv_unref(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_usepvn -X<sv_usepvn> - -Tells an SV to use C<ptr> to find its string value. Implemented by -calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set' -magic. See C<sv_usepvn_flags>. - - void sv_usepvn(SV* sv, char* ptr, STRLEN len) - -=for hackers -Found in file mathoms.c - -=item sv_usepvn_mg -X<sv_usepvn_mg> - -Like C<sv_usepvn>, 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<sv_uv> - -A private implementation of the C<SvUVx> 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<unpack_str> - -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 op.c - - -=over 8 - -=item op_contextualize -X<op_contextualize> - -Applies a syntactic context to an op tree representing an expression. -I<o> is the op tree, and I<context> must be C<G_SCALAR>, C<G_ARRAY>, -or C<G_VOID> to specify the context to apply. The modified op tree -is returned. - - OP * op_contextualize(OP *o, I32 context) - -=for hackers -Found in file op.c - - -=back - -=head1 Functions in file perl.h - - -=over 8 - -=item PERL_SYS_INIT -X<PERL_SYS_INIT> - -Provides system-specific tune up of the C runtime environment necessary to -run Perl interpreters. This should be called only once, before creating -any Perl interpreters. - - void PERL_SYS_INIT(int argc, char** argv) - -=for hackers -Found in file perl.h - -=item PERL_SYS_INIT3 -X<PERL_SYS_INIT3> - -Provides system-specific tune up of the C runtime environment necessary to -run Perl interpreters. This should be called only once, before creating -any Perl interpreters. - - void PERL_SYS_INIT3(int argc, char** argv, - char** env) - -=for hackers -Found in file perl.h - -=item PERL_SYS_TERM -X<PERL_SYS_TERM> - -Provides system-specific clean up of the C runtime environment after -running Perl interpreters. This should be called only once, after -freeing any remaining Perl interpreters. - - void PERL_SYS_TERM() - -=for hackers -Found in file perl.h - - -=back - -=head1 Functions in file pp_ctl.c - - -=over 8 - -=item caller_cx -X<caller_cx> - -The XSUB-writer's equivalent of L<caller()|perlfunc/caller>. The -returned C<PERL_CONTEXT> structure can be interrogated to find all the -information returned to Perl by C<caller>. Note that XSUBs don't get a -stack frame, so C<caller_cx(0, NULL)> will return information for the -immediately-surrounding Perl code. - -This function skips over the automatic calls to C<&DB::sub> made on the -behalf of the debugger. If the stack frame requested was a sub called by -C<DB::sub>, the return value will be the frame for the call to -C<DB::sub>, since that has the correct line number/etc. for the call -site. If I<dbcxp> is non-C<NULL>, it will be set to a pointer to the -frame for the sub call itself. - - const PERL_CONTEXT * caller_cx( - I32 level, - const PERL_CONTEXT **dbcxp - ) - -=for hackers -Found in file pp_ctl.c - -=item find_runcv -X<find_runcv> - -Locate the CV corresponding to the currently executing sub or eval. -If db_seqp is non_null, skip CVs that are in the DB package and populate -*db_seqp with the cop sequence number at the point that the DB:: code was -entered. (allows debuggers to eval in the scope of the breakpoint rather -than in the scope of the debugger itself). - - CV* find_runcv(U32 *db_seqp) - -=for hackers -Found in file pp_ctl.c - - -=back - -=head1 Functions in file pp_pack.c - - -=over 8 - -=item packlist -X<packlist> - -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<unpackstring> - -The engine implementing unpack() Perl function. C<unpackstring> puts the -extracted list items on the stack and returns the number of elements. -Issue C<PUTBACK> before and C<SPAGAIN> 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 Functions in file pp_sys.c - - -=over 8 - -=item setdefout -X<setdefout> - -Sets PL_defoutgv, the default file handle for output, to the passed in -typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference -count of the passed in typeglob is increased by one, and the reference count -of the typeglob that PL_defoutgv points to is decreased by one. - - void setdefout(GV* gv) - -=for hackers -Found in file pp_sys.c - - -=back - -=head1 Functions in file utf8.h - - -=over 8 - -=item ibcmp_utf8 -X<ibcmp_utf8> - -This is a synonym for (! foldEQ_utf8()) - - I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, - bool u1, const char *s2, char **pe2, - UV l2, bool u2) - -=for hackers -Found in file utf8.h - - -=back - -=head1 Functions in file util.h - - -=over 8 - -=item ibcmp -X<ibcmp> - -This is a synonym for (! foldEQ()) - - I32 ibcmp(const char* a, const char* b, I32 len) - -=for hackers -Found in file util.h - -=item ibcmp_locale -X<ibcmp_locale> - -This is a synonym for (! foldEQ_locale()) - - I32 ibcmp_locale(const char* a, const char* b, - I32 len) - -=for hackers -Found in file util.h - - -=back - -=head1 Global Variables - -=over 8 - -=item PL_check -X<PL_check> - -Array, indexed by opcode, of functions that will be called for the "check" -phase of optree building during compilation of Perl code. For most (but -not all) types of op, once the op has been initially built and populated -with child ops it will be filtered through the check function referenced -by the appropriate element of this array. The new op is passed in as the -sole argument to the check function, and the check function returns the -completed op. The check function may (as the name suggests) check the op -for validity and signal errors. It may also initialise or modify parts of -the ops, or perform more radical surgery such as adding or removing child -ops, or even throw the op away and return a different op in its place. - -This array of function pointers is a convenient place to hook into the -compilation process. An XS module can put its own custom check function -in place of any of the standard ones, to influence the compilation of a -particular type of op. However, a custom check function must never fully -replace a standard check function (or even a custom check function from -another module). A module modifying checking must instead B<wrap> the -preexisting check function. A custom check function must be selective -about when to apply its custom behaviour. In the usual case where -it decides not to do anything special with an op, it must chain the -preexisting op function. Check functions are thus linked in a chain, -with the core's base checker at the end. - -For thread safety, modules should not write directly to this array. -Instead, use the function L</wrap_op_checker>. - -=for hackers -Found in file perlvars.h - -=item PL_keyword_plugin -X<PL_keyword_plugin> - -Function pointer, pointing at a function used to handle extended keywords. -The function should be declared as - - int keyword_plugin_function(pTHX_ - char *keyword_ptr, STRLEN keyword_len, - OP **op_ptr) - -The function is called from the tokeniser, whenever a possible keyword -is seen. C<keyword_ptr> points at the word in the parser's input -buffer, and C<keyword_len> gives its length; it is not null-terminated. -The function is expected to examine the word, and possibly other state -such as L<%^H|perlvar/%^H>, to decide whether it wants to handle it -as an extended keyword. If it does not, the function should return -C<KEYWORD_PLUGIN_DECLINE>, and the normal parser process will continue. - -If the function wants to handle the keyword, it first must -parse anything following the keyword that is part of the syntax -introduced by the keyword. See L</Lexer interface> for details. - -When a keyword is being handled, the plugin function must build -a tree of C<OP> structures, representing the code that was parsed. -The root of the tree must be stored in C<*op_ptr>. The function then -returns a constant indicating the syntactic role of the construct that -it has parsed: C<KEYWORD_PLUGIN_STMT> if it is a complete statement, or -C<KEYWORD_PLUGIN_EXPR> if it is an expression. Note that a statement -construct cannot be used inside an expression (except via C<do BLOCK> -and similar), and an expression is not a complete statement (it requires -at least a terminating semicolon). - -When a keyword is handled, the plugin function may also have -(compile-time) side effects. It may modify C<%^H>, define functions, and -so on. Typically, if side effects are the main purpose of a handler, -it does not wish to generate any ops to be included in the normal -compilation. In this case it is still required to supply an op tree, -but it suffices to generate a single null op. - -That's how the C<*PL_keyword_plugin> function needs to behave overall. -Conventionally, however, one does not completely replace the existing -handler function. Instead, take a copy of C<PL_keyword_plugin> before -assigning your own function pointer to it. Your handler function should -look for keywords that it is interested in and handle those. Where it -is not interested, it should call the saved plugin function, passing on -the arguments it received. Thus C<PL_keyword_plugin> actually points -at a chain of handler functions, all of which have an opportunity to -handle keywords, and only the last function in the chain (built into -the Perl core) will normally return C<KEYWORD_PLUGIN_DECLINE>. - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file perlvars.h - - -=back - -=head1 GV Functions - -=over 8 - -=item GvSV -X<GvSV> - -Return the SV from the GV. - - SV* GvSV(GV* gv) - -=for hackers -Found in file gv.h - -=item gv_const_sv -X<gv_const_sv> - -If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for -inlining, or C<gv> 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<gv_fetchmeth> - -Like L</gv_fetchmeth_pvn>, but lacks a flags parameter. - - GV* gv_fetchmeth(HV* stash, const char* name, - STRLEN len, I32 level) - -=for hackers -Found in file gv.c - -=item gv_fetchmethod_autoload -X<gv_fetchmethod_autoload> - -Returns the glob which contains the subroutine to call to invoke the method -on the C<stash>. 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<gv_fetchmethod_autoload> 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<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload> -with a non-zero C<autoload> 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<gv_fetchmeth> with -C<level==0>. C<name> should be writable if contains C<':'> or C<' -''>. The warning against passing the GV returned by C<gv_fetchmeth> to -C<call_sv> 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<gv_fetchmeth_autoload> - -This is the old form of L</gv_fetchmeth_pvn_autoload>, which has no flags -parameter. - - GV* gv_fetchmeth_autoload(HV* stash, - const char* name, - STRLEN len, I32 level) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth_pv -X<gv_fetchmeth_pv> - -Exactly like L</gv_fetchmeth_pvn>, but takes a nul-terminated string -instead of a string/length pair. - - GV* gv_fetchmeth_pv(HV* stash, const char* name, - I32 level, U32 flags) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth_pvn -X<gv_fetchmeth_pvn> - -Returns the glob with the given C<name> and a defined subroutine or -C<NULL>. The glob lives in the given C<stash>, or in the stashes -accessible via @ISA and UNIVERSAL::. - -The argument C<level> should be either 0 or -1. If C<level==0>, as a -side-effect creates a glob with the given C<name> in the given C<stash> -which in the case of success contains an alias for the subroutine, and sets -up caching info for this glob. - -Currently, the only significant value for C<flags> is SVf_UTF8. - -This function grants C<"SUPER"> token as a postfix of the stash name. The -GV returned from C<gv_fetchmeth> may be a method cache entry, which is not -visible to Perl code. So when calling C<call_sv>, 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<GvCV> macro. - - GV* gv_fetchmeth_pvn(HV* stash, const char* name, - STRLEN len, I32 level, - U32 flags) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth_pvn_autoload -X<gv_fetchmeth_pvn_autoload> - -Same as gv_fetchmeth_pvn(), 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<level < 0>. For an autoloaded subroutine without a stub, GvCV() -of the result may be zero. - -Currently, the only significant value for C<flags> is SVf_UTF8. - - GV* gv_fetchmeth_pvn_autoload(HV* stash, - const char* name, - STRLEN len, I32 level, - U32 flags) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth_pv_autoload -X<gv_fetchmeth_pv_autoload> - -Exactly like L</gv_fetchmeth_pvn_autoload>, but takes a nul-terminated string -instead of a string/length pair. - - GV* gv_fetchmeth_pv_autoload(HV* stash, - const char* name, - I32 level, U32 flags) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth_sv -X<gv_fetchmeth_sv> - -Exactly like L</gv_fetchmeth_pvn>, but takes the name string in the form -of an SV instead of a string/length pair. - - GV* gv_fetchmeth_sv(HV* stash, SV* namesv, - I32 level, U32 flags) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth_sv_autoload -X<gv_fetchmeth_sv_autoload> - -Exactly like L</gv_fetchmeth_pvn_autoload>, but takes the name string in the form -of an SV instead of a string/length pair. - - GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv, - I32 level, U32 flags) - -=for hackers -Found in file gv.c - -=item gv_init -X<gv_init> - -The old form of gv_init_pvn(). It does not work with UTF8 strings, as it -has no flags parameter. If the C<multi> parameter is set, the -GV_ADDMULTI flag will be passed to gv_init_pvn(). - - void gv_init(GV* gv, HV* stash, const char* name, - STRLEN len, int multi) - -=for hackers -Found in file gv.c - -=item gv_init_pv -X<gv_init_pv> - -Same as gv_init_pvn(), but takes a nul-terminated string for the name -instead of separate char * and length parameters. - - void gv_init_pv(GV* gv, HV* stash, const char* name, - U32 flags) - -=for hackers -Found in file gv.c - -=item gv_init_pvn -X<gv_init_pvn> - -Converts a scalar into a typeglob. This is an incoercible typeglob; -assigning a reference to it will assign to one of its slots, instead of -overwriting it as happens with typeglobs created by SvSetSV. Converting -any scalar that is SvOK() may produce unpredictable results and is reserved -for perl's internal use. - -C<gv> is the scalar to be converted. - -C<stash> is the parent stash/package, if any. - -C<name> and C<len> give the name. The name must be unqualified; -that is, it must not include the package name. If C<gv> is a -stash element, it is the caller's responsibility to ensure that the name -passed to this function matches the name of the element. If it does not -match, perl's internal bookkeeping will get out of sync. - -C<flags> can be set to SVf_UTF8 if C<name> is a UTF8 string, or -the return value of SvUTF8(sv). It can also take the -GV_ADDMULTI flag, which means to pretend that the GV has been -seen before (i.e., suppress "Used once" warnings). - - void gv_init_pvn(GV* gv, HV* stash, const char* name, - STRLEN len, U32 flags) - -=for hackers -Found in file gv.c - -=item gv_init_sv -X<gv_init_sv> - -Same as gv_init_pvn(), but takes an SV * for the name instead of separate -char * and length parameters. C<flags> is currently unused. - - void gv_init_sv(GV* gv, HV* stash, SV* namesv, - U32 flags) - -=for hackers -Found in file gv.c - -=item gv_stashpv -X<gv_stashpv> - -Returns a pointer to the stash for a specified package. Uses C<strlen> to -determine the length of C<name>, then calls C<gv_stashpvn()>. - - HV* gv_stashpv(const char* name, I32 flags) - -=for hackers -Found in file gv.c - -=item gv_stashpvn -X<gv_stashpvn> - -Returns a pointer to the stash for a specified package. The C<namelen> -parameter indicates the length of the C<name>, in bytes. C<flags> is passed -to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be -created if it does not already exist. If the package does not exist and -C<flags> is 0 (or any other setting that does not create packages) then NULL -is returned. - - - HV* gv_stashpvn(const char* name, U32 namelen, - I32 flags) - -=for hackers -Found in file gv.c - -=item gv_stashpvs -X<gv_stashpvs> - -Like C<gv_stashpvn>, 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<gv_stashsv> - -Returns a pointer to the stash for a specified package. See C<gv_stashpvn>. - - HV* gv_stashsv(SV* sv, I32 flags) - -=for hackers -Found in file gv.c - - -=back - -=head1 Handy Values - -=over 8 - -=item Nullav -X<Nullav> - -Null AV pointer. - -(deprecated - use C<(AV *)NULL> instead) - -=for hackers -Found in file av.h - -=item Nullch -X<Nullch> - -Null character pointer. (No longer available when C<PERL_CORE> is defined.) - -=for hackers -Found in file handy.h - -=item Nullcv -X<Nullcv> - -Null CV pointer. - -(deprecated - use C<(CV *)NULL> instead) - -=for hackers -Found in file cv.h - -=item Nullhv -X<Nullhv> - -Null HV pointer. - -(deprecated - use C<(HV *)NULL> instead) - -=for hackers -Found in file hv.h - -=item Nullsv -X<Nullsv> - -Null SV pointer. (No longer available when C<PERL_CORE> is defined.) - -=for hackers -Found in file handy.h - - -=back - -=head1 Hash Manipulation Functions - -=over 8 - -=item cop_fetch_label -X<cop_fetch_label> - -Returns the label attached to a cop. -The flags pointer may be set to C<SVf_UTF8> or 0. - -NOTE: this function is experimental and may change or be -removed without notice. - - const char * cop_fetch_label(COP *const cop, - STRLEN *len, U32 *flags) - -=for hackers -Found in file hv.c - -=item cop_store_label -X<cop_store_label> - -Save a label into a C<cop_hints_hash>. You need to set flags to C<SVf_UTF8> -for a utf-8 label. - -NOTE: this function is experimental and may change or be -removed without notice. - - void cop_store_label(COP *const cop, - const char *label, STRLEN len, - U32 flags) - -=for hackers -Found in file hv.c - -=item get_hv -X<get_hv> - -Returns the HV of the specified Perl hash. C<flags> are passed to -C<gv_fetchpv>. If C<GV_ADD> is set and the -Perl variable does not exist then it will be created. If C<flags> is zero -and the variable does not exist then NULL is returned. - -NOTE: the perl_ form of this function is deprecated. - - HV* get_hv(const char *name, I32 flags) - -=for hackers -Found in file perl.c - -=item HEf_SVKEY -X<HEf_SVKEY> - -This flag, used in the length slot of hash entries and magic structures, -specifies the structure contains an C<SV*> pointer where a C<char*> pointer -is to be expected. (For information only--not to be used). - -=for hackers -Found in file hv.h - -=item HeHASH -X<HeHASH> - -Returns the computed hash stored in the hash entry. - - U32 HeHASH(HE* he) - -=for hackers -Found in file hv.h - -=item HeKEY -X<HeKEY> - -Returns the actual pointer stored in the key slot of the hash entry. The -pointer may be either C<char*> or C<SV*>, depending on the value of -C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are -usually preferable for finding the value of a key. - - void* HeKEY(HE* he) - -=for hackers -Found in file hv.h - -=item HeKLEN -X<HeKLEN> - -If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry -holds an C<SV*> key. Otherwise, holds the actual length of the key. Can -be assigned to. The C<HePV()> macro is usually preferable for finding key -lengths. - - STRLEN HeKLEN(HE* he) - -=for hackers -Found in file hv.h - -=item HePV -X<HePV> - -Returns the key slot of the hash entry as a C<char*> value, doing any -necessary dereferencing of possibly C<SV*> keys. The length of the string -is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do -not care about what the length of the key is, you may use the global -variable C<PL_na>, though this is rather less efficient than using a local -variable. Remember though, that hash keys in perl are free to contain -embedded nulls, so using C<strlen()> or similar is not a good way to find -the length of hash keys. This is very similar to the C<SvPV()> macro -described elsewhere in this document. See also C<HeUTF8>. - -If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a -new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more -efficient. - - char* HePV(HE* he, STRLEN len) - -=for hackers -Found in file hv.h - -=item HeSVKEY -X<HeSVKEY> - -Returns the key as an C<SV*>, or C<NULL> if the hash entry does not -contain an C<SV*> key. - - SV* HeSVKEY(HE* he) - -=for hackers -Found in file hv.h - -=item HeSVKEY_force -X<HeSVKEY_force> - -Returns the key as an C<SV*>. Will create and return a temporary mortal -C<SV*> if the hash entry contains only a C<char*> key. - - SV* HeSVKEY_force(HE* he) - -=for hackers -Found in file hv.h - -=item HeSVKEY_set -X<HeSVKEY_set> - -Sets the key to a given C<SV*>, taking care to set the appropriate flags to -indicate the presence of an C<SV*> key, and returns the same -C<SV*>. - - SV* HeSVKEY_set(HE* he, SV* sv) - -=for hackers -Found in file hv.h - -=item HeUTF8 -X<HeUTF8> - -Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8, -doing any necessary dereferencing of possibly C<SV*> keys. The value returned -will be 0 or non-0, not necessarily 1 (or even a value with any low bits set), -so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a -typedef for C<char>. - - char* HeUTF8(HE* he) - -=for hackers -Found in file hv.h - -=item HeVAL -X<HeVAL> - -Returns the value slot (type C<SV*>) stored in the hash entry. - - SV* HeVAL(HE* he) - -=for hackers -Found in file hv.h - -=item HvENAME -X<HvENAME> - -Returns the effective name of a stash, or NULL if there is none. The -effective name represents a location in the symbol table where this stash -resides. It is updated automatically when packages are aliased or deleted. -A stash that is no longer in the symbol table has no effective name. This -name is preferable to C<HvNAME> for use in MRO linearisations and isa -caches. - - char* HvENAME(HV* stash) - -=for hackers -Found in file hv.h - -=item HvENAMELEN -X<HvENAMELEN> - -Returns the length of the stash's effective name. - - STRLEN HvENAMELEN(HV *stash) - -=for hackers -Found in file hv.h - -=item HvENAMEUTF8 -X<HvENAMEUTF8> - -Returns true if the effective name is in UTF8 encoding. - - unsigned char HvENAMEUTF8(HV *stash) - -=for hackers -Found in file hv.h - -=item HvNAME -X<HvNAME> - -Returns the package name of a stash, or NULL if C<stash> isn't a stash. -See C<SvSTASH>, C<CvSTASH>. - - char* HvNAME(HV* stash) - -=for hackers -Found in file hv.h - -=item HvNAMELEN -X<HvNAMELEN> - -Returns the length of the stash's name. - - STRLEN HvNAMELEN(HV *stash) - -=for hackers -Found in file hv.h - -=item HvNAMEUTF8 -X<HvNAMEUTF8> - -Returns true if the name is in UTF8 encoding. - - unsigned char HvNAMEUTF8(HV *stash) - -=for hackers -Found in file hv.h - -=item hv_assert -X<hv_assert> - -Check that a hash is in an internally consistent state. - - void hv_assert(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_clear -X<hv_clear> - -Frees the all the elements of a hash, leaving it empty. -The XS equivalent of C<%hash = ()>. See also L</hv_undef>. - -If any destructors are triggered as a result, the hv itself may -be freed. - - void hv_clear(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_clear_placeholders -X<hv_clear_placeholders> - -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 -deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags -it so it will be ignored by future operations such as iterating over the hash, -but will still allow the hash to have a value reassigned to the key at some -future point. This function clears any such placeholder keys from the hash. -See Hash::Util::lock_keys() for an example of its use. - - void hv_clear_placeholders(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_copy_hints_hv -X<hv_copy_hints_hv> - -A specialised version of L</newHVhv> for copying C<%^H>. I<ohv> must be -a pointer to a hash (which may have C<%^H> magic, but should be generally -non-magical), or C<NULL> (interpreted as an empty hash). The content -of I<ohv> is copied to a new hash, which has the C<%^H>-specific magic -added to it. A pointer to the new hash is returned. - - HV * hv_copy_hints_hv(HV *ohv) - -=for hackers -Found in file hv.c - -=item hv_delete -X<hv_delete> - -Deletes a key/value pair in the hash. The value's SV is removed from -the hash, made mortal, and returned to the caller. The absolute -value of C<klen> is the length of the key. If C<klen> is negative the -key is assumed to be in UTF-8-encoded Unicode. The C<flags> value -will normally be zero; if set to G_DISCARD then NULL will be returned. -NULL will also be returned if the key is not found. - - SV* hv_delete(HV *hv, const char *key, I32 klen, - I32 flags) - -=for hackers -Found in file hv.c - -=item hv_delete_ent -X<hv_delete_ent> - -Deletes a key/value pair in the hash. The value SV is removed from the hash, -made mortal, and returned to the caller. The C<flags> value will normally be -zero; if set to G_DISCARD then NULL will be returned. NULL will also be -returned if the key is not found. C<hash> can be a valid precomputed hash -value, or 0 to ask for it to be computed. - - SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, - U32 hash) - -=for hackers -Found in file hv.c - -=item hv_exists -X<hv_exists> - -Returns a boolean indicating whether the specified hash key exists. The -absolute value of C<klen> is the length of the key. If C<klen> is -negative the key is assumed to be in UTF-8-encoded Unicode. - - bool hv_exists(HV *hv, const char *key, I32 klen) - -=for hackers -Found in file hv.c - -=item hv_exists_ent -X<hv_exists_ent> - -Returns a boolean indicating whether -the specified hash key exists. C<hash> -can be a valid precomputed hash value, or 0 to ask for it to be -computed. - - bool hv_exists_ent(HV *hv, SV *keysv, U32 hash) - -=for hackers -Found in file hv.c - -=item hv_fetch -X<hv_fetch> - -Returns the SV which corresponds to the specified key in the hash. -The absolute value of C<klen> is the length of the key. If C<klen> is -negative the key is assumed to be in UTF-8-encoded Unicode. If -C<lval> is set then the fetch will be part of a store. Check that the -return value is non-null before dereferencing it to an C<SV*>. - -See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more -information on how to use this function on tied hashes. - - SV** hv_fetch(HV *hv, const char *key, I32 klen, - I32 lval) - -=for hackers -Found in file hv.c - -=item hv_fetchs -X<hv_fetchs> - -Like C<hv_fetch>, 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<hv_fetch_ent> - -Returns the hash entry which corresponds to the specified key in the hash. -C<hash> must be a valid precomputed hash number for the given C<key>, or 0 -if you want the function to compute it. IF C<lval> is set then the fetch -will be part of a store. Make sure the return value is non-null before -accessing it. The return value when C<hv> is a tied hash is a pointer to a -static location, so be sure to make a copy of the structure if you need to -store it somewhere. - -See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more -information on how to use this function on tied hashes. - - HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, - U32 hash) - -=for hackers -Found in file hv.c - -=item hv_fill -X<hv_fill> - -Returns the number of hash buckets that happen to be in use. This function is -wrapped by the macro C<HvFILL>. - -Previously this value was stored in the HV structure, rather than being -calculated on demand. - - STRLEN hv_fill(HV const *const hv) - -=for hackers -Found in file hv.c - -=item hv_iterinit -X<hv_iterinit> - -Prepares a starting point to traverse a hash table. Returns the number of -keys in the hash (i.e. the same as C<HvUSEDKEYS(hv)>). The return value is -currently only meaningful for hashes without tie magic. - -NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of -hash buckets that happen to be in use. If you still need that esoteric -value, you can get it through the macro C<HvFILL(hv)>. - - - I32 hv_iterinit(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_iterkey -X<hv_iterkey> - -Returns the key from the current position of the hash iterator. See -C<hv_iterinit>. - - char* hv_iterkey(HE* entry, I32* retlen) - -=for hackers -Found in file hv.c - -=item hv_iterkeysv -X<hv_iterkeysv> - -Returns the key as an C<SV*> from the current position of the hash -iterator. The return value will always be a mortal copy of the key. Also -see C<hv_iterinit>. - - SV* hv_iterkeysv(HE* entry) - -=for hackers -Found in file hv.c - -=item hv_iternext -X<hv_iternext> - -Returns entries from a hash iterator. See C<hv_iterinit>. - -You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the -iterator currently points to, without losing your place or invalidating your -iterator. Note that in this case the current entry is deleted from the hash -with your iterator holding the last reference to it. Your iterator is flagged -to free the entry on the next call to C<hv_iternext>, so you must not discard -your iterator immediately else the entry will leak - call C<hv_iternext> to -trigger the resource deallocation. - - HE* hv_iternext(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_iternextsv -X<hv_iternextsv> - -Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one -operation. - - SV* hv_iternextsv(HV *hv, char **key, I32 *retlen) - -=for hackers -Found in file hv.c - -=item hv_iternext_flags -X<hv_iternext_flags> - -Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>. -The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is -set the placeholders keys (for restricted hashes) will be returned in addition -to normal keys. By default placeholders are automatically skipped over. -Currently a placeholder is implemented with a value that is -C<&PL_sv_placeholder>. Note that the implementation of placeholders and -restricted hashes may change, and the implementation currently is -insufficiently abstracted for any change to be tidy. - -NOTE: this function is experimental and may change or be -removed without notice. - - HE* hv_iternext_flags(HV *hv, I32 flags) - -=for hackers -Found in file hv.c - -=item hv_iterval -X<hv_iterval> - -Returns the value from the current position of the hash iterator. See -C<hv_iterkey>. - - SV* hv_iterval(HV *hv, HE *entry) - -=for hackers -Found in file hv.c - -=item hv_magic -X<hv_magic> - -Adds magic to a hash. See C<sv_magic>. - - void hv_magic(HV *hv, GV *gv, int how) - -=for hackers -Found in file hv.c - -=item hv_scalar -X<hv_scalar> - -Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied. - - SV* hv_scalar(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_store -X<hv_store> - -Stores an SV in a hash. The hash key is specified as C<key> and the -absolute value of C<klen> is the length of the key. If C<klen> is -negative the key is assumed to be in UTF-8-encoded Unicode. The -C<hash> parameter is the precomputed hash value; if it is zero then -Perl will compute it. - -The return value will be -NULL if the operation failed or if the value did not need to be actually -stored within the hash (as in the case of tied hashes). Otherwise it can -be dereferenced to get the original C<SV*>. Note that the caller is -responsible for suitably incrementing the reference count of C<val> before -the call, and decrementing it if the function returned NULL. Effectively -a successful hv_store takes ownership of one reference to C<val>. This is -usually what you want; a newly created SV has a reference count of one, so -if all your code does is create SVs then store them in a hash, hv_store -will own the only reference to the new SV, and your code doesn't need to do -anything further to tidy up. hv_store is not implemented as a call to -hv_store_ent, and does not create a temporary SV for the key, so if your -key data is not already in SV form then use hv_store in preference to -hv_store_ent. - -See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more -information on how to use this function on tied hashes. - - SV** hv_store(HV *hv, const char *key, I32 klen, - SV *val, U32 hash) - -=for hackers -Found in file hv.c - -=item hv_stores -X<hv_stores> - -Like C<hv_store>, 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<hv_store_ent> - -Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash> -parameter is the precomputed hash value; if it is zero then Perl will -compute it. The return value is the new hash entry so created. It will be -NULL if the operation failed or if the value did not need to be actually -stored within the hash (as in the case of tied hashes). Otherwise the -contents of the return value can be accessed using the C<He?> macros -described here. Note that the caller is responsible for suitably -incrementing the reference count of C<val> before the call, and -decrementing it if the function returned NULL. Effectively a successful -hv_store_ent takes ownership of one reference to C<val>. This is -usually what you want; a newly created SV has a reference count of one, so -if all your code does is create SVs then store them in a hash, hv_store -will own the only reference to the new SV, and your code doesn't need to do -anything further to tidy up. Note that hv_store_ent only reads the C<key>; -unlike C<val> it does not take ownership of it, so maintaining the correct -reference count on C<key> is entirely the caller's responsibility. hv_store -is not implemented as a call to hv_store_ent, and does not create a temporary -SV for the key, so if your key data is not already in SV form then use -hv_store in preference to hv_store_ent. - -See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more -information on how to use this function on tied hashes. - - HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash) - -=for hackers -Found in file hv.c - -=item hv_undef -X<hv_undef> - -Undefines the hash. The XS equivalent of C<undef(%hash)>. - -As well as freeing all the elements of the hash (like hv_clear()), this -also frees any auxiliary data and storage associated with the hash. - -If any destructors are triggered as a result, the hv itself may -be freed. - -See also L</hv_clear>. - - void hv_undef(HV *hv) - -=for hackers -Found in file hv.c - -=item newHV -X<newHV> - -Creates a new HV. The reference count is set to 1. - - HV* newHV() - -=for hackers -Found in file hv.h - - -=back - -=head1 Hook manipulation - -=over 8 - -=item wrap_op_checker -X<wrap_op_checker> - -Puts a C function into the chain of check functions for a specified op -type. This is the preferred way to manipulate the L</PL_check> array. -I<opcode> specifies which type of op is to be affected. I<new_checker> -is a pointer to the C function that is to be added to that opcode's -check chain, and I<old_checker_p> points to the storage location where a -pointer to the next function in the chain will be stored. The value of -I<new_pointer> is written into the L</PL_check> array, while the value -previously stored there is written to I<*old_checker_p>. - -L</PL_check> is global to an entire process, and a module wishing to -hook op checking may find itself invoked more than once per process, -typically in different threads. To handle that situation, this function -is idempotent. The location I<*old_checker_p> must initially (once -per process) contain a null pointer. A C variable of static duration -(declared at file scope, typically also marked C<static> to give -it internal linkage) will be implicitly initialised appropriately, -if it does not have an explicit initialiser. This function will only -actually modify the check chain if it finds I<*old_checker_p> to be null. -This function is also thread safe on the small scale. It uses appropriate -locking to avoid race conditions in accessing L</PL_check>. - -When this function is called, the function referenced by I<new_checker> -must be ready to be called, except for I<*old_checker_p> being unfilled. -In a threading situation, I<new_checker> may be called immediately, -even before this function has returned. I<*old_checker_p> will always -be appropriately set before I<new_checker> is called. If I<new_checker> -decides not to do anything special with an op that it is given (which -is the usual case for most uses of op check hooking), it must chain the -check function referenced by I<*old_checker_p>. - -If you want to influence compilation of calls to a specific subroutine, -then use L</cv_set_call_checker> rather than hooking checking of all -C<entersub> ops. - - void wrap_op_checker(Optype opcode, - Perl_check_t new_checker, - Perl_check_t *old_checker_p) - -=for hackers -Found in file op.c - - -=back - -=head1 Lexer interface - -=over 8 - -=item lex_bufutf8 -X<lex_bufutf8> - -Indicates whether the octets in the lexer buffer -(L</PL_parser-E<gt>linestr>) should be interpreted as the UTF-8 encoding -of Unicode characters. If not, they should be interpreted as Latin-1 -characters. This is analogous to the C<SvUTF8> flag for scalars. - -In UTF-8 mode, it is not guaranteed that the lexer buffer actually -contains valid UTF-8. Lexing code must be robust in the face of invalid -encoding. - -The actual C<SvUTF8> flag of the L</PL_parser-E<gt>linestr> scalar -is significant, but not the whole story regarding the input character -encoding. Normally, when a file is being read, the scalar contains octets -and its C<SvUTF8> flag is off, but the octets should be interpreted as -UTF-8 if the C<use utf8> pragma is in effect. During a string eval, -however, the scalar may have the C<SvUTF8> flag on, and in this case its -octets should be interpreted as UTF-8 unless the C<use bytes> pragma -is in effect. This logic may change in the future; use this function -instead of implementing the logic yourself. - -NOTE: this function is experimental and may change or be -removed without notice. - - bool lex_bufutf8() - -=for hackers -Found in file toke.c - -=item lex_discard_to -X<lex_discard_to> - -Discards the first part of the L</PL_parser-E<gt>linestr> buffer, -up to I<ptr>. The remaining content of the buffer will be moved, and -all pointers into the buffer updated appropriately. I<ptr> must not -be later in the buffer than the position of L</PL_parser-E<gt>bufptr>: -it is not permitted to discard text that has yet to be lexed. - -Normally it is not necessarily to do this directly, because it suffices to -use the implicit discarding behaviour of L</lex_next_chunk> and things -based on it. However, if a token stretches across multiple lines, -and the lexing code has kept multiple lines of text in the buffer for -that purpose, then after completion of the token it would be wise to -explicitly discard the now-unneeded earlier lines, to avoid future -multi-line tokens growing the buffer without bound. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_discard_to(char *ptr) - -=for hackers -Found in file toke.c - -=item lex_grow_linestr -X<lex_grow_linestr> - -Reallocates the lexer buffer (L</PL_parser-E<gt>linestr>) to accommodate -at least I<len> octets (including terminating NUL). Returns a -pointer to the reallocated buffer. This is necessary before making -any direct modification of the buffer that would increase its length. -L</lex_stuff_pvn> provides a more convenient way to insert text into -the buffer. - -Do not use C<SvGROW> or C<sv_grow> directly on C<PL_parser-E<gt>linestr>; -this function updates all of the lexer's variables that point directly -into the buffer. - -NOTE: this function is experimental and may change or be -removed without notice. - - char * lex_grow_linestr(STRLEN len) - -=for hackers -Found in file toke.c - -=item lex_next_chunk -X<lex_next_chunk> - -Reads in the next chunk of text to be lexed, appending it to -L</PL_parser-E<gt>linestr>. This should be called when lexing code has -looked to the end of the current chunk and wants to know more. It is -usual, but not necessary, for lexing to have consumed the entirety of -the current chunk at this time. - -If L</PL_parser-E<gt>bufptr> is pointing to the very end of the current -chunk (i.e., the current chunk has been entirely consumed), normally the -current chunk will be discarded at the same time that the new chunk is -read in. If I<flags> includes C<LEX_KEEP_PREVIOUS>, the current chunk -will not be discarded. If the current chunk has not been entirely -consumed, then it will not be discarded regardless of the flag. - -Returns true if some new text was added to the buffer, or false if the -buffer has reached the end of the input text. - -NOTE: this function is experimental and may change or be -removed without notice. - - bool lex_next_chunk(U32 flags) - -=for hackers -Found in file toke.c - -=item lex_peek_unichar -X<lex_peek_unichar> - -Looks ahead one (Unicode) character in the text currently being lexed. -Returns the codepoint (unsigned integer value) of the next character, -or -1 if lexing has reached the end of the input text. To consume the -peeked character, use L</lex_read_unichar>. - -If the next character is in (or extends into) the next chunk of input -text, the next chunk will be read in. Normally the current chunk will be -discarded at the same time, but if I<flags> includes C<LEX_KEEP_PREVIOUS> -then the current chunk will not be discarded. - -If the input is being interpreted as UTF-8 and a UTF-8 encoding error -is encountered, an exception is generated. - -NOTE: this function is experimental and may change or be -removed without notice. - - I32 lex_peek_unichar(U32 flags) - -=for hackers -Found in file toke.c - -=item lex_read_space -X<lex_read_space> - -Reads optional spaces, in Perl style, in the text currently being -lexed. The spaces may include ordinary whitespace characters and -Perl-style comments. C<#line> directives are processed if encountered. -L</PL_parser-E<gt>bufptr> is moved past the spaces, so that it points -at a non-space character (or the end of the input text). - -If spaces extend into the next chunk of input text, the next chunk will -be read in. Normally the current chunk will be discarded at the same -time, but if I<flags> includes C<LEX_KEEP_PREVIOUS> then the current -chunk will not be discarded. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_read_space(U32 flags) - -=for hackers -Found in file toke.c - -=item lex_read_to -X<lex_read_to> - -Consume text in the lexer buffer, from L</PL_parser-E<gt>bufptr> up -to I<ptr>. This advances L</PL_parser-E<gt>bufptr> to match I<ptr>, -performing the correct bookkeeping whenever a newline character is passed. -This is the normal way to consume lexed text. - -Interpretation of the buffer's octets can be abstracted out by -using the slightly higher-level functions L</lex_peek_unichar> and -L</lex_read_unichar>. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_read_to(char *ptr) - -=for hackers -Found in file toke.c - -=item lex_read_unichar -X<lex_read_unichar> - -Reads the next (Unicode) character in the text currently being lexed. -Returns the codepoint (unsigned integer value) of the character read, -and moves L</PL_parser-E<gt>bufptr> past the character, or returns -1 -if lexing has reached the end of the input text. To non-destructively -examine the next character, use L</lex_peek_unichar> instead. - -If the next character is in (or extends into) the next chunk of input -text, the next chunk will be read in. Normally the current chunk will be -discarded at the same time, but if I<flags> includes C<LEX_KEEP_PREVIOUS> -then the current chunk will not be discarded. - -If the input is being interpreted as UTF-8 and a UTF-8 encoding error -is encountered, an exception is generated. - -NOTE: this function is experimental and may change or be -removed without notice. - - I32 lex_read_unichar(U32 flags) - -=for hackers -Found in file toke.c - -=item lex_start -X<lex_start> - -Creates and initialises a new lexer/parser state object, supplying -a context in which to lex and parse from a new source of Perl code. -A pointer to the new state object is placed in L</PL_parser>. An entry -is made on the save stack so that upon unwinding the new state object -will be destroyed and the former value of L</PL_parser> will be restored. -Nothing else need be done to clean up the parsing context. - -The code to be parsed comes from I<line> and I<rsfp>. I<line>, if -non-null, provides a string (in SV form) containing code to be parsed. -A copy of the string is made, so subsequent modification of I<line> -does not affect parsing. I<rsfp>, if non-null, provides an input stream -from which code will be read to be parsed. If both are non-null, the -code in I<line> comes first and must consist of complete lines of input, -and I<rsfp> supplies the remainder of the source. - -The I<flags> parameter is reserved for future use. Currently it is only -used by perl internally, so extensions should always pass zero. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_start(SV *line, PerlIO *rsfp, U32 flags) - -=for hackers -Found in file toke.c - -=item lex_stuff_pv -X<lex_stuff_pv> - -Insert characters into the lexer buffer (L</PL_parser-E<gt>linestr>), -immediately after the current lexing point (L</PL_parser-E<gt>bufptr>), -reallocating the buffer if necessary. This means that lexing code that -runs later will see the characters as if they had appeared in the input. -It is not recommended to do this as part of normal parsing, and most -uses of this facility run the risk of the inserted characters being -interpreted in an unintended manner. - -The string to be inserted is represented by octets starting at I<pv> -and continuing to the first nul. These octets are interpreted as either -UTF-8 or Latin-1, according to whether the C<LEX_STUFF_UTF8> flag is set -in I<flags>. The characters are recoded for the lexer buffer, according -to how the buffer is currently being interpreted (L</lex_bufutf8>). -If it is not convenient to nul-terminate a string to be inserted, the -L</lex_stuff_pvn> function is more appropriate. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_stuff_pv(const char *pv, U32 flags) - -=for hackers -Found in file toke.c - -=item lex_stuff_pvn -X<lex_stuff_pvn> - -Insert characters into the lexer buffer (L</PL_parser-E<gt>linestr>), -immediately after the current lexing point (L</PL_parser-E<gt>bufptr>), -reallocating the buffer if necessary. This means that lexing code that -runs later will see the characters as if they had appeared in the input. -It is not recommended to do this as part of normal parsing, and most -uses of this facility run the risk of the inserted characters being -interpreted in an unintended manner. - -The string to be inserted is represented by I<len> octets starting -at I<pv>. These octets are interpreted as either UTF-8 or Latin-1, -according to whether the C<LEX_STUFF_UTF8> flag is set in I<flags>. -The characters are recoded for the lexer buffer, according to how the -buffer is currently being interpreted (L</lex_bufutf8>). If a string -to be inserted is available as a Perl scalar, the L</lex_stuff_sv> -function is more convenient. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_stuff_pvn(const char *pv, STRLEN len, - U32 flags) - -=for hackers -Found in file toke.c - -=item lex_stuff_pvs -X<lex_stuff_pvs> - -Like L</lex_stuff_pvn>, but takes a literal string instead of a -string/length pair. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_stuff_pvs(const char *pv, U32 flags) - -=for hackers -Found in file handy.h - -=item lex_stuff_sv -X<lex_stuff_sv> - -Insert characters into the lexer buffer (L</PL_parser-E<gt>linestr>), -immediately after the current lexing point (L</PL_parser-E<gt>bufptr>), -reallocating the buffer if necessary. This means that lexing code that -runs later will see the characters as if they had appeared in the input. -It is not recommended to do this as part of normal parsing, and most -uses of this facility run the risk of the inserted characters being -interpreted in an unintended manner. - -The string to be inserted is the string value of I<sv>. The characters -are recoded for the lexer buffer, according to how the buffer is currently -being interpreted (L</lex_bufutf8>). If a string to be inserted is -not already a Perl scalar, the L</lex_stuff_pvn> function avoids the -need to construct a scalar. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_stuff_sv(SV *sv, U32 flags) - -=for hackers -Found in file toke.c - -=item lex_unstuff -X<lex_unstuff> - -Discards text about to be lexed, from L</PL_parser-E<gt>bufptr> up to -I<ptr>. Text following I<ptr> will be moved, and the buffer shortened. -This hides the discarded text from any lexing code that runs later, -as if the text had never appeared. - -This is not the normal way to consume lexed text. For that, use -L</lex_read_to>. - -NOTE: this function is experimental and may change or be -removed without notice. - - void lex_unstuff(char *ptr) - -=for hackers -Found in file toke.c - -=item parse_arithexpr -X<parse_arithexpr> - -Parse a Perl arithmetic expression. This may contain operators of precedence -down to the bit shift operators. The expression must be followed (and thus -terminated) either by a comparison or lower-precedence operator or by -something that would normally terminate an expression such as semicolon. -If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional, -otherwise it is mandatory. It is up to the caller to ensure that the -dynamic parser state (L</PL_parser> et al) is correctly set to reflect -the source of the code to be parsed and the lexical context for the -expression. - -The op tree representing the expression is returned. If an optional -expression is absent, a null pointer is returned, otherwise the pointer -will be non-null. - -If an error occurs in parsing or compilation, in most cases a valid op -tree is returned anyway. The error is reflected in the parser state, -normally resulting in a single exception at the top level of parsing -which covers all the compilation errors that occurred. Some compilation -errors, however, will throw an exception immediately. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_arithexpr(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_barestmt -X<parse_barestmt> - -Parse a single unadorned Perl statement. This may be a normal imperative -statement or a declaration that has compile-time effect. It does not -include any label or other affixture. It is up to the caller to ensure -that the dynamic parser state (L</PL_parser> et al) is correctly set to -reflect the source of the code to be parsed and the lexical context for -the statement. - -The op tree representing the statement is returned. This may be a -null pointer if the statement is null, for example if it was actually -a subroutine definition (which has compile-time side effects). If not -null, it will be ops directly implementing the statement, suitable to -pass to L</newSTATEOP>. It will not normally include a C<nextstate> or -equivalent op (except for those embedded in a scope contained entirely -within the statement). - -If an error occurs in parsing or compilation, in most cases a valid op -tree (most likely null) is returned anyway. The error is reflected in -the parser state, normally resulting in a single exception at the top -level of parsing which covers all the compilation errors that occurred. -Some compilation errors, however, will throw an exception immediately. - -The I<flags> parameter is reserved for future use, and must always -be zero. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_barestmt(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_block -X<parse_block> - -Parse a single complete Perl code block. This consists of an opening -brace, a sequence of statements, and a closing brace. The block -constitutes a lexical scope, so C<my> variables and various compile-time -effects can be contained within it. It is up to the caller to ensure -that the dynamic parser state (L</PL_parser> et al) is correctly set to -reflect the source of the code to be parsed and the lexical context for -the statement. - -The op tree representing the code block is returned. This is always a -real op, never a null pointer. It will normally be a C<lineseq> list, -including C<nextstate> or equivalent ops. No ops to construct any kind -of runtime scope are included by virtue of it being a block. - -If an error occurs in parsing or compilation, in most cases a valid op -tree (most likely null) is returned anyway. The error is reflected in -the parser state, normally resulting in a single exception at the top -level of parsing which covers all the compilation errors that occurred. -Some compilation errors, however, will throw an exception immediately. - -The I<flags> parameter is reserved for future use, and must always -be zero. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_block(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_fullexpr -X<parse_fullexpr> - -Parse a single complete Perl expression. This allows the full -expression grammar, including the lowest-precedence operators such -as C<or>. The expression must be followed (and thus terminated) by a -token that an expression would normally be terminated by: end-of-file, -closing bracketing punctuation, semicolon, or one of the keywords that -signals a postfix expression-statement modifier. If I<flags> includes -C<PARSE_OPTIONAL> then the expression is optional, otherwise it is -mandatory. It is up to the caller to ensure that the dynamic parser -state (L</PL_parser> et al) is correctly set to reflect the source of -the code to be parsed and the lexical context for the expression. - -The op tree representing the expression is returned. If an optional -expression is absent, a null pointer is returned, otherwise the pointer -will be non-null. - -If an error occurs in parsing or compilation, in most cases a valid op -tree is returned anyway. The error is reflected in the parser state, -normally resulting in a single exception at the top level of parsing -which covers all the compilation errors that occurred. Some compilation -errors, however, will throw an exception immediately. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_fullexpr(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_fullstmt -X<parse_fullstmt> - -Parse a single complete Perl statement. This may be a normal imperative -statement or a declaration that has compile-time effect, and may include -optional labels. It is up to the caller to ensure that the dynamic -parser state (L</PL_parser> et al) is correctly set to reflect the source -of the code to be parsed and the lexical context for the statement. - -The op tree representing the statement is returned. This may be a -null pointer if the statement is null, for example if it was actually -a subroutine definition (which has compile-time side effects). If not -null, it will be the result of a L</newSTATEOP> call, normally including -a C<nextstate> or equivalent op. - -If an error occurs in parsing or compilation, in most cases a valid op -tree (most likely null) is returned anyway. The error is reflected in -the parser state, normally resulting in a single exception at the top -level of parsing which covers all the compilation errors that occurred. -Some compilation errors, however, will throw an exception immediately. - -The I<flags> parameter is reserved for future use, and must always -be zero. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_fullstmt(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_label -X<parse_label> - -Parse a single label, possibly optional, of the type that may prefix a -Perl statement. It is up to the caller to ensure that the dynamic parser -state (L</PL_parser> et al) is correctly set to reflect the source of -the code to be parsed. If I<flags> includes C<PARSE_OPTIONAL> then the -label is optional, otherwise it is mandatory. - -The name of the label is returned in the form of a fresh scalar. If an -optional label is absent, a null pointer is returned. - -If an error occurs in parsing, which can only occur if the label is -mandatory, a valid label is returned anyway. The error is reflected in -the parser state, normally resulting in a single exception at the top -level of parsing which covers all the compilation errors that occurred. - -NOTE: this function is experimental and may change or be -removed without notice. - - SV * parse_label(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_listexpr -X<parse_listexpr> - -Parse a Perl list expression. This may contain operators of precedence -down to the comma operator. The expression must be followed (and thus -terminated) either by a low-precedence logic operator such as C<or> or by -something that would normally terminate an expression such as semicolon. -If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional, -otherwise it is mandatory. It is up to the caller to ensure that the -dynamic parser state (L</PL_parser> et al) is correctly set to reflect -the source of the code to be parsed and the lexical context for the -expression. - -The op tree representing the expression is returned. If an optional -expression is absent, a null pointer is returned, otherwise the pointer -will be non-null. - -If an error occurs in parsing or compilation, in most cases a valid op -tree is returned anyway. The error is reflected in the parser state, -normally resulting in a single exception at the top level of parsing -which covers all the compilation errors that occurred. Some compilation -errors, however, will throw an exception immediately. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_listexpr(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_stmtseq -X<parse_stmtseq> - -Parse a sequence of zero or more Perl statements. These may be normal -imperative statements, including optional labels, or declarations -that have compile-time effect, or any mixture thereof. The statement -sequence ends when a closing brace or end-of-file is encountered in a -place where a new statement could have validly started. It is up to -the caller to ensure that the dynamic parser state (L</PL_parser> et al) -is correctly set to reflect the source of the code to be parsed and the -lexical context for the statements. - -The op tree representing the statement sequence is returned. This may -be a null pointer if the statements were all null, for example if there -were no statements or if there were only subroutine definitions (which -have compile-time side effects). If not null, it will be a C<lineseq> -list, normally including C<nextstate> or equivalent ops. - -If an error occurs in parsing or compilation, in most cases a valid op -tree is returned anyway. The error is reflected in the parser state, -normally resulting in a single exception at the top level of parsing -which covers all the compilation errors that occurred. Some compilation -errors, however, will throw an exception immediately. - -The I<flags> parameter is reserved for future use, and must always -be zero. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_stmtseq(U32 flags) - -=for hackers -Found in file toke.c - -=item parse_termexpr -X<parse_termexpr> - -Parse a Perl term expression. This may contain operators of precedence -down to the assignment operators. The expression must be followed (and thus -terminated) either by a comma or lower-precedence operator or by -something that would normally terminate an expression such as semicolon. -If I<flags> includes C<PARSE_OPTIONAL> then the expression is optional, -otherwise it is mandatory. It is up to the caller to ensure that the -dynamic parser state (L</PL_parser> et al) is correctly set to reflect -the source of the code to be parsed and the lexical context for the -expression. - -The op tree representing the expression is returned. If an optional -expression is absent, a null pointer is returned, otherwise the pointer -will be non-null. - -If an error occurs in parsing or compilation, in most cases a valid op -tree is returned anyway. The error is reflected in the parser state, -normally resulting in a single exception at the top level of parsing -which covers all the compilation errors that occurred. Some compilation -errors, however, will throw an exception immediately. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * parse_termexpr(U32 flags) - -=for hackers -Found in file toke.c - -=item PL_parser -X<PL_parser> - -Pointer to a structure encapsulating the state of the parsing operation -currently in progress. The pointer can be locally changed to perform -a nested parse without interfering with the state of an outer parse. -Individual members of C<PL_parser> have their own documentation. - -=for hackers -Found in file toke.c - -=item PL_parser-E<gt>bufend -X<PL_parser-E<gt>bufend> - -Direct pointer to the end of the chunk of text currently being lexed, the -end of the lexer buffer. This is equal to C<SvPVX(PL_parser-E<gt>linestr) -+ SvCUR(PL_parser-E<gt>linestr)>. A NUL character (zero octet) is -always located at the end of the buffer, and does not count as part of -the buffer's contents. - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file toke.c - -=item PL_parser-E<gt>bufptr -X<PL_parser-E<gt>bufptr> - -Points to the current position of lexing inside the lexer buffer. -Characters around this point may be freely examined, within -the range delimited by C<SvPVX(L</PL_parser-E<gt>linestr>)> and -L</PL_parser-E<gt>bufend>. The octets of the buffer may be intended to be -interpreted as either UTF-8 or Latin-1, as indicated by L</lex_bufutf8>. - -Lexing code (whether in the Perl core or not) moves this pointer past -the characters that it consumes. It is also expected to perform some -bookkeeping whenever a newline character is consumed. This movement -can be more conveniently performed by the function L</lex_read_to>, -which handles newlines appropriately. - -Interpretation of the buffer's octets can be abstracted out by -using the slightly higher-level functions L</lex_peek_unichar> and -L</lex_read_unichar>. - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file toke.c - -=item PL_parser-E<gt>linestart -X<PL_parser-E<gt>linestart> - -Points to the start of the current line inside the lexer buffer. -This is useful for indicating at which column an error occurred, and -not much else. This must be updated by any lexing code that consumes -a newline; the function L</lex_read_to> handles this detail. - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file toke.c - -=item PL_parser-E<gt>linestr -X<PL_parser-E<gt>linestr> - -Buffer scalar containing the chunk currently under consideration of the -text currently being lexed. This is always a plain string scalar (for -which C<SvPOK> is true). It is not intended to be used as a scalar by -normal scalar means; instead refer to the buffer directly by the pointer -variables described below. - -The lexer maintains various C<char*> pointers to things in the -C<PL_parser-E<gt>linestr> buffer. If C<PL_parser-E<gt>linestr> is ever -reallocated, all of these pointers must be updated. Don't attempt to -do this manually, but rather use L</lex_grow_linestr> if you need to -reallocate the buffer. - -The content of the text chunk in the buffer is commonly exactly one -complete line of input, up to and including a newline terminator, -but there are situations where it is otherwise. The octets of the -buffer may be intended to be interpreted as either UTF-8 or Latin-1. -The function L</lex_bufutf8> tells you which. Do not use the C<SvUTF8> -flag on this scalar, which may disagree with it. - -For direct examination of the buffer, the variable -L</PL_parser-E<gt>bufend> points to the end of the buffer. The current -lexing position is pointed to by L</PL_parser-E<gt>bufptr>. Direct use -of these pointers is usually preferable to examination of the scalar -through normal scalar means. - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file toke.c - - -=back - -=head1 Magical Functions - -=over 8 - -=item mg_clear -X<mg_clear> - -Clear something magical that the SV represents. See C<sv_magic>. - - int mg_clear(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_copy -X<mg_copy> - -Copies the magic from one SV to another. See C<sv_magic>. - - int mg_copy(SV *sv, SV *nsv, const char *key, - I32 klen) - -=for hackers -Found in file mg.c - -=item mg_find -X<mg_find> - -Finds the magic pointer for type matching the SV. See C<sv_magic>. - - MAGIC* mg_find(const SV* sv, int type) - -=for hackers -Found in file mg.c - -=item mg_findext -X<mg_findext> - -Finds the magic pointer of C<type> with the given C<vtbl> for the C<SV>. See -C<sv_magicext>. - - MAGIC* mg_findext(const SV* sv, int type, - const MGVTBL *vtbl) - -=for hackers -Found in file mg.c - -=item mg_free -X<mg_free> - -Free any magic storage used by the SV. See C<sv_magic>. - - int mg_free(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_free_type -X<mg_free_type> - -Remove any magic of type I<how> from the SV I<sv>. See L</sv_magic>. - - void mg_free_type(SV *sv, int how) - -=for hackers -Found in file mg.c - -=item mg_get -X<mg_get> - -Do magic before a value is retrieved from the SV. See C<sv_magic>. - - int mg_get(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_length -X<mg_length> - -Report on the SV's length. See C<sv_magic>. - - U32 mg_length(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_magical -X<mg_magical> - -Turns on the magical status of an SV. See C<sv_magic>. - - void mg_magical(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_set -X<mg_set> - -Do magic after a value is assigned to the SV. See C<sv_magic>. - - int mg_set(SV* sv) - -=for hackers -Found in file mg.c - -=item SvGETMAGIC -X<SvGETMAGIC> - -Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its -argument more than once. - - void SvGETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvLOCK -X<SvLOCK> - -Arranges for a mutual exclusion lock to be obtained on sv if a suitable module -has been loaded. - - void SvLOCK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSETMAGIC -X<SvSETMAGIC> - -Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its -argument more than once. - - void SvSETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSetMagicSV -X<SvSetMagicSV> - -Like C<SvSetSV>, but does any set magic required afterwards. - - void SvSetMagicSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetMagicSV_nosteal -X<SvSetMagicSV_nosteal> - -Like C<SvSetSV_nosteal>, but does any set magic required afterwards. - - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV -X<SvSetSV> - -Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments -more than once. - - void SvSetSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV_nosteal -X<SvSetSV_nosteal> - -Calls a non-destructive version of C<sv_setsv> if dsv is not the same as -ssv. May evaluate arguments more than once. - - void SvSetSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSHARE -X<SvSHARE> - -Arranges for sv to be shared between threads if a suitable module -has been loaded. - - void SvSHARE(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUNLOCK -X<SvUNLOCK> - -Releases a mutual exclusion lock on sv if a suitable module -has been loaded. - - void SvUNLOCK(SV* sv) - -=for hackers -Found in file sv.h - - -=back - -=head1 Memory Management - -=over 8 - -=item Copy -X<Copy> - -The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the -source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is -the type. May fail on overlapping copies. See also C<Move>. - - void Copy(void* src, void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item CopyD -X<CopyD> - -Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call -optimise. - - void * CopyD(void* src, void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item Move -X<Move> - -The XSUB-writer's interface to the C C<memmove> function. The C<src> is the -source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is -the type. Can do overlapping moves. See also C<Copy>. - - void Move(void* src, void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item MoveD -X<MoveD> - -Like C<Move> but returns dest. Useful for encouraging compilers to tail-call -optimise. - - void * MoveD(void* src, void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item Newx -X<Newx> - -The XSUB-writer's interface to the C C<malloc> function. - -In 5.9.3, Newx() and friends replace the older New() API, and drops -the first parameter, I<x>, a debug aid which allowed callers to identify -themselves. This aid has been superseded by a new build option, -PERL_MEM_LOG (see L<perlhacktips/PERL_MEM_LOG>). 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 Newxc -X<Newxc> - -The XSUB-writer's interface to the C C<malloc> function, with -cast. See also C<Newx>. - - void Newxc(void* ptr, int nitems, type, cast) - -=for hackers -Found in file handy.h - -=item Newxz -X<Newxz> - -The XSUB-writer's interface to the C C<malloc> function. The allocated -memory is zeroed with C<memzero>. See also C<Newx>. - - void Newxz(void* ptr, int nitems, type) - -=for hackers -Found in file handy.h - -=item Poison -X<Poison> - -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<PoisonFree> - -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<PoisonNew> - -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<PoisonWith> - -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<Renew> - -The XSUB-writer's interface to the C C<realloc> function. - - void Renew(void* ptr, int nitems, type) - -=for hackers -Found in file handy.h - -=item Renewc -X<Renewc> - -The XSUB-writer's interface to the C C<realloc> function, with -cast. - - void Renewc(void* ptr, int nitems, type, cast) - -=for hackers -Found in file handy.h - -=item Safefree -X<Safefree> - -The XSUB-writer's interface to the C C<free> function. - - void Safefree(void* ptr) - -=for hackers -Found in file handy.h - -=item savepv -X<savepv> - -Perl's version of C<strdup()>. Returns a pointer to a newly allocated -string which is a duplicate of C<pv>. The size of the string is -determined by C<strlen()>. The memory allocated for the new string can -be freed with the C<Safefree()> function. - - char* savepv(const char* pv) - -=for hackers -Found in file util.c - -=item savepvn -X<savepvn> - -Perl's version of what C<strndup()> would be if it existed. Returns a -pointer to a newly allocated string which is a duplicate of the first -C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for -the new string can be freed with the C<Safefree()> function. - - char* savepvn(const char* pv, I32 len) - -=for hackers -Found in file util.c - -=item savepvs -X<savepvs> - -Like C<savepvn>, 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<savesharedpv> - -A version of C<savepv()> which allocates the duplicate string in memory -which is shared between threads. - - char* savesharedpv(const char* pv) - -=for hackers -Found in file util.c - -=item savesharedpvn -X<savesharedpvn> - -A version of C<savepvn()> which allocates the duplicate string in memory -which is shared between threads. (With the specific difference that a NULL -pointer is not acceptable) - - char* savesharedpvn(const char *const pv, - const STRLEN len) - -=for hackers -Found in file util.c - -=item savesharedpvs -X<savesharedpvs> - -A version of C<savepvs()> which allocates the duplicate string in memory -which is shared between threads. - - char* savesharedpvs(const char* s) - -=for hackers -Found in file handy.h - -=item savesharedsvpv -X<savesharedsvpv> - -A version of C<savesharedpv()> which allocates the duplicate string in -memory which is shared between threads. - - char* savesharedsvpv(SV *sv) - -=for hackers -Found in file util.c - -=item savesvpv -X<savesvpv> - -A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from -the passed in SV using C<SvPV()> - - char* savesvpv(SV* sv) - -=for hackers -Found in file util.c - -=item StructCopy -X<StructCopy> - -This is an architecture-independent macro to copy one structure to another. - - void StructCopy(type src, type dest, type) - -=for hackers -Found in file handy.h - -=item Zero -X<Zero> - -The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the -destination, C<nitems> is the number of items, and C<type> is the type. - - void Zero(void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item ZeroD -X<ZeroD> - -Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call -optimise. - - void * ZeroD(void* dest, int nitems, type) - -=for hackers -Found in file handy.h - - -=back - -=head1 Miscellaneous Functions - -=over 8 - -=item fbm_compile -X<fbm_compile> - -Analyses the string in order to make fast searches on it using fbm_instr() --- the Boyer-Moore algorithm. - - void fbm_compile(SV* sv, U32 flags) - -=for hackers -Found in file util.c - -=item fbm_instr -X<fbm_instr> - -Returns the location of the SV in the string delimited by C<str> and -C<strend>. It returns C<NULL> if the string can't be found. The C<sv> -does not have to be fbm_compiled, but the search will not be as fast -then. - - char* fbm_instr(unsigned char* big, - unsigned char* bigend, SV* littlestr, - U32 flags) - -=for hackers -Found in file util.c - -=item foldEQ -X<foldEQ> - -Returns true if the leading len bytes of the strings s1 and s2 are the same -case-insensitively; false otherwise. Uppercase and lowercase ASCII range bytes -match themselves and their opposite case counterparts. Non-cased and non-ASCII -range bytes match only themselves. - - I32 foldEQ(const char* a, const char* b, I32 len) - -=for hackers -Found in file util.c - -=item foldEQ_locale -X<foldEQ_locale> - -Returns true if the leading len bytes of the strings s1 and s2 are the same -case-insensitively in the current locale; false otherwise. - - I32 foldEQ_locale(const char* a, const char* b, - I32 len) - -=for hackers -Found in file util.c - -=item form -X<form> - -Takes a sprintf-style format pattern and conventional -(non-SV) arguments and returns the formatted string. - - (char *) Perl_form(pTHX_ const char* pat, ...) - -can be used any place a string (char *) is required: - - char * s = Perl_form("%d.%d",major,minor); - -Uses a single private buffer so if you want to format several strings you -must explicitly copy the earlier strings away (and free the copies when you -are done). - - char* form(const char* pat, ...) - -=for hackers -Found in file util.c - -=item getcwd_sv -X<getcwd_sv> - -Fill the sv with current working directory - - int getcwd_sv(SV* sv) - -=for hackers -Found in file util.c - -=item mess -X<mess> - -Take a sprintf-style format pattern and argument list. These are used to -generate a string message. If the message does not end with a newline, -then it will be extended with some indication of the current location -in the code, as described for L</mess_sv>. - -Normally, the resulting message is returned in a new mortal SV. -During global destruction a single SV may be shared between uses of -this function. - - SV * mess(const char *pat, ...) - -=for hackers -Found in file util.c - -=item mess_sv -X<mess_sv> - -Expands a message, intended for the user, to include an indication of -the current location in the code, if the message does not already appear -to be complete. - -C<basemsg> is the initial message or object. If it is a reference, it -will be used as-is and will be the result of this function. Otherwise it -is used as a string, and if it already ends with a newline, it is taken -to be complete, and the result of this function will be the same string. -If the message does not end with a newline, then a segment such as C<at -foo.pl line 37> will be appended, and possibly other clauses indicating -the current state of execution. The resulting message will end with a -dot and a newline. - -Normally, the resulting message is returned in a new mortal SV. -During global destruction a single SV may be shared between uses of this -function. If C<consume> is true, then the function is permitted (but not -required) to modify and return C<basemsg> instead of allocating a new SV. - - SV * mess_sv(SV *basemsg, bool consume) - -=for hackers -Found in file util.c - -=item my_snprintf -X<my_snprintf> - -The C library C<snprintf> functionality, if available and -standards-compliant (uses C<vsnprintf>, actually). However, if the -C<vsnprintf> is not available, will unfortunately use the unsafe -C<vsprintf> which can overrun the buffer (there is an overrun check, -but that may be too late). Consider using C<sv_vcatpvf> instead, or -getting C<vsnprintf>. - - int my_snprintf(char *buffer, const Size_t len, - const char *format, ...) - -=for hackers -Found in file util.c - -=item my_sprintf -X<my_sprintf> - -The C library C<sprintf>, 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<sprintf>. - - int my_sprintf(char *buffer, const char *pat, ...) - -=for hackers -Found in file util.c - -=item my_vsnprintf -X<my_vsnprintf> - -The C library C<vsnprintf> if available and standards-compliant. -However, if if the C<vsnprintf> is not available, will unfortunately -use the unsafe C<vsprintf> which can overrun the buffer (there is an -overrun check, but that may be too late). Consider using -C<sv_vcatpvf> instead, or getting C<vsnprintf>. - - 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<new_version> - -Returns a new version object based on the passed in SV: - - SV *sv = new_version(SV *ver); - -Does not alter the passed in ver SV. See "upg_version" if you -want to upgrade the SV. - - SV* new_version(SV *ver) - -=for hackers -Found in file util.c - -=item prescan_version -X<prescan_version> - -Validate that a given string can be parsed as a version object, but doesn't -actually perform the parsing. Can use either strict or lax validation rules. -Can optionally set a number of hint variables to save the parsing code -some time when tokenizing. - - const char* prescan_version(const char *s, bool strict, - const char** errstr, - bool *sqv, - int *ssaw_decimal, - int *swidth, bool *salpha) - -=for hackers -Found in file util.c - -=item scan_version -X<scan_version> - -Returns a pointer to the next character after the parsed -version string, as well as upgrading the passed in SV to -an RV. - -Function must be called with an already existing SV like - - sv = newSV(0); - s = scan_version(s, SV *sv, bool qv); - -Performs some preprocessing to the string to ensure that -it has the correct characteristics of a version. Flags the -object if it contains an underscore (which denotes this -is an alpha version). The boolean qv denotes that the version -should be interpreted as if it had multiple decimals, even if -it doesn't. - - const char* scan_version(const char *s, SV *rv, bool qv) - -=for hackers -Found in file util.c - -=item strEQ -X<strEQ> - -Test two strings to see if they are equal. Returns true or false. - - bool strEQ(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strGE -X<strGE> - -Test two strings to see if the first, C<s1>, is greater than or equal to -the second, C<s2>. Returns true or false. - - bool strGE(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strGT -X<strGT> - -Test two strings to see if the first, C<s1>, is greater than the second, -C<s2>. Returns true or false. - - bool strGT(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strLE -X<strLE> - -Test two strings to see if the first, C<s1>, is less than or equal to the -second, C<s2>. Returns true or false. - - bool strLE(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strLT -X<strLT> - -Test two strings to see if the first, C<s1>, is less than the second, -C<s2>. Returns true or false. - - bool strLT(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strNE -X<strNE> - -Test two strings to see if they are different. Returns true or -false. - - bool strNE(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strnEQ -X<strnEQ> - -Test two strings to see if they are equal. The C<len> parameter indicates -the number of bytes to compare. Returns true or false. (A wrapper for -C<strncmp>). - - bool strnEQ(char* s1, char* s2, STRLEN len) - -=for hackers -Found in file handy.h - -=item strnNE -X<strnNE> - -Test two strings to see if they are different. The C<len> parameter -indicates the number of bytes to compare. Returns true or false. (A -wrapper for C<strncmp>). - - bool strnNE(char* s1, char* s2, STRLEN len) - -=for hackers -Found in file handy.h - -=item sv_destroyable -X<sv_destroyable> - -Dummy routine which reports that object can be destroyed when there is no -sharing module present. It ignores its single SV argument, and returns -'true'. Exists to avoid test for a NULL function pointer and because it -could potentially warn under some level of strict-ness. - - bool sv_destroyable(SV *sv) - -=for hackers -Found in file util.c - -=item sv_nosharing -X<sv_nosharing> - -Dummy routine which "shares" an SV when there is no sharing module present. -Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument. -Exists to avoid test for a NULL function pointer and because it could -potentially warn under some level of strict-ness. - - void sv_nosharing(SV *sv) - -=for hackers -Found in file util.c - -=item upg_version -X<upg_version> - -In-place upgrade of the supplied SV to a version object. - - SV *sv = upg_version(SV *sv, bool qv); - -Returns a pointer to the upgraded SV. Set the boolean qv if you want -to force this SV to be interpreted as an "extended" version. - - SV* upg_version(SV *ver, bool qv) - -=for hackers -Found in file util.c - -=item vcmp -X<vcmp> - -Version object aware cmp. Both operands must already have been -converted into version objects. - - int vcmp(SV *lhv, SV *rhv) - -=for hackers -Found in file util.c - -=item vmess -X<vmess> - -C<pat> and C<args> are a sprintf-style format pattern and encapsulated -argument list. These are used to generate a string message. If the -message does not end with a newline, then it will be extended with -some indication of the current location in the code, as described for -L</mess_sv>. - -Normally, the resulting message is returned in a new mortal SV. -During global destruction a single SV may be shared between uses of -this function. - - SV * vmess(const char *pat, va_list *args) - -=for hackers -Found in file util.c - -=item vnormal -X<vnormal> - -Accepts a version object and returns the normalized string -representation. Call like: - - sv = vnormal(rv); - -NOTE: you can pass either the object directly or the SV -contained within the RV. - -The SV returned has a refcount of 1. - - SV* vnormal(SV *vs) - -=for hackers -Found in file util.c - -=item vnumify -X<vnumify> - -Accepts a version object and returns the normalized floating -point representation. Call like: - - sv = vnumify(rv); - -NOTE: you can pass either the object directly or the SV -contained within the RV. - -The SV returned has a refcount of 1. - - SV* vnumify(SV *vs) - -=for hackers -Found in file util.c - -=item vstringify -X<vstringify> - -In order to maintain maximum compatibility with earlier versions -of Perl, this function will return either the floating point -notation or the multiple dotted notation, depending on whether -the original version contained 1 or more dots, respectively. - -The SV returned has a refcount of 1. - - SV* vstringify(SV *vs) - -=for hackers -Found in file util.c - -=item vverify -X<vverify> - -Validates that the SV contains valid internal structure for a version object. -It may be passed either the version object (RV) or the hash itself (HV). If -the structure is valid, it returns the HV. If the structure is invalid, -it returns NULL. - - SV *hv = vverify(sv); - -Note that it only confirms the bare minimum structure (so as not to get -confused by derived classes which may contain additional hash entries): - - SV* vverify(SV *vs) - -=for hackers -Found in file util.c - - -=back - -=head1 MRO Functions - -=over 8 - -=item mro_get_linear_isa -X<mro_get_linear_isa> - -Returns the mro linearisation for the given stash. By default, this -will be whatever C<mro_get_linear_isa_dfs> returns unless some -other MRO is in effect for the stash. The return value is a -read-only AV*. - -You are responsible for C<SvREFCNT_inc()> on the -return value if you plan to store it anywhere -semi-permanently (otherwise it might be deleted -out from under you the next time the cache is -invalidated). - - AV* mro_get_linear_isa(HV* stash) - -=for hackers -Found in file mro.c - -=item mro_method_changed_in -X<mro_method_changed_in> - -Invalidates method caching on any child classes -of the given stash, so that they might notice -the changes in this one. - -Ideally, all instances of C<PL_sub_generation++> in -perl source outside of F<mro.c> should be -replaced by calls to this. - -Perl automatically handles most of the common -ways a method might be redefined. However, there -are a few ways you could change a method in a stash -without the cache code noticing, in which case you -need to call this method afterwards: - -1) Directly manipulating the stash HV entries from -XS code. - -2) Assigning a reference to a readonly scalar -constant into a stash entry in order to create -a constant subroutine (like constant.pm -does). - -This same method is available from pure perl -via, C<mro::method_changed_in(classname)>. - - void mro_method_changed_in(HV* stash) - -=for hackers -Found in file mro.c - -=item mro_register -X<mro_register> - -Registers a custom mro plugin. See L<perlmroapi> for details. - - void mro_register(const struct mro_alg *mro) - -=for hackers -Found in file mro.c - - -=back - -=head1 Multicall Functions - -=over 8 - -=item dMULTICALL -X<dMULTICALL> - -Declare local variables for a multicall. See L<perlcall/LIGHTWEIGHT CALLBACKS>. - - dMULTICALL; - -=for hackers -Found in file cop.h - -=item MULTICALL -X<MULTICALL> - -Make a lightweight callback. See L<perlcall/LIGHTWEIGHT CALLBACKS>. - - MULTICALL; - -=for hackers -Found in file cop.h - -=item POP_MULTICALL -X<POP_MULTICALL> - -Closing bracket for a lightweight callback. -See L<perlcall/LIGHTWEIGHT CALLBACKS>. - - POP_MULTICALL; - -=for hackers -Found in file cop.h - -=item PUSH_MULTICALL -X<PUSH_MULTICALL> - -Opening bracket for a lightweight callback. -See L<perlcall/LIGHTWEIGHT CALLBACKS>. - - PUSH_MULTICALL; - -=for hackers -Found in file cop.h - - -=back - -=head1 Numeric functions - -=over 8 - -=item grok_bin -X<grok_bin> - -converts a string representing a binary number to numeric form. - -On entry I<start> and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I<result> should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first invalid character. -Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an -invalid character will also trigger a warning. -On return I<*len> is set to the length of the scanned string, -and I<*flags> gives output flags. - -If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear, -and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin> -returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags, -and writes the value to I<*result> (or the value is discarded if I<result> -is NULL). - -The binary number may optionally be prefixed with "0b" or "b" unless -C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If -C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary -number may use '_' characters to separate digits. - - UV grok_bin(const char* start, STRLEN* len_p, - I32* flags, NV *result) - -=for hackers -Found in file numeric.c - -=item grok_hex -X<grok_hex> - -converts a string representing a hex number to numeric form. - -On entry I<start> and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I<result> should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first invalid character. -Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an -invalid character will also trigger a warning. -On return I<*len> is set to the length of the scanned string, -and I<*flags> gives output flags. - -If the value is <= UV_MAX it is returned as a UV, the output flags are clear, -and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex> -returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags, -and writes the value to I<*result> (or the value is discarded if I<result> -is NULL). - -The hex number may optionally be prefixed with "0x" or "x" unless -C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If -C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex -number may use '_' characters to separate digits. - - UV grok_hex(const char* start, STRLEN* len_p, - I32* flags, NV *result) - -=for hackers -Found in file numeric.c - -=item grok_number -X<grok_number> - -Recognise (or not) a number. The type of the number is returned -(0 if unrecognised), otherwise it is a bit-ORed combination of -IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT, -IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h). - -If the value of the number can fit an in UV, it is returned in the *valuep -IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV -will never be set unless *valuep is valid, but *valuep may have been assigned -to during processing even though IS_NUMBER_IN_UV is not set on return. -If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when -valuep is non-NULL, but no actual assignment (or SEGV) will occur. - -IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were -seen (in which case *valuep gives the true value truncated to an integer), and -IS_NUMBER_NEG if the number is negative (in which case *valuep holds the -absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the -number is larger than a UV. - - int grok_number(const char *pv, STRLEN len, - UV *valuep) - -=for hackers -Found in file numeric.c - -=item grok_numeric_radix -X<grok_numeric_radix> - -Scan and skip for a numeric decimal separator (radix). - - bool grok_numeric_radix(const char **sp, - const char *send) - -=for hackers -Found in file numeric.c - -=item grok_oct -X<grok_oct> - -converts a string representing an octal number to numeric form. - -On entry I<start> and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I<result> should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first invalid character. -Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an -8 or 9 will also trigger a warning. -On return I<*len> is set to the length of the scanned string, -and I<*flags> gives output flags. - -If the value is <= UV_MAX it is returned as a UV, the output flags are clear, -and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct> -returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags, -and writes the value to I<*result> (or the value is discarded if I<result> -is NULL). - -If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal -number may use '_' characters to separate digits. - - UV grok_oct(const char* start, STRLEN* len_p, - I32* flags, NV *result) - -=for hackers -Found in file numeric.c - -=item Perl_signbit -X<Perl_signbit> - -Return a non-zero integer if the sign bit on an NV is set, and 0 if -it is not. - -If Configure detects this system has a signbit() that will work with -our NVs, then we just use it via the #define in perl.h. Otherwise, -fall back on this implementation. As a first pass, this gets everything -right except -0.0. Alas, catching -0.0 is the main use for this function, -so this is not too helpful yet. Still, at least we have the scaffolding -in place to support other systems, should that prove useful. - - -Configure notes: This function is called 'Perl_signbit' instead of a -plain 'signbit' because it is easy to imagine a system having a signbit() -function or macro that doesn't happen to work with our particular choice -of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect -the standard system headers to be happy. Also, this is a no-context -function (no pTHX_) because Perl_signbit() is usually re-#defined in -perl.h as a simple macro call to the system's signbit(). -Users should just always call Perl_signbit(). - -NOTE: this function is experimental and may change or be -removed without notice. - - int Perl_signbit(NV f) - -=for hackers -Found in file numeric.c - -=item scan_bin -X<scan_bin> - -For backwards compatibility. Use C<grok_bin> instead. - - NV scan_bin(const char* start, STRLEN len, - STRLEN* retlen) - -=for hackers -Found in file numeric.c - -=item scan_hex -X<scan_hex> - -For backwards compatibility. Use C<grok_hex> instead. - - NV scan_hex(const char* start, STRLEN len, - STRLEN* retlen) - -=for hackers -Found in file numeric.c - -=item scan_oct -X<scan_oct> - -For backwards compatibility. Use C<grok_oct> instead. - - NV scan_oct(const char* start, STRLEN len, - STRLEN* retlen) - -=for hackers -Found in file numeric.c - - -=back - -=head1 Optree construction - -=over 8 - -=item newASSIGNOP -X<newASSIGNOP> - -Constructs, checks, and returns an assignment op. I<left> and I<right> -supply the parameters of the assignment; they are consumed by this -function and become part of the constructed op tree. - -If I<optype> is C<OP_ANDASSIGN>, C<OP_ORASSIGN>, or C<OP_DORASSIGN>, then -a suitable conditional optree is constructed. If I<optype> is the opcode -of a binary operator, such as C<OP_BIT_OR>, then an op is constructed that -performs the binary operation and assigns the result to the left argument. -Either way, if I<optype> is non-zero then I<flags> has no effect. - -If I<optype> is zero, then a plain scalar or list assignment is -constructed. Which type of assignment it is is automatically determined. -I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS> -will be set automatically, and, shifted up eight bits, the eight bits -of C<op_private>, except that the bit with value 1 or 2 is automatically -set as required. - - OP * newASSIGNOP(I32 flags, OP *left, I32 optype, - OP *right) - -=for hackers -Found in file op.c - -=item newBINOP -X<newBINOP> - -Constructs, checks, and returns an op of any binary type. I<type> -is the opcode. I<flags> gives the eight bits of C<op_flags>, except -that C<OPf_KIDS> will be set automatically, and, shifted up eight bits, -the eight bits of C<op_private>, except that the bit with value 1 or -2 is automatically set as required. I<first> and I<last> supply up to -two ops to be the direct children of the binary op; they are consumed -by this function and become part of the constructed op tree. - - OP * newBINOP(I32 type, I32 flags, OP *first, - OP *last) - -=for hackers -Found in file op.c - -=item newCONDOP -X<newCONDOP> - -Constructs, checks, and returns a conditional-expression (C<cond_expr>) -op. I<flags> gives the eight bits of C<op_flags>, except that C<OPf_KIDS> -will be set automatically, and, shifted up eight bits, the eight bits of -C<op_private>, except that the bit with value 1 is automatically set. -I<first> supplies the expression selecting between the two branches, -and I<trueop> and I<falseop> supply the branches; they are consumed by -this function and become part of the constructed op tree. - - OP * newCONDOP(I32 flags, OP *first, OP *trueop, - OP *falseop) - -=for hackers -Found in file op.c - -=item newFOROP -X<newFOROP> - -Constructs, checks, and returns an op tree expressing a C<foreach> -loop (iteration through a list of values). This is a heavyweight loop, -with structure that allows exiting the loop by C<last> and suchlike. - -I<sv> optionally supplies the variable that will be aliased to each -item in turn; if null, it defaults to C<$_> (either lexical or global). -I<expr> supplies the list of values to iterate over. I<block> supplies -the main body of the loop, and I<cont> optionally supplies a C<continue> -block that operates as a second half of the body. All of these optree -inputs are consumed by this function and become part of the constructed -op tree. - -I<flags> gives the eight bits of C<op_flags> for the C<leaveloop> -op and, shifted up eight bits, the eight bits of C<op_private> for -the C<leaveloop> op, except that (in both cases) some bits will be set -automatically. - - OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block, - OP *cont) - -=for hackers -Found in file op.c - -=item newGIVENOP -X<newGIVENOP> - -Constructs, checks, and returns an op tree expressing a C<given> block. -I<cond> supplies the expression that will be locally assigned to a lexical -variable, and I<block> supplies the body of the C<given> construct; they -are consumed by this function and become part of the constructed op tree. -I<defsv_off> is the pad offset of the scalar lexical variable that will -be affected. - - OP * newGIVENOP(OP *cond, OP *block, - PADOFFSET defsv_off) - -=for hackers -Found in file op.c - -=item newGVOP -X<newGVOP> - -Constructs, checks, and returns an op of any type that involves an -embedded reference to a GV. I<type> is the opcode. I<flags> gives the -eight bits of C<op_flags>. I<gv> identifies the GV that the op should -reference; calling this function does not transfer ownership of any -reference to it. - - OP * newGVOP(I32 type, I32 flags, GV *gv) - -=for hackers -Found in file op.c - -=item newLISTOP -X<newLISTOP> - -Constructs, checks, and returns an op of any list type. I<type> is -the opcode. I<flags> gives the eight bits of C<op_flags>, except that -C<OPf_KIDS> will be set automatically if required. I<first> and I<last> -supply up to two ops to be direct children of the list op; they are -consumed by this function and become part of the constructed op tree. - - OP * newLISTOP(I32 type, I32 flags, OP *first, - OP *last) - -=for hackers -Found in file op.c - -=item newLOGOP -X<newLOGOP> - -Constructs, checks, and returns a logical (flow control) op. I<type> -is the opcode. I<flags> gives the eight bits of C<op_flags>, except -that C<OPf_KIDS> will be set automatically, and, shifted up eight bits, -the eight bits of C<op_private>, except that the bit with value 1 is -automatically set. I<first> supplies the expression controlling the -flow, and I<other> supplies the side (alternate) chain of ops; they are -consumed by this function and become part of the constructed op tree. - - OP * newLOGOP(I32 type, I32 flags, OP *first, - OP *other) - -=for hackers -Found in file op.c - -=item newLOOPEX -X<newLOOPEX> - -Constructs, checks, and returns a loop-exiting op (such as C<goto> -or C<last>). I<type> is the opcode. I<label> supplies the parameter -determining the target of the op; it is consumed by this function and -become part of the constructed op tree. - - OP * newLOOPEX(I32 type, OP *label) - -=for hackers -Found in file op.c - -=item newLOOPOP -X<newLOOPOP> - -Constructs, checks, and returns an op tree expressing a loop. This is -only a loop in the control flow through the op tree; it does not have -the heavyweight loop structure that allows exiting the loop by C<last> -and suchlike. I<flags> gives the eight bits of C<op_flags> for the -top-level op, except that some bits will be set automatically as required. -I<expr> supplies the expression controlling loop iteration, and I<block> -supplies the body of the loop; they are consumed by this function and -become part of the constructed op tree. I<debuggable> is currently -unused and should always be 1. - - OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr, - OP *block) - -=for hackers -Found in file op.c - -=item newNULLLIST -X<newNULLLIST> - -Constructs, checks, and returns a new C<stub> op, which represents an -empty list expression. - - OP * newNULLLIST() - -=for hackers -Found in file op.c - -=item newOP -X<newOP> - -Constructs, checks, and returns an op of any base type (any type that -has no extra fields). I<type> is the opcode. I<flags> gives the -eight bits of C<op_flags>, and, shifted up eight bits, the eight bits -of C<op_private>. - - OP * newOP(I32 type, I32 flags) - -=for hackers -Found in file op.c - -=item newPADOP -X<newPADOP> - -Constructs, checks, and returns an op of any type that involves a -reference to a pad element. I<type> is the opcode. I<flags> gives the -eight bits of C<op_flags>. A pad slot is automatically allocated, and -is populated with I<sv>; this function takes ownership of one reference -to it. - -This function only exists if Perl has been compiled to use ithreads. - - OP * newPADOP(I32 type, I32 flags, SV *sv) - -=for hackers -Found in file op.c - -=item newPMOP -X<newPMOP> - -Constructs, checks, and returns an op of any pattern matching type. -I<type> is the opcode. I<flags> gives the eight bits of C<op_flags> -and, shifted up eight bits, the eight bits of C<op_private>. - - OP * newPMOP(I32 type, I32 flags) - -=for hackers -Found in file op.c - -=item newPVOP -X<newPVOP> - -Constructs, checks, and returns an op of any type that involves an -embedded C-level pointer (PV). I<type> is the opcode. I<flags> gives -the eight bits of C<op_flags>. I<pv> supplies the C-level pointer, which -must have been allocated using L</PerlMemShared_malloc>; the memory will -be freed when the op is destroyed. - - OP * newPVOP(I32 type, I32 flags, char *pv) - -=for hackers -Found in file op.c - -=item newRANGE -X<newRANGE> - -Constructs and returns a C<range> op, with subordinate C<flip> and -C<flop> ops. I<flags> gives the eight bits of C<op_flags> for the -C<flip> op and, shifted up eight bits, the eight bits of C<op_private> -for both the C<flip> and C<range> ops, except that the bit with value -1 is automatically set. I<left> and I<right> supply the expressions -controlling the endpoints of the range; they are consumed by this function -and become part of the constructed op tree. - - OP * newRANGE(I32 flags, OP *left, OP *right) - -=for hackers -Found in file op.c - -=item newSLICEOP -X<newSLICEOP> - -Constructs, checks, and returns an C<lslice> (list slice) op. I<flags> -gives the eight bits of C<op_flags>, except that C<OPf_KIDS> will -be set automatically, and, shifted up eight bits, the eight bits of -C<op_private>, except that the bit with value 1 or 2 is automatically -set as required. I<listval> and I<subscript> supply the parameters of -the slice; they are consumed by this function and become part of the -constructed op tree. - - OP * newSLICEOP(I32 flags, OP *subscript, - OP *listval) - -=for hackers -Found in file op.c - -=item newSTATEOP -X<newSTATEOP> - -Constructs a state op (COP). The state op is normally a C<nextstate> op, -but will be a C<dbstate> op if debugging is enabled for currently-compiled -code. The state op is populated from L</PL_curcop> (or L</PL_compiling>). -If I<label> is non-null, it supplies the name of a label to attach to -the state op; this function takes ownership of the memory pointed at by -I<label>, and will free it. I<flags> gives the eight bits of C<op_flags> -for the state op. - -If I<o> is null, the state op is returned. Otherwise the state op is -combined with I<o> into a C<lineseq> list op, which is returned. I<o> -is consumed by this function and becomes part of the returned op tree. - - OP * newSTATEOP(I32 flags, char *label, OP *o) - -=for hackers -Found in file op.c - -=item newSVOP -X<newSVOP> - -Constructs, checks, and returns an op of any type that involves an -embedded SV. I<type> is the opcode. I<flags> gives the eight bits -of C<op_flags>. I<sv> gives the SV to embed in the op; this function -takes ownership of one reference to it. - - OP * newSVOP(I32 type, I32 flags, SV *sv) - -=for hackers -Found in file op.c - -=item newUNOP -X<newUNOP> - -Constructs, checks, and returns an op of any unary type. I<type> is -the opcode. I<flags> gives the eight bits of C<op_flags>, except that -C<OPf_KIDS> will be set automatically if required, and, shifted up eight -bits, the eight bits of C<op_private>, except that the bit with value 1 -is automatically set. I<first> supplies an optional op to be the direct -child of the unary op; it is consumed by this function and become part -of the constructed op tree. - - OP * newUNOP(I32 type, I32 flags, OP *first) - -=for hackers -Found in file op.c - -=item newWHENOP -X<newWHENOP> - -Constructs, checks, and returns an op tree expressing a C<when> block. -I<cond> supplies the test expression, and I<block> supplies the block -that will be executed if the test evaluates to true; they are consumed -by this function and become part of the constructed op tree. I<cond> -will be interpreted DWIMically, often as a comparison against C<$_>, -and may be null to generate a C<default> block. - - OP * newWHENOP(OP *cond, OP *block) - -=for hackers -Found in file op.c - -=item newWHILEOP -X<newWHILEOP> - -Constructs, checks, and returns an op tree expressing a C<while> loop. -This is a heavyweight loop, with structure that allows exiting the loop -by C<last> and suchlike. - -I<loop> is an optional preconstructed C<enterloop> op to use in the -loop; if it is null then a suitable op will be constructed automatically. -I<expr> supplies the loop's controlling expression. I<block> supplies the -main body of the loop, and I<cont> optionally supplies a C<continue> block -that operates as a second half of the body. All of these optree inputs -are consumed by this function and become part of the constructed op tree. - -I<flags> gives the eight bits of C<op_flags> for the C<leaveloop> -op and, shifted up eight bits, the eight bits of C<op_private> for -the C<leaveloop> op, except that (in both cases) some bits will be set -automatically. I<debuggable> is currently unused and should always be 1. -I<has_my> can be supplied as true to force the -loop body to be enclosed in its own scope. - - OP * newWHILEOP(I32 flags, I32 debuggable, - LOOP *loop, OP *expr, OP *block, - OP *cont, I32 has_my) - -=for hackers -Found in file op.c - - -=back - -=head1 Optree Manipulation Functions - -=over 8 - -=item ck_entersub_args_list -X<ck_entersub_args_list> - -Performs the default fixup of the arguments part of an C<entersub> -op tree. This consists of applying list context to each of the -argument ops. This is the standard treatment used on a call marked -with C<&>, or a method call, or a call through a subroutine reference, -or any other call where the callee can't be identified at compile time, -or a call where the callee has no prototype. - - OP * ck_entersub_args_list(OP *entersubop) - -=for hackers -Found in file op.c - -=item ck_entersub_args_proto -X<ck_entersub_args_proto> - -Performs the fixup of the arguments part of an C<entersub> op tree -based on a subroutine prototype. This makes various modifications to -the argument ops, from applying context up to inserting C<refgen> ops, -and checking the number and syntactic types of arguments, as directed by -the prototype. This is the standard treatment used on a subroutine call, -not marked with C<&>, where the callee can be identified at compile time -and has a prototype. - -I<protosv> supplies the subroutine prototype to be applied to the call. -It may be a normal defined scalar, of which the string value will be used. -Alternatively, for convenience, it may be a subroutine object (a C<CV*> -that has been cast to C<SV*>) which has a prototype. The prototype -supplied, in whichever form, does not need to match the actual callee -referenced by the op tree. - -If the argument ops disagree with the prototype, for example by having -an unacceptable number of arguments, a valid op tree is returned anyway. -The error is reflected in the parser state, normally resulting in a single -exception at the top level of parsing which covers all the compilation -errors that occurred. In the error message, the callee is referred to -by the name defined by the I<namegv> parameter. - - OP * ck_entersub_args_proto(OP *entersubop, - GV *namegv, SV *protosv) - -=for hackers -Found in file op.c - -=item ck_entersub_args_proto_or_list -X<ck_entersub_args_proto_or_list> - -Performs the fixup of the arguments part of an C<entersub> op tree either -based on a subroutine prototype or using default list-context processing. -This is the standard treatment used on a subroutine call, not marked -with C<&>, where the callee can be identified at compile time. - -I<protosv> supplies the subroutine prototype to be applied to the call, -or indicates that there is no prototype. It may be a normal scalar, -in which case if it is defined then the string value will be used -as a prototype, and if it is undefined then there is no prototype. -Alternatively, for convenience, it may be a subroutine object (a C<CV*> -that has been cast to C<SV*>), of which the prototype will be used if it -has one. The prototype (or lack thereof) supplied, in whichever form, -does not need to match the actual callee referenced by the op tree. - -If the argument ops disagree with the prototype, for example by having -an unacceptable number of arguments, a valid op tree is returned anyway. -The error is reflected in the parser state, normally resulting in a single -exception at the top level of parsing which covers all the compilation -errors that occurred. In the error message, the callee is referred to -by the name defined by the I<namegv> parameter. - - OP * ck_entersub_args_proto_or_list(OP *entersubop, - GV *namegv, - SV *protosv) - -=for hackers -Found in file op.c - -=item cv_const_sv -X<cv_const_sv> - -If C<cv> is a constant sub eligible for inlining. returns the constant -value returned by the sub. Otherwise, returns NULL. - -Constant subs can be created with C<newCONSTSUB> or as described in -L<perlsub/"Constant Functions">. - - SV* cv_const_sv(const CV *const cv) - -=for hackers -Found in file op.c - -=item cv_get_call_checker -X<cv_get_call_checker> - -Retrieves the function that will be used to fix up a call to I<cv>. -Specifically, the function is applied to an C<entersub> op tree for a -subroutine call, not marked with C<&>, where the callee can be identified -at compile time as I<cv>. - -The C-level function pointer is returned in I<*ckfun_p>, and an SV -argument for it is returned in I<*ckobj_p>. The function is intended -to be called in this manner: - - entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p)); - -In this call, I<entersubop> is a pointer to the C<entersub> op, -which may be replaced by the check function, and I<namegv> is a GV -supplying the name that should be used by the check function to refer -to the callee of the C<entersub> op if it needs to emit any diagnostics. -It is permitted to apply the check function in non-standard situations, -such as to a call to a different subroutine or to a method call. - -By default, the function is -L<Perl_ck_entersub_args_proto_or_list|/ck_entersub_args_proto_or_list>, -and the SV parameter is I<cv> itself. This implements standard -prototype processing. It can be changed, for a particular subroutine, -by L</cv_set_call_checker>. - - void cv_get_call_checker(CV *cv, - Perl_call_checker *ckfun_p, - SV **ckobj_p) - -=for hackers -Found in file op.c - -=item cv_set_call_checker -X<cv_set_call_checker> - -Sets the function that will be used to fix up a call to I<cv>. -Specifically, the function is applied to an C<entersub> op tree for a -subroutine call, not marked with C<&>, where the callee can be identified -at compile time as I<cv>. - -The C-level function pointer is supplied in I<ckfun>, and an SV argument -for it is supplied in I<ckobj>. The function is intended to be called -in this manner: - - entersubop = ckfun(aTHX_ entersubop, namegv, ckobj); - -In this call, I<entersubop> is a pointer to the C<entersub> op, -which may be replaced by the check function, and I<namegv> is a GV -supplying the name that should be used by the check function to refer -to the callee of the C<entersub> op if it needs to emit any diagnostics. -It is permitted to apply the check function in non-standard situations, -such as to a call to a different subroutine or to a method call. - -The current setting for a particular CV can be retrieved by -L</cv_get_call_checker>. - - void cv_set_call_checker(CV *cv, - Perl_call_checker ckfun, - SV *ckobj) - -=for hackers -Found in file op.c - -=item LINKLIST -X<LINKLIST> - -Given the root of an optree, link the tree in execution order using the -C<op_next> pointers and return the first op executed. If this has -already been done, it will not be redone, and C<< o->op_next >> will be -returned. If C<< o->op_next >> is not already set, I<o> should be at -least an C<UNOP>. - - OP* LINKLIST(OP *o) - -=for hackers -Found in file op.h - -=item newCONSTSUB -X<newCONSTSUB> - -See L</newCONSTSUB_flags>. - - CV* newCONSTSUB(HV* stash, const char* name, SV* sv) - -=for hackers -Found in file op.c - -=item newCONSTSUB_flags -X<newCONSTSUB_flags> - -Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is -eligible for inlining at compile-time. - -Currently, the only useful value for C<flags> is SVf_UTF8. - -Passing NULL for SV creates a constant sub equivalent to C<sub BAR () {}>, -which won't be called if used as a destructor, but will suppress the overhead -of a call to C<AUTOLOAD>. (This form, however, isn't eligible for inlining at -compile time.) - - CV* newCONSTSUB_flags(HV* stash, const char* name, - STRLEN len, U32 flags, SV* sv) - -=for hackers -Found in file op.c - -=item newXS -X<newXS> - -Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be -static storage, as it is used directly as CvFILE(), without a copy being made. - -=for hackers -Found in file op.c - -=item op_append_elem -X<op_append_elem> - -Append an item to the list of ops contained directly within a list-type -op, returning the lengthened list. I<first> is the list-type op, -and I<last> is the op to append to the list. I<optype> specifies the -intended opcode for the list. If I<first> is not already a list of the -right type, it will be upgraded into one. If either I<first> or I<last> -is null, the other is returned unchanged. - - OP * op_append_elem(I32 optype, OP *first, OP *last) - -=for hackers -Found in file op.c - -=item op_append_list -X<op_append_list> - -Concatenate the lists of ops contained directly within two list-type ops, -returning the combined list. I<first> and I<last> are the list-type ops -to concatenate. I<optype> specifies the intended opcode for the list. -If either I<first> or I<last> is not already a list of the right type, -it will be upgraded into one. If either I<first> or I<last> is null, -the other is returned unchanged. - - OP * op_append_list(I32 optype, OP *first, OP *last) - -=for hackers -Found in file op.c - -=item OP_CLASS -X<OP_CLASS> - -Return the class of the provided OP: that is, which of the *OP -structures it uses. For core ops this currently gets the information out -of PL_opargs, which does not always accurately reflect the type used. -For custom ops the type is returned from the registration, and it is up -to the registree to ensure it is accurate. The value returned will be -one of the OA_* constants from op.h. - - U32 OP_CLASS(OP *o) - -=for hackers -Found in file op.h - -=item OP_DESC -X<OP_DESC> - -Return a short description of the provided OP. - - const char * OP_DESC(OP *o) - -=for hackers -Found in file op.h - -=item op_linklist -X<op_linklist> - -This function is the implementation of the L</LINKLIST> macro. It should -not be called directly. - - OP* op_linklist(OP *o) - -=for hackers -Found in file op.c - -=item op_lvalue -X<op_lvalue> - -Propagate lvalue ("modifiable") context to an op and its children. -I<type> represents the context type, roughly based on the type of op that -would do the modifying, although C<local()> is represented by OP_NULL, -because it has no op type of its own (it is signalled by a flag on -the lvalue op). - -This function detects things that can't be modified, such as C<$x+1>, and -generates errors for them. For example, C<$x+1 = 2> would cause it to be -called with an op of type OP_ADD and a C<type> argument of OP_SASSIGN. - -It also flags things that need to behave specially in an lvalue context, -such as C<$$x = 5> which might have to vivify a reference in C<$x>. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * op_lvalue(OP *o, I32 type) - -=for hackers -Found in file op.c - -=item OP_NAME -X<OP_NAME> - -Return the name of the provided OP. For core ops this looks up the name -from the op_type; for custom ops from the op_ppaddr. - - const char * OP_NAME(OP *o) - -=for hackers -Found in file op.h - -=item op_prepend_elem -X<op_prepend_elem> - -Prepend an item to the list of ops contained directly within a list-type -op, returning the lengthened list. I<first> is the op to prepend to the -list, and I<last> is the list-type op. I<optype> specifies the intended -opcode for the list. If I<last> is not already a list of the right type, -it will be upgraded into one. If either I<first> or I<last> is null, -the other is returned unchanged. - - OP * op_prepend_elem(I32 optype, OP *first, OP *last) - -=for hackers -Found in file op.c - -=item op_scope -X<op_scope> - -Wraps up an op tree with some additional ops so that at runtime a dynamic -scope will be created. The original ops run in the new dynamic scope, -and then, provided that they exit normally, the scope will be unwound. -The additional ops used to create and unwind the dynamic scope will -normally be an C<enter>/C<leave> pair, but a C<scope> op may be used -instead if the ops are simple enough to not need the full dynamic scope -structure. - -NOTE: this function is experimental and may change or be -removed without notice. - - OP * op_scope(OP *o) - -=for hackers -Found in file op.c - -=item rv2cv_op_cv -X<rv2cv_op_cv> - -Examines an op, which is expected to identify a subroutine at runtime, -and attempts to determine at compile time which subroutine it identifies. -This is normally used during Perl compilation to determine whether -a prototype can be applied to a function call. I<cvop> is the op -being considered, normally an C<rv2cv> op. A pointer to the identified -subroutine is returned, if it could be determined statically, and a null -pointer is returned if it was not possible to determine statically. - -Currently, the subroutine can be identified statically if the RV that the -C<rv2cv> is to operate on is provided by a suitable C<gv> or C<const> op. -A C<gv> op is suitable if the GV's CV slot is populated. A C<const> op is -suitable if the constant value must be an RV pointing to a CV. Details of -this process may change in future versions of Perl. If the C<rv2cv> op -has the C<OPpENTERSUB_AMPER> flag set then no attempt is made to identify -the subroutine statically: this flag is used to suppress compile-time -magic on a subroutine call, forcing it to use default runtime behaviour. - -If I<flags> has the bit C<RV2CVOPCV_MARK_EARLY> set, then the handling -of a GV reference is modified. If a GV was examined and its CV slot was -found to be empty, then the C<gv> op has the C<OPpEARLY_CV> flag set. -If the op is not optimised away, and the CV slot is later populated with -a subroutine having a prototype, that flag eventually triggers the warning -"called too early to check prototype". - -If I<flags> has the bit C<RV2CVOPCV_RETURN_NAME_GV> set, then instead -of returning a pointer to the subroutine it returns a pointer to the -GV giving the most appropriate name for the subroutine in this context. -Normally this is just the C<CvGV> of the subroutine, but for an anonymous -(C<CvANON>) subroutine that is referenced through a GV it will be the -referencing GV. The resulting C<GV*> is cast to C<CV*> to be returned. -A null pointer is returned as usual if there is no statically-determinable -subroutine. - - CV * rv2cv_op_cv(OP *cvop, U32 flags) - -=for hackers -Found in file op.c - - -=back - -=head1 Pad Data Structures - -=over 8 - -=item CvPADLIST -X<CvPADLIST> - -CV's can have CvPADLIST(cv) set to point to an AV. This is the CV's -scratchpad, which stores lexical variables and opcode temporary and -per-thread values. - -For these purposes "forms" are a kind-of CV, eval""s are too (except they're -not callable at will and are always thrown away after the eval"" is done -executing). Require'd files are simply evals without any outer lexical -scope. - -XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad, -but that is really the callers pad (a slot of which is allocated by -every entersub). - -The CvPADLIST AV has the REFCNT of its component items managed "manually" -(mostly in pad.c) rather than by normal av.c rules. So we turn off AvREAL -just before freeing it, to let av.c know not to touch the entries. -The items in the AV are not SVs as for a normal AV, but other AVs: - -0'th Entry of the CvPADLIST is an AV which represents the "names" or rather -the "static type information" for lexicals. - -The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that -depth of recursion into the CV. -The 0'th slot of a frame AV is an AV which is @_. -other entries are storage for variables and op targets. - -Iterating over the names AV iterates over all possible pad -items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having -&PL_sv_undef "names" (see pad_alloc()). - -Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names. -The rest are op targets/GVs/constants which are statically allocated -or resolved at compile time. These don't have names by which they -can be looked up from Perl code at run time through eval"" like -my/our variables can be. Since they can't be looked up by "name" -but only by their index allocated at compile time (which is usually -in PL_op->op_targ), wasting a name SV for them doesn't make sense. - -The SVs in the names AV have their PV being the name of the variable. -xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for -which the name is valid (accessed through the macros COP_SEQ_RANGE_LOW and -_HIGH). During compilation, these fields may hold the special value -PERL_PADSEQ_INTRO to indicate various stages: - - COP_SEQ_RANGE_LOW _HIGH - ----------------- ----- - PERL_PADSEQ_INTRO 0 variable not yet introduced: { my ($x - valid-seq# PERL_PADSEQ_INTRO variable in scope: { my ($x) - valid-seq# valid-seq# compilation of scope complete: { my ($x) } - -For typed lexicals name SV is SVt_PVMG and SvSTASH -points at the type. For C<our> lexicals, the type is also SVt_PVMG, with the -SvOURSTASH slot pointing at the stash of the associated global (so that -duplicate C<our> declarations in the same package can be detected). SvUVX is -sometimes hijacked to store the generation number during compilation. - -If SvFAKE is set on the name SV, then that slot in the frame AV is -a REFCNT'ed reference to a lexical from "outside". In this case, -the name SV does not use xlow and xhigh to store a cop_seq range, since it is -in scope throughout. Instead xhigh stores some flags containing info about -the real lexical (is it declared in an anon, and is it capable of being -instantiated multiple times?), and for fake ANONs, xlow contains the index -within the parent's pad where the lexical's value is stored, to make -cloning quicker. - -If the 'name' is '&' the corresponding entry in frame AV -is a CV representing a possible closure. -(SvFAKE and name of '&' is not a meaningful combination currently but could -become so if C<my sub foo {}> is implemented.) - -Note that formats are treated as anon subs, and are cloned each time -write is called (if necessary). - -The flag SVs_PADSTALE is cleared on lexicals each time the my() is executed, -and set on scope exit. This allows the 'Variable $x is not available' warning -to be generated in evals, such as - - { my $x = 1; sub f { eval '$x'} } f(); - -For state vars, SVs_PADSTALE is overloaded to mean 'not yet initialised' - -NOTE: this function is experimental and may change or be -removed without notice. - - PADLIST * CvPADLIST(CV *cv) - -=for hackers -Found in file pad.c - -=item pad_add_name_pvs -X<pad_add_name_pvs> - -Exactly like L</pad_add_name_pvn>, but takes a literal string instead -of a string/length pair. - - PADOFFSET pad_add_name_pvs(const char *name, U32 flags, - HV *typestash, HV *ourstash) - -=for hackers -Found in file pad.h - -=item pad_findmy_pvs -X<pad_findmy_pvs> - -Exactly like L</pad_findmy_pvn>, but takes a literal string instead -of a string/length pair. - - PADOFFSET pad_findmy_pvs(const char *name, U32 flags) - -=for hackers -Found in file pad.h - -=item pad_new -X<pad_new> - -Create a new padlist, updating the global variables for the -currently-compiling padlist to point to the new padlist. The following -flags can be OR'ed together: - - padnew_CLONE this pad is for a cloned CV - padnew_SAVE save old globals on the save stack - padnew_SAVESUB also save extra stuff for start of sub - - PADLIST * pad_new(int flags) - -=for hackers -Found in file pad.c - -=item PL_comppad -X<PL_comppad> - -During compilation, this points to the array containing the values -part of the pad for the currently-compiling code. (At runtime a CV may -have many such value arrays; at compile time just one is constructed.) -At runtime, this points to the array containing the currently-relevant -values for the pad for the currently-executing code. - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file pad.c - -=item PL_comppad_name -X<PL_comppad_name> - -During compilation, this points to the array containing the names part -of the pad for the currently-compiling code. - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file pad.c - -=item PL_curpad -X<PL_curpad> - -Points directly to the body of the L</PL_comppad> array. -(I.e., this is C<AvARRAY(PL_comppad)>.) - -NOTE: this function is experimental and may change or be -removed without notice. - -=for hackers -Found in file pad.c - - -=back - -=head1 Per-Interpreter Variables - -=over 8 - -=item PL_modglobal -X<PL_modglobal> - -C<PL_modglobal> 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<PL_na> - -A convenience variable which is typically used with C<SvPV> 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<SvPV_nolen> macro. - - STRLEN PL_na - -=for hackers -Found in file intrpvar.h - -=item PL_opfreehook -X<PL_opfreehook> - -When non-C<NULL>, the function pointed by this variable will be called each time an OP is freed with the corresponding OP as the argument. -This allows extensions to free any extra attribute they have locally attached to an OP. -It is also assured to first fire for the parent OP and then for its kids. - -When you replace this variable, it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own. - - Perl_ophook_t PL_opfreehook - -=for hackers -Found in file intrpvar.h - -=item PL_peepp -X<PL_peepp> - -Pointer to the per-subroutine peephole optimiser. This is a function -that gets called at the end of compilation of a Perl subroutine (or -equivalently independent piece of Perl code) to perform fixups of -some ops and to perform small-scale optimisations. The function is -called once for each subroutine that is compiled, and is passed, as sole -parameter, a pointer to the op that is the entry point to the subroutine. -It modifies the op tree in place. - -The peephole optimiser should never be completely replaced. Rather, -add code to it by wrapping the existing optimiser. The basic way to do -this can be seen in L<perlguts/Compile pass 3: peephole optimization>. -If the new code wishes to operate on ops throughout the subroutine's -structure, rather than just at the top level, it is likely to be more -convenient to wrap the L</PL_rpeepp> hook. - - peep_t PL_peepp - -=for hackers -Found in file intrpvar.h - -=item PL_rpeepp -X<PL_rpeepp> - -Pointer to the recursive peephole optimiser. This is a function -that gets called at the end of compilation of a Perl subroutine (or -equivalently independent piece of Perl code) to perform fixups of some -ops and to perform small-scale optimisations. The function is called -once for each chain of ops linked through their C<op_next> fields; -it is recursively called to handle each side chain. It is passed, as -sole parameter, a pointer to the op that is at the head of the chain. -It modifies the op tree in place. - -The peephole optimiser should never be completely replaced. Rather, -add code to it by wrapping the existing optimiser. The basic way to do -this can be seen in L<perlguts/Compile pass 3: peephole optimization>. -If the new code wishes to operate only on ops at a subroutine's top level, -rather than throughout the structure, it is likely to be more convenient -to wrap the L</PL_peepp> hook. - - peep_t PL_rpeepp - -=for hackers -Found in file intrpvar.h - -=item PL_sv_no -X<PL_sv_no> - -This is the C<false> SV. See C<PL_sv_yes>. 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<PL_sv_undef> - -This is the C<undef> 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<PL_sv_yes> - -This is the C<true> SV. See C<PL_sv_no>. Always refer to this as -C<&PL_sv_yes>. - - SV PL_sv_yes - -=for hackers -Found in file intrpvar.h - - -=back - -=head1 REGEXP Functions - -=over 8 - -=item SvRX -X<SvRX> - -Convenience macro to get the REGEXP from a SV. This is approximately -equivalent to the following snippet: - - if (SvMAGICAL(sv)) - mg_get(sv); - if (SvROK(sv)) - sv = MUTABLE_SV(SvRV(sv)); - if (SvTYPE(sv) == SVt_REGEXP) - return (REGEXP*) sv; - -NULL will be returned if a REGEXP* is not found. - - REGEXP * SvRX(SV *sv) - -=for hackers -Found in file regexp.h - -=item SvRXOK -X<SvRXOK> - -Returns a boolean indicating whether the SV (or the one it references) -is a REGEXP. - -If you want to do something with the REGEXP* later use SvRX instead -and check for NULL. - - bool SvRXOK(SV* sv) - -=for hackers -Found in file regexp.h - - -=back - -=head1 Simple Exception Handling Macros - -=over 8 - -=item dXCPT -X<dXCPT> - -Set up necessary local variables for exception handling. -See L<perlguts/"Exception Handling">. - - dXCPT; - -=for hackers -Found in file XSUB.h - -=item XCPT_CATCH -X<XCPT_CATCH> - -Introduces a catch block. See L<perlguts/"Exception Handling">. - -=for hackers -Found in file XSUB.h - -=item XCPT_RETHROW -X<XCPT_RETHROW> - -Rethrows a previously caught exception. See L<perlguts/"Exception Handling">. - - XCPT_RETHROW; - -=for hackers -Found in file XSUB.h - -=item XCPT_TRY_END -X<XCPT_TRY_END> - -Ends a try block. See L<perlguts/"Exception Handling">. - -=for hackers -Found in file XSUB.h - -=item XCPT_TRY_START -X<XCPT_TRY_START> - -Starts a try block. See L<perlguts/"Exception Handling">. - -=for hackers -Found in file XSUB.h - - -=back - -=head1 Stack Manipulation Macros - -=over 8 - -=item dMARK -X<dMARK> - -Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and -C<dORIGMARK>. - - dMARK; - -=for hackers -Found in file pp.h - -=item dORIGMARK -X<dORIGMARK> - -Saves the original stack mark for the XSUB. See C<ORIGMARK>. - - dORIGMARK; - -=for hackers -Found in file pp.h - -=item dSP -X<dSP> - -Declares a local copy of perl's stack pointer for the XSUB, available via -the C<SP> macro. See C<SP>. - - dSP; - -=for hackers -Found in file pp.h - -=item EXTEND -X<EXTEND> - -Used to extend the argument stack for an XSUB's return values. Once -used, guarantees that there is room for at least C<nitems> to be pushed -onto the stack. - - void EXTEND(SP, int nitems) - -=for hackers -Found in file pp.h - -=item MARK -X<MARK> - -Stack marker variable for the XSUB. See C<dMARK>. - -=for hackers -Found in file pp.h - -=item mPUSHi -X<mPUSHi> - -Push an integer onto the stack. The stack must have room for this element. -Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi> and C<XPUSHi>. - - void mPUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item mPUSHn -X<mPUSHn> - -Push a double onto the stack. The stack must have room for this element. -Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn> and C<XPUSHn>. - - void mPUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item mPUSHp -X<mPUSHp> - -Push a string onto the stack. The stack must have room for this element. -The C<len> indicates the length of the string. Does not use C<TARG>. -See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>. - - void mPUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item mPUSHs -X<mPUSHs> - -Push an SV onto the stack and mortalizes the SV. The stack must have room -for this element. Does not use C<TARG>. See also C<PUSHs> and C<mXPUSHs>. - - void mPUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item mPUSHu -X<mPUSHu> - -Push an unsigned integer onto the stack. The stack must have room for this -element. Does not use C<TARG>. See also C<PUSHu>, C<mXPUSHu> and C<XPUSHu>. - - void mPUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item mXPUSHi -X<mXPUSHi> - -Push an integer onto the stack, extending the stack if necessary. -Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and C<PUSHi>. - - void mXPUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item mXPUSHn -X<mXPUSHn> - -Push a double onto the stack, extending the stack if necessary. -Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and C<PUSHn>. - - void mXPUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item mXPUSHp -X<mXPUSHp> - -Push a string onto the stack, extending the stack if necessary. The C<len> -indicates the length of the string. Does not use C<TARG>. See also C<XPUSHp>, -C<mPUSHp> and C<PUSHp>. - - void mXPUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item mXPUSHs -X<mXPUSHs> - -Push an SV onto the stack, extending the stack if necessary and mortalizes -the SV. Does not use C<TARG>. See also C<XPUSHs> and C<mPUSHs>. - - void mXPUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item mXPUSHu -X<mXPUSHu> - -Push an unsigned integer onto the stack, extending the stack if necessary. -Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu> and C<PUSHu>. - - void mXPUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item ORIGMARK -X<ORIGMARK> - -The original stack mark for the XSUB. See C<dORIGMARK>. - -=for hackers -Found in file pp.h - -=item POPi -X<POPi> - -Pops an integer off the stack. - - IV POPi - -=for hackers -Found in file pp.h - -=item POPl -X<POPl> - -Pops a long off the stack. - - long POPl - -=for hackers -Found in file pp.h - -=item POPn -X<POPn> - -Pops a double off the stack. - - NV POPn - -=for hackers -Found in file pp.h - -=item POPp -X<POPp> - -Pops a string off the stack. Deprecated. New code should use POPpx. - - char* POPp - -=for hackers -Found in file pp.h - -=item POPpbytex -X<POPpbytex> - -Pops a string off the stack which must consist of bytes i.e. characters < 256. - - char* POPpbytex - -=for hackers -Found in file pp.h - -=item POPpx -X<POPpx> - -Pops a string off the stack. - - char* POPpx - -=for hackers -Found in file pp.h - -=item POPs -X<POPs> - -Pops an SV off the stack. - - SV* POPs - -=for hackers -Found in file pp.h - -=item PUSHi -X<PUSHi> - -Push an integer onto the stack. The stack must have room for this element. -Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be -called to declare it. Do not call multiple C<TARG>-oriented macros to -return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and -C<mXPUSHi>. - - void PUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item PUSHMARK -X<PUSHMARK> - -Opening bracket for arguments on a callback. See C<PUTBACK> and -L<perlcall>. - - void PUSHMARK(SP) - -=for hackers -Found in file pp.h - -=item PUSHmortal -X<PUSHmortal> - -Push a new mortal SV onto the stack. The stack must have room for this -element. Does not use C<TARG>. See also C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>. - - void PUSHmortal() - -=for hackers -Found in file pp.h - -=item PUSHn -X<PUSHn> - -Push a double onto the stack. The stack must have room for this element. -Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be -called to declare it. Do not call multiple C<TARG>-oriented macros to -return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and -C<mXPUSHn>. - - void PUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item PUSHp -X<PUSHp> - -Push a string onto the stack. The stack must have room for this element. -The C<len> indicates the length of the string. Handles 'set' magic. Uses -C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not -call multiple C<TARG>-oriented macros to return lists from XSUB's - see -C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>. - - void PUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item PUSHs -X<PUSHs> - -Push an SV onto the stack. The stack must have room for this element. -Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>, -C<XPUSHs> and C<XPUSHmortal>. - - void PUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item PUSHu -X<PUSHu> - -Push an unsigned integer onto the stack. The stack must have room for this -element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> -should be called to declare it. Do not call multiple C<TARG>-oriented -macros to return lists from XSUB's - see C<mPUSHu> instead. See also -C<XPUSHu> and C<mXPUSHu>. - - void PUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item PUTBACK -X<PUTBACK> - -Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>. -See C<PUSHMARK> and L<perlcall> for other uses. - - PUTBACK; - -=for hackers -Found in file pp.h - -=item SP -X<SP> - -Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and -C<SPAGAIN>. - -=for hackers -Found in file pp.h - -=item SPAGAIN -X<SPAGAIN> - -Refetch the stack pointer. Used after a callback. See L<perlcall>. - - SPAGAIN; - -=for hackers -Found in file pp.h - -=item XPUSHi -X<XPUSHi> - -Push an integer onto the stack, extending the stack if necessary. Handles -'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to -declare it. Do not call multiple C<TARG>-oriented macros to return lists -from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>. - - void XPUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item XPUSHmortal -X<XPUSHmortal> - -Push a new mortal SV onto the stack, extending the stack if necessary. -Does not use C<TARG>. See also C<XPUSHs>, C<PUSHmortal> and C<PUSHs>. - - void XPUSHmortal() - -=for hackers -Found in file pp.h - -=item XPUSHn -X<XPUSHn> - -Push a double onto the stack, extending the stack if necessary. Handles -'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to -declare it. Do not call multiple C<TARG>-oriented macros to return lists -from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>. - - void XPUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item XPUSHp -X<XPUSHp> - -Push a string onto the stack, extending the stack if necessary. The C<len> -indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so -C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call -multiple C<TARG>-oriented macros to return lists from XSUB's - see -C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>. - - void XPUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item XPUSHs -X<XPUSHs> - -Push an SV onto the stack, extending the stack if necessary. Does not -handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>, -C<PUSHs> and C<PUSHmortal>. - - void XPUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item XPUSHu -X<XPUSHu> - -Push an unsigned integer onto the stack, extending the stack if necessary. -Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be -called to declare it. Do not call multiple C<TARG>-oriented macros to -return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and -C<mPUSHu>. - - void XPUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item XSRETURN -X<XSRETURN> - -Return from XSUB, indicating number of items on the stack. This is usually -handled by C<xsubpp>. - - void XSRETURN(int nitems) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_EMPTY -X<XSRETURN_EMPTY> - -Return an empty list from an XSUB immediately. - - XSRETURN_EMPTY; - -=for hackers -Found in file XSUB.h - -=item XSRETURN_IV -X<XSRETURN_IV> - -Return an integer from an XSUB immediately. Uses C<XST_mIV>. - - void XSRETURN_IV(IV iv) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_NO -X<XSRETURN_NO> - -Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>. - - XSRETURN_NO; - -=for hackers -Found in file XSUB.h - -=item XSRETURN_NV -X<XSRETURN_NV> - -Return a double from an XSUB immediately. Uses C<XST_mNV>. - - void XSRETURN_NV(NV nv) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_PV -X<XSRETURN_PV> - -Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>. - - void XSRETURN_PV(char* str) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_UNDEF -X<XSRETURN_UNDEF> - -Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>. - - XSRETURN_UNDEF; - -=for hackers -Found in file XSUB.h - -=item XSRETURN_UV -X<XSRETURN_UV> - -Return an integer from an XSUB immediately. Uses C<XST_mUV>. - - void XSRETURN_UV(IV uv) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_YES -X<XSRETURN_YES> - -Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>. - - XSRETURN_YES; - -=for hackers -Found in file XSUB.h - -=item XST_mIV -X<XST_mIV> - -Place an integer into the specified position C<pos> on the stack. The -value is stored in a new mortal SV. - - void XST_mIV(int pos, IV iv) - -=for hackers -Found in file XSUB.h - -=item XST_mNO -X<XST_mNO> - -Place C<&PL_sv_no> into the specified position C<pos> on the -stack. - - void XST_mNO(int pos) - -=for hackers -Found in file XSUB.h - -=item XST_mNV -X<XST_mNV> - -Place a double into the specified position C<pos> on the stack. The value -is stored in a new mortal SV. - - void XST_mNV(int pos, NV nv) - -=for hackers -Found in file XSUB.h - -=item XST_mPV -X<XST_mPV> - -Place a copy of a string into the specified position C<pos> on the stack. -The value is stored in a new mortal SV. - - void XST_mPV(int pos, char* str) - -=for hackers -Found in file XSUB.h - -=item XST_mUNDEF -X<XST_mUNDEF> - -Place C<&PL_sv_undef> into the specified position C<pos> on the -stack. - - void XST_mUNDEF(int pos) - -=for hackers -Found in file XSUB.h - -=item XST_mYES -X<XST_mYES> - -Place C<&PL_sv_yes> into the specified position C<pos> on the -stack. - - void XST_mYES(int pos) - -=for hackers -Found in file XSUB.h - - -=back - -=head1 SV Flags - -=over 8 - -=item svtype -X<svtype> - -An enum of flags for Perl types. These are found in the file B<sv.h> -in the C<svtype> enum. Test these flags with the C<SvTYPE> macro. - -=for hackers -Found in file sv.h - -=item SVt_IV -X<SVt_IV> - -Integer type flag for scalars. See C<svtype>. - -=for hackers -Found in file sv.h - -=item SVt_NV -X<SVt_NV> - -Double type flag for scalars. See C<svtype>. - -=for hackers -Found in file sv.h - -=item SVt_PV -X<SVt_PV> - -Pointer type flag for scalars. See C<svtype>. - -=for hackers -Found in file sv.h - -=item SVt_PVAV -X<SVt_PVAV> - -Type flag for arrays. See C<svtype>. - -=for hackers -Found in file sv.h - -=item SVt_PVCV -X<SVt_PVCV> - -Type flag for code refs. See C<svtype>. - -=for hackers -Found in file sv.h - -=item SVt_PVHV -X<SVt_PVHV> - -Type flag for hashes. See C<svtype>. - -=for hackers -Found in file sv.h - -=item SVt_PVMG -X<SVt_PVMG> - -Type flag for blessed scalars. See C<svtype>. - -=for hackers -Found in file sv.h - - -=back - -=head1 SV Manipulation Functions - -=over 8 - -=item boolSV -X<boolSV> - -Returns a true SV if C<b> is a true value, or a false SV if C<b> is 0. - -See also C<PL_sv_yes> and C<PL_sv_no>. - - SV * boolSV(bool b) - -=for hackers -Found in file sv.h - -=item croak_xs_usage -X<croak_xs_usage> - -A specialised variant of C<croak()> for emitting the usage message for xsubs - - croak_xs_usage(cv, "eee_yow"); - -works out the package name and subroutine name from C<cv>, and then calls -C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as: - - Perl_croak(aTHX_ "Usage: %"SVf"::%"SVf"(%s)", "ouch" "awk", "eee_yow"); - - void croak_xs_usage(const CV *const cv, - const char *const params) - -=for hackers -Found in file universal.c - -=item get_sv -X<get_sv> - -Returns the SV of the specified Perl scalar. C<flags> are passed to -C<gv_fetchpv>. If C<GV_ADD> is set and the -Perl variable does not exist then it will be created. If C<flags> is zero -and the variable does not exist then NULL is returned. - -NOTE: the perl_ form of this function is deprecated. - - SV* get_sv(const char *name, I32 flags) - -=for hackers -Found in file perl.c - -=item newRV_inc -X<newRV_inc> - -Creates an RV wrapper for an SV. The reference count for the original SV is -incremented. - - SV* newRV_inc(SV* sv) - -=for hackers -Found in file sv.h - -=item newSVpvn_utf8 -X<newSVpvn_utf8> - -Creates a new SV and copies a string into it. If utf8 is true, calls -C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>. - - SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, - U32 utf8) - -=for hackers -Found in file sv.h - -=item SvCUR -X<SvCUR> - -Returns the length of the string which is in the SV. See C<SvLEN>. - - STRLEN SvCUR(SV* sv) - -=for hackers -Found in file sv.h - -=item SvCUR_set -X<SvCUR_set> - -Set the current length of the string which is in the SV. See C<SvCUR> -and C<SvIV_set>. - - void SvCUR_set(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvEND -X<SvEND> - -Returns a pointer to the spot just after the last character in -the string which is in the SV, where there is usually a trailing -null (even though Perl scalars do not strictly require it). -See C<SvCUR>. Access the character as *(SvEND(sv)). - -Warning: If C<SvCUR> is equal to C<SvLEN>, then C<SvEND> points to -unallocated memory. - - char* SvEND(SV* sv) - -=for hackers -Found in file sv.h - -=item SvGAMAGIC -X<SvGAMAGIC> - -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. - - U32 SvGAMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvGROW -X<SvGROW> - -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 -NUL character). Calls C<sv_grow> to perform the expansion if necessary. -Returns a pointer to the character buffer. - - char * SvGROW(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvIOK -X<SvIOK> - -Returns a U32 value indicating whether the SV contains an integer. - - U32 SvIOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOKp -X<SvIOKp> - -Returns a U32 value indicating whether the SV contains an integer. Checks -the B<private> setting. Use C<SvIOK> instead. - - U32 SvIOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_notUV -X<SvIOK_notUV> - -Returns a boolean indicating whether the SV contains a signed integer. - - bool SvIOK_notUV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_off -X<SvIOK_off> - -Unsets the IV status of an SV. - - void SvIOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_on -X<SvIOK_on> - -Tells an SV that it is an integer. - - void SvIOK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_only -X<SvIOK_only> - -Tells an SV that it is an integer and disables all other OK bits. - - void SvIOK_only(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_only_UV -X<SvIOK_only_UV> - -Tells and SV that it is an unsigned integer and disables all other OK bits. - - void SvIOK_only_UV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_UV -X<SvIOK_UV> - -Returns a boolean indicating whether the SV contains an unsigned integer. - - bool SvIOK_UV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIsCOW -X<SvIsCOW> - -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 -COW). - - bool SvIsCOW(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIsCOW_shared_hash -X<SvIsCOW_shared_hash> - -Returns a boolean indicating whether the SV is Copy-On-Write shared hash key -scalar. - - bool SvIsCOW_shared_hash(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIV -X<SvIV> - -Coerces the given SV to an integer and returns it. See C<SvIVx> for a -version which guarantees to evaluate sv only once. - - IV SvIV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIVX -X<SvIVX> - -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<SvIV()>. - - IV SvIVX(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIVx -X<SvIVx> - -Coerces the given SV to an integer and returns it. -Guarantees to evaluate C<sv> only once. Only use -this if C<sv> is an expression with side effects, -otherwise use the more efficient C<SvIV>. - - IV SvIVx(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIV_nomg -X<SvIV_nomg> - -Like C<SvIV> but doesn't process magic. - - IV SvIV_nomg(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIV_set -X<SvIV_set> - -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<SvIVX>. -With future Perls, however, it will be more efficient to use -C<SvIV_set> instead of the lvalue assignment to C<SvIVX>. - - void SvIV_set(SV* sv, IV val) - -=for hackers -Found in file sv.h - -=item SvLEN -X<SvLEN> - -Returns the size of the string buffer in the SV, not including any part -attributable to C<SvOOK>. See C<SvCUR>. - - STRLEN SvLEN(SV* sv) - -=for hackers -Found in file sv.h - -=item SvLEN_set -X<SvLEN_set> - -Set the actual length of the string which is in the SV. See C<SvIV_set>. - - void SvLEN_set(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvMAGIC_set -X<SvMAGIC_set> - -Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>. - - void SvMAGIC_set(SV* sv, MAGIC* val) - -=for hackers -Found in file sv.h - -=item SvNIOK -X<SvNIOK> - -Returns a U32 value indicating whether the SV contains a number, integer or -double. - - U32 SvNIOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNIOKp -X<SvNIOKp> - -Returns a U32 value indicating whether the SV contains a number, integer or -double. Checks the B<private> setting. Use C<SvNIOK> instead. - - U32 SvNIOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNIOK_off -X<SvNIOK_off> - -Unsets the NV/IV status of an SV. - - void SvNIOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK -X<SvNOK> - -Returns a U32 value indicating whether the SV contains a double. - - U32 SvNOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOKp -X<SvNOKp> - -Returns a U32 value indicating whether the SV contains a double. Checks the -B<private> setting. Use C<SvNOK> instead. - - U32 SvNOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK_off -X<SvNOK_off> - -Unsets the NV status of an SV. - - void SvNOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK_on -X<SvNOK_on> - -Tells an SV that it is a double. - - void SvNOK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK_only -X<SvNOK_only> - -Tells an SV that it is a double and disables all other OK bits. - - void SvNOK_only(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNV -X<SvNV> - -Coerce the given SV to a double and return it. See C<SvNVx> for a version -which guarantees to evaluate sv only once. - - NV SvNV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNVX -X<SvNVX> - -Returns the raw value in the SV's NV slot, without checks or conversions. -Only use when you are sure SvNOK is true. See also C<SvNV()>. - - NV SvNVX(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNVx -X<SvNVx> - -Coerces the given SV to a double and returns it. -Guarantees to evaluate C<sv> only once. Only use -this if C<sv> is an expression with side effects, -otherwise use the more efficient C<SvNV>. - - NV SvNVx(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNV_nomg -X<SvNV_nomg> - -Like C<SvNV> but doesn't process magic. - - NV SvNV_nomg(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNV_set -X<SvNV_set> - -Set the value of the NV pointer in sv to val. See C<SvIV_set>. - - void SvNV_set(SV* sv, NV val) - -=for hackers -Found in file sv.h - -=item SvOK -X<SvOK> - -Returns a U32 value indicating whether the value is defined. This is -only meaningful for scalars. - - U32 SvOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvOOK -X<SvOOK> - -Returns a U32 indicating whether the pointer to the string buffer is offset. -This hack is used internally to speed up removal of characters from the -beginning of a SvPV. When SvOOK is true, then the start of the -allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX. -This offset used to be stored in SvIVX, but is now stored within the spare -part of the buffer. - - U32 SvOOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvOOK_offset -X<SvOOK_offset> - -Reads into I<len> the offset from SvPVX back to the true start of the -allocated buffer, which will be non-zero if C<sv_chop> has been used to -efficiently remove characters from start of the buffer. Implemented as a -macro, which takes the address of I<len>, which must be of type C<STRLEN>. -Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false. - - void SvOOK_offset(NN SV*sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPOK -X<SvPOK> - -Returns a U32 value indicating whether the SV contains a character -string. - - U32 SvPOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOKp -X<SvPOKp> - -Returns a U32 value indicating whether the SV contains a character string. -Checks the B<private> setting. Use C<SvPOK> instead. - - U32 SvPOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_off -X<SvPOK_off> - -Unsets the PV status of an SV. - - void SvPOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_on -X<SvPOK_on> - -Tells an SV that it is a string. - - void SvPOK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_only -X<SvPOK_only> - -Tells an SV that it is a string and disables all other OK bits. -Will also turn off the UTF-8 status. - - void SvPOK_only(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_only_UTF8 -X<SvPOK_only_UTF8> - -Tells an SV that it is a string and disables all other OK bits, -and leaves the UTF-8 status as it was. - - void SvPOK_only_UTF8(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPV -X<SvPV> - -Returns a pointer to the string in the SV, or a stringified form of -the SV if the SV does not contain a string. The SV may cache the -stringified version becoming C<SvPOK>. Handles 'get' magic. See also -C<SvPVx> for a version which guarantees to evaluate sv only once. - - char* SvPV(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbyte -X<SvPVbyte> - -Like C<SvPV>, but converts sv to byte representation first if necessary. - - char* SvPVbyte(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbytex -X<SvPVbytex> - -Like C<SvPV>, but converts sv to byte representation first if necessary. -Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte> -otherwise. - - char* SvPVbytex(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbytex_force -X<SvPVbytex_force> - -Like C<SvPV_force>, but converts sv to byte representation first if necessary. -Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force> -otherwise. - - char* SvPVbytex_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbyte_force -X<SvPVbyte_force> - -Like C<SvPV_force>, but converts sv to byte representation first if necessary. - - char* SvPVbyte_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbyte_nolen -X<SvPVbyte_nolen> - -Like C<SvPV_nolen>, but converts sv to byte representation first if necessary. - - char* SvPVbyte_nolen(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPVutf8 -X<SvPVutf8> - -Like C<SvPV>, but converts sv to utf8 first if necessary. - - char* SvPVutf8(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVutf8x -X<SvPVutf8x> - -Like C<SvPV>, but converts sv to utf8 first if necessary. -Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8> -otherwise. - - char* SvPVutf8x(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVutf8x_force -X<SvPVutf8x_force> - -Like C<SvPV_force>, but converts sv to utf8 first if necessary. -Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force> -otherwise. - - char* SvPVutf8x_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVutf8_force -X<SvPVutf8_force> - -Like C<SvPV_force>, but converts sv to utf8 first if necessary. - - char* SvPVutf8_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVutf8_nolen -X<SvPVutf8_nolen> - -Like C<SvPV_nolen>, but converts sv to utf8 first if necessary. - - char* SvPVutf8_nolen(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPVX -X<SvPVX> - -Returns a pointer to the physical string in the SV. The SV must contain a -string. - -This is also used to store the name of an autoloaded subroutine in an XS -AUTOLOAD routine. See L<perlguts/Autoloading with XSUBs>. - - char* SvPVX(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPVx -X<SvPVx> - -A version of C<SvPV> which guarantees to evaluate C<sv> only once. -Only use this if C<sv> is an expression with side effects, otherwise use the -more efficient C<SvPV>. - - char* SvPVx(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_force -X<SvPV_force> - -Like C<SvPV> but will force the SV into containing just a string -(C<SvPOK_only>). You want force if you are going to update the C<SvPVX> -directly. - - char* SvPV_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_force_nomg -X<SvPV_force_nomg> - -Like C<SvPV> but will force the SV into containing just a string -(C<SvPOK_only>). You want force if you are going to update the C<SvPVX> -directly. Doesn't process magic. - - char* SvPV_force_nomg(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_nolen -X<SvPV_nolen> - -Returns a pointer to the string in the SV, or a stringified form of -the SV if the SV does not contain a string. The SV may cache the -stringified form becoming C<SvPOK>. Handles 'get' magic. - - char* SvPV_nolen(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPV_nomg -X<SvPV_nomg> - -Like C<SvPV> but doesn't process magic. - - char* SvPV_nomg(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_nomg_nolen -X<SvPV_nomg_nolen> - -Like C<SvPV_nolen> but doesn't process magic. - - char* SvPV_nomg_nolen(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPV_set -X<SvPV_set> - -Set the value of the PV pointer in sv to val. See C<SvIV_set>. - - void SvPV_set(SV* sv, char* val) - -=for hackers -Found in file sv.h - -=item SvREFCNT -X<SvREFCNT> - -Returns the value of the object's reference count. - - U32 SvREFCNT(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_dec -X<SvREFCNT_dec> - -Decrements the reference count of the given SV. - - void SvREFCNT_dec(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc -X<SvREFCNT_inc> - -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<SvREFCNT_inc_NN> - -Same as SvREFCNT_inc, but can only be used if you know I<sv> -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<SvREFCNT_inc_simple> - -Same as SvREFCNT_inc, but can only be used with expressions without side -effects. 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<SvREFCNT_inc_simple_NN> - -Same as SvREFCNT_inc_simple, but can only be used if you know I<sv> -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<SvREFCNT_inc_simple_void> - -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<SvREFCNT_inc_simple_void_NN> - -Same as SvREFCNT_inc, but can only be used if you don't need the return -value, and you know that I<sv> 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<SvREFCNT_inc_void> - -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<SvREFCNT_inc_void_NN> - -Same as SvREFCNT_inc, but can only be used if you don't need the return -value, and you know that I<sv> 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<SvROK> - -Tests if the SV is an RV. - - U32 SvROK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK_off -X<SvROK_off> - -Unsets the RV status of an SV. - - void SvROK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK_on -X<SvROK_on> - -Tells an SV that it is an RV. - - void SvROK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvRV -X<SvRV> - -Dereferences an RV to return the SV. - - SV* SvRV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvRV_set -X<SvRV_set> - -Set the value of the RV pointer in sv to val. See C<SvIV_set>. - - void SvRV_set(SV* sv, SV* val) - -=for hackers -Found in file sv.h - -=item SvSTASH -X<SvSTASH> - -Returns the stash of the SV. - - HV* SvSTASH(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSTASH_set -X<SvSTASH_set> - -Set the value of the STASH pointer in sv to val. See C<SvIV_set>. - - void SvSTASH_set(SV* sv, HV* val) - -=for hackers -Found in file sv.h - -=item SvTAINT -X<SvTAINT> - -Taints an SV if tainting is enabled, and if some input to the current -expression is tainted--usually a variable, but possibly also implicit -inputs such as locale settings. C<SvTAINT> propagates that taintedness to -the outputs of an expression in a pessimistic fashion; i.e., without paying -attention to precisely which outputs are influenced by which inputs. - - void SvTAINT(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTAINTED -X<SvTAINTED> - -Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if -not. - - bool SvTAINTED(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTAINTED_off -X<SvTAINTED_off> - -Untaints an SV. Be I<very> careful with this routine, as it short-circuits -some of Perl's fundamental security features. XS module authors should not -use this function unless they fully understand all the implications of -unconditionally untainting the value. Untainting should be done in the -standard perl fashion, via a carefully crafted regexp, rather than directly -untainting variables. - - void SvTAINTED_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTAINTED_on -X<SvTAINTED_on> - -Marks an SV as tainted if tainting is enabled. - - void SvTAINTED_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTRUE -X<SvTRUE> - -Returns a boolean indicating whether Perl would evaluate the SV as true or -false. See SvOK() for a defined/undefined test. Handles 'get' magic -unless the scalar is already SvPOK, SvIOK or SvNOK (the public, not the -private flags). - - bool SvTRUE(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTRUE_nomg -X<SvTRUE_nomg> - -Returns a boolean indicating whether Perl would evaluate the SV as true or -false. See SvOK() for a defined/undefined test. Does not handle 'get' magic. - - bool SvTRUE_nomg(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTYPE -X<SvTYPE> - -Returns the type of the SV. See C<svtype>. - - svtype SvTYPE(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUOK -X<SvUOK> - -Returns a boolean indicating whether the SV contains an unsigned integer. - - bool SvUOK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUPGRADE -X<SvUPGRADE> - -Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to -perform the upgrade if necessary. See C<svtype>. - - void SvUPGRADE(SV* sv, svtype type) - -=for hackers -Found in file sv.h - -=item SvUTF8 -X<SvUTF8> - -Returns a U32 value indicating the UTF-8 status of an SV. If things are set-up -properly, this indicates whether or not the SV contains UTF-8 encoded data. -Call this after SvPV() in case any call to string overloading updates the -internal flag. - - U32 SvUTF8(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUTF8_off -X<SvUTF8_off> - -Unsets the UTF-8 status of an SV (the data is not changed, just the flag). -Do not use frivolously. - - void SvUTF8_off(SV *sv) - -=for hackers -Found in file sv.h - -=item SvUTF8_on -X<SvUTF8_on> - -Turn on the UTF-8 status of an SV (the data is not changed, just the flag). -Do not use frivolously. - - void SvUTF8_on(SV *sv) - -=for hackers -Found in file sv.h - -=item SvUV -X<SvUV> - -Coerces the given SV to an unsigned integer and returns it. See C<SvUVx> -for a version which guarantees to evaluate sv only once. - - UV SvUV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUVX -X<SvUVX> - -Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C<SvUV()>. - - UV SvUVX(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUVx -X<SvUVx> - -Coerces the given SV to an unsigned integer and -returns it. Guarantees to C<sv> only once. Only -use this if C<sv> is an expression with side effects, -otherwise use the more efficient C<SvUV>. - - UV SvUVx(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUV_nomg -X<SvUV_nomg> - -Like C<SvUV> but doesn't process magic. - - UV SvUV_nomg(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUV_set -X<SvUV_set> - -Set the value of the UV pointer in sv to val. See C<SvIV_set>. - - void SvUV_set(SV* sv, UV val) - -=for hackers -Found in file sv.h - -=item SvVOK -X<SvVOK> - -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<sv_catpvn_nomg> - -Like C<sv_catpvn> but doesn't process magic. - - void sv_catpvn_nomg(SV* sv, const char* ptr, - STRLEN len) - -=for hackers -Found in file sv.h - -=item sv_catpv_nomg -X<sv_catpv_nomg> - -Like C<sv_catpv> but doesn't process magic. - - void sv_catpv_nomg(SV* sv, const char* ptr) - -=for hackers -Found in file sv.h - -=item sv_catsv_nomg -X<sv_catsv_nomg> - -Like C<sv_catsv> 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<sv_derived_from> - -Exactly like L</sv_derived_from_pv>, but doesn't take a C<flags> parameter. - - bool sv_derived_from(SV* sv, const char *const name) - -=for hackers -Found in file universal.c - -=item sv_derived_from_pv -X<sv_derived_from_pv> - -Exactly like L</sv_derived_from_pvn>, but takes a nul-terminated string -instead of a string/length pair. - - bool sv_derived_from_pv(SV* sv, - const char *const name, - U32 flags) - -=for hackers -Found in file universal.c - -=item sv_derived_from_pvn -X<sv_derived_from_pvn> - -Returns a boolean indicating whether the SV is derived from the specified class -I<at the C level>. To check derivation at the Perl level, call C<isa()> as a -normal Perl method. - -Currently, the only significant value for C<flags> is SVf_UTF8. - - bool sv_derived_from_pvn(SV* sv, - const char *const name, - const STRLEN len, U32 flags) - -=for hackers -Found in file universal.c - -=item sv_derived_from_sv -X<sv_derived_from_sv> - -Exactly like L</sv_derived_from_pvn>, but takes the name string in the form -of an SV instead of a string/length pair. - - bool sv_derived_from_sv(SV* sv, SV *namesv, - U32 flags) - -=for hackers -Found in file universal.c - -=item sv_does -X<sv_does> - -Like L</sv_does_pv>, but doesn't take a C<flags> parameter. - - bool sv_does(SV* sv, const char *const name) - -=for hackers -Found in file universal.c - -=item sv_does_pv -X<sv_does_pv> - -Like L</sv_does_sv>, but takes a nul-terminated string instead of an SV. - - bool sv_does_pv(SV* sv, const char *const name, - U32 flags) - -=for hackers -Found in file universal.c - -=item sv_does_pvn -X<sv_does_pvn> - -Like L</sv_does_sv>, but takes a string/length pair instead of an SV. - - bool sv_does_pvn(SV* sv, const char *const name, - const STRLEN len, U32 flags) - -=for hackers -Found in file universal.c - -=item sv_does_sv -X<sv_does_sv> - -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* sv, SV* namesv, U32 flags) - -=for hackers -Found in file universal.c - -=item sv_report_used -X<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_setsv_nomg -X<sv_setsv_nomg> - -Like C<sv_setsv> but doesn't process magic. - - void sv_setsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item sv_utf8_upgrade_nomg -X<sv_utf8_upgrade_nomg> - -Like sv_utf8_upgrade, but doesn't do magic on C<sv>. - - STRLEN sv_utf8_upgrade_nomg(NN SV *sv) - -=for hackers -Found in file sv.h - - -=back - -=head1 SV-Body Allocation - -=over 8 - -=item looks_like_number -X<looks_like_number> - -Test if the content of an SV looks like a number (or is a number). -C<Inf> and C<Infinity> are treated as numbers (so will not issue a -non-numeric warning), even if your atof() doesn't grok them. Get-magic is -ignored. - - I32 looks_like_number(SV *const sv) - -=for hackers -Found in file sv.c - -=item newRV_noinc -X<newRV_noinc> - -Creates an RV wrapper for an SV. The reference count for the original -SV is B<not> incremented. - - SV* newRV_noinc(SV *const sv) - -=for hackers -Found in file sv.c - -=item newSV -X<newSV> - -Creates a new SV. A non-zero C<len> 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<x>, a debug aid which allowed callers to identify themselves. -This aid has been superseded by a new build option, PERL_MEM_LOG (see -L<perlhacktips/PERL_MEM_LOG>). The older API is still there for use in XS -modules supporting older perls. - - SV* newSV(const STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVhek -X<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 *const hek) - -=for hackers -Found in file sv.c - -=item newSViv -X<newSViv> - -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. - - SV* newSViv(const IV i) - -=for hackers -Found in file sv.c - -=item newSVnv -X<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(const NV n) - -=for hackers -Found in file sv.c - -=item newSVpv -X<newSVpv> - -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. If C<len> is zero, Perl will compute the length using -strlen(). For efficiency, consider using C<newSVpvn> instead. - - SV* newSVpv(const char *const s, const STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvf -X<newSVpvf> - -Creates a new SV and initializes it with the string formatted like -C<sprintf>. - - SV* newSVpvf(const char *const pat, ...) - -=for hackers -Found in file sv.c - -=item newSVpvn -X<newSVpvn> - -Creates a new SV and copies a buffer into it, which may contain NUL characters -(C<\0>) and other binary data. The reference count for the SV is set to 1. -Note that if C<len> is zero, Perl will create a zero length (Perl) string. You -are responsible for ensuring that the source buffer is at least -C<len> bytes long. If the C<buffer> argument is NULL the new SV will be -undefined. - - SV* newSVpvn(const char *const s, const STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvn_flags -X<newSVpvn_flags> - -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. Note that if C<len> is zero, Perl will create a zero length -string. You are responsible for ensuring that the source string is at least -C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined. -Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>. -If C<SVs_TEMP> is set, then C<sv_2mortal()> is called on the result before -returning. If C<SVf_UTF8> is set, C<s> -is considered to be in UTF-8 and the -C<SVf_UTF8> flag will be set on the new SV. -C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as - - #define newSVpvn_utf8(s, len, u) \ - newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0) - - SV* newSVpvn_flags(const char *const s, - const STRLEN len, - const U32 flags) - -=for hackers -Found in file sv.c - -=item newSVpvn_share -X<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. If the C<hash> parameter -is non-zero, that value is used; otherwise the hash is computed. -The string's hash can later be retrieved from the SV -with the C<SvSHARED_HASH()> macro. 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<newSVpvs> - -Like C<newSVpvn>, 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_flags -X<newSVpvs_flags> - -Like C<newSVpvn_flags>, but takes a literal string instead of a string/length -pair. - - SV* newSVpvs_flags(const char* s, U32 flags) - -=for hackers -Found in file handy.h - -=item newSVpvs_share -X<newSVpvs_share> - -Like C<newSVpvn_share>, 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 newSVpv_share -X<newSVpv_share> - -Like C<newSVpvn_share>, but takes a nul-terminated string instead of a -string/length pair. - - SV* newSVpv_share(const char* s, U32 hash) - -=for hackers -Found in file sv.c - -=item newSVrv -X<newSVrv> - -Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then -it will be upgraded to one. If C<classname> 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 *const rv, - const char *const classname) - -=for hackers -Found in file sv.c - -=item newSVsv -X<newSVsv> - -Creates a new SV which is an exact duplicate of the original SV. -(Uses C<sv_setsv>.) - - SV* newSVsv(SV *const old) - -=for hackers -Found in file sv.c - -=item newSVuv -X<newSVuv> - -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. - - SV* newSVuv(const UV u) - -=for hackers -Found in file sv.c - -=item newSV_type -X<newSV_type> - -Creates a new SV, of the type specified. The reference count for the new SV -is set to 1. - - SV* newSV_type(const svtype type) - -=for hackers -Found in file sv.c - -=item sv_2bool -X<sv_2bool> - -This macro is only used by sv_true() or its macro equivalent, and only if -the latter's argument is neither SvPOK, SvIOK nor SvNOK. -It calls sv_2bool_flags with the SV_GMAGIC flag. - - bool sv_2bool(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_2bool_flags -X<sv_2bool_flags> - -This function is only used by sv_true() and friends, and only if -the latter's argument is neither SvPOK, SvIOK nor SvNOK. If the flags -contain SV_GMAGIC, then it does an mg_get() first. - - - bool sv_2bool_flags(SV *const sv, const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_2cv -X<sv_2cv> - -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<lref> are passed to gv_fetchsv. - - CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, - const I32 lref) - -=for hackers -Found in file sv.c - -=item sv_2io -X<sv_2io> - -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 -named after the PV if we're a string. - -'Get' magic is ignored on the sv passed in, but will be called on -C<SvRV(sv)> if sv is an RV. - - IO* sv_2io(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_2iv_flags -X<sv_2iv_flags> - -Return the integer value of an SV, doing any necessary string -conversion. If flags includes SV_GMAGIC, does an mg_get() first. -Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros. - - IV sv_2iv_flags(SV *const sv, const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_2mortal -X<sv_2mortal> - -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 -statement boundaries. SvTEMP() is turned on which means that the SV's -string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal> -and C<sv_mortalcopy>. - - SV* sv_2mortal(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_2nv_flags -X<sv_2nv_flags> - -Return the num value of an SV, doing any necessary string or integer -conversion. If flags includes SV_GMAGIC, does an mg_get() first. -Normally used via the C<SvNV(sv)> and C<SvNVx(sv)> macros. - - NV sv_2nv_flags(SV *const sv, const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_2pvbyte -X<sv_2pvbyte> - -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 -side-effect. - -Usually accessed via the C<SvPVbyte> macro. - - char* sv_2pvbyte(SV *sv, STRLEN *const lp) - -=for hackers -Found in file sv.c - -=item sv_2pvutf8 -X<sv_2pvutf8> - -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. - -Usually accessed via the C<SvPVutf8> macro. - - char* sv_2pvutf8(SV *sv, STRLEN *const lp) - -=for hackers -Found in file sv.c - -=item sv_2pv_flags -X<sv_2pv_flags> - -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 if necessary. Normally invoked via the C<SvPV_flags> macro. -C<sv_2pv()> and C<sv_2pv_nomg> usually end up here too. - - char* sv_2pv_flags(SV *const sv, STRLEN *const lp, - const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_2uv_flags -X<sv_2uv_flags> - -Return the unsigned integer value of an SV, doing any necessary string -conversion. If flags includes SV_GMAGIC, does an mg_get() first. -Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros. - - UV sv_2uv_flags(SV *const sv, const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_backoff -X<sv_backoff> - -Remove any string offset. You should normally use the C<SvOOK_off> macro -wrapper instead. - - int sv_backoff(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_bless -X<sv_bless> - -Blesses an SV into a specified package. The SV must be an RV. The package -must be designated by its stash (see C<gv_stashpv()>). The reference count -of the SV is unaffected. - - SV* sv_bless(SV *const sv, HV *const stash) - -=for hackers -Found in file sv.c - -=item sv_catpv -X<sv_catpv> - -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 -valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>. - - void sv_catpv(SV *const sv, const char* ptr) - -=for hackers -Found in file sv.c - -=item sv_catpvf -X<sv_catpvf> - -Processes its arguments like C<sprintf> and appends the formatted -output to an SV. If the appended data contains "wide" characters -(including, but not limited to, SVs with a UTF-8 PV formatted with %s, -and characters >255 formatted with %c), the original SV might get -upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See -C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be -valid UTF-8; if the original SV was bytes, the pattern should be too. - - void sv_catpvf(SV *const sv, const char *const pat, - ...) - -=for hackers -Found in file sv.c - -=item sv_catpvf_mg -X<sv_catpvf_mg> - -Like C<sv_catpvf>, but also handles 'set' magic. - - void sv_catpvf_mg(SV *const sv, - const char *const pat, ...) - -=for hackers -Found in file sv.c - -=item sv_catpvn -X<sv_catpvn> - -Concatenates the string onto the end of the string which is in the SV. The -C<len> indicates number of bytes to copy. If the SV has the UTF-8 -status set, then the bytes appended should be valid UTF-8. -Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>. - - void sv_catpvn(SV *dsv, const char *sstr, STRLEN len) - -=for hackers -Found in file sv.c - -=item sv_catpvn_flags -X<sv_catpvn_flags> - -Concatenates the string onto the end of the string which is in the SV. The -C<len> indicates number of bytes to copy. If the SV has the UTF-8 -status set, then the bytes appended should be valid UTF-8. -If C<flags> has the C<SV_SMAGIC> bit set, will -C<mg_set> on C<dsv> afterwards if appropriate. -C<sv_catpvn> and C<sv_catpvn_nomg> are implemented -in terms of this function. - - void sv_catpvn_flags(SV *const dstr, - const char *sstr, - const STRLEN len, - const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_catpvs -X<sv_catpvs> - -Like C<sv_catpvn>, but takes a literal string instead of a string/length pair. - - void sv_catpvs(SV* sv, const char* s) - -=for hackers -Found in file handy.h - -=item sv_catpvs_flags -X<sv_catpvs_flags> - -Like C<sv_catpvn_flags>, but takes a literal string instead of a -string/length pair. - - void sv_catpvs_flags(SV* sv, const char* s, - I32 flags) - -=for hackers -Found in file handy.h - -=item sv_catpvs_mg -X<sv_catpvs_mg> - -Like C<sv_catpvn_mg>, but takes a literal string instead of a -string/length pair. - - void sv_catpvs_mg(SV* sv, const char* s) - -=for hackers -Found in file handy.h - -=item sv_catpvs_nomg -X<sv_catpvs_nomg> - -Like C<sv_catpvn_nomg>, but takes a literal string instead of a -string/length pair. - - void sv_catpvs_nomg(SV* sv, const char* s) - -=for hackers -Found in file handy.h - -=item sv_catpv_flags -X<sv_catpv_flags> - -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 valid UTF-8. If C<flags> has the C<SV_SMAGIC> bit set, will C<mg_set> -on the modified SV if appropriate. - - void sv_catpv_flags(SV *dstr, const char *sstr, - const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_catpv_mg -X<sv_catpv_mg> - -Like C<sv_catpv>, but also handles 'set' magic. - - void sv_catpv_mg(SV *const sv, const char *const ptr) - -=for hackers -Found in file sv.c - -=item sv_catsv -X<sv_catsv> - -Concatenates the string from SV C<ssv> onto the end of the string in -SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but -not 'set' magic. See C<sv_catsv_mg>. - - void sv_catsv(SV *dstr, SV *sstr) - -=for hackers -Found in file sv.c - -=item sv_catsv_flags -X<sv_catsv_flags> - -Concatenates the string from SV C<ssv> onto the end of the string in -SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC> -bit set, will C<mg_get> on the C<ssv>, if appropriate, before -reading it. If the C<flags> contain C<SV_SMAGIC>, C<mg_set> will be -called on the modified SV afterward, if appropriate. C<sv_catsv> -and C<sv_catsv_nomg> are implemented in terms of this function. - - void sv_catsv_flags(SV *const dsv, SV *const ssv, - const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_chop -X<sv_chop> - -Efficient removal of characters from the beginning of the string buffer. -SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside -the string buffer. The C<ptr> becomes the first character of the adjusted -string. Uses the "OOK hack". - -Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer -refer to the same chunk of data. - -The unfortunate similarity of this function's name to that of Perl's C<chop> -operator is strictly coincidental. This function works from the left; -C<chop> works from the right. - - void sv_chop(SV *const sv, const char *const ptr) - -=for hackers -Found in file sv.c - -=item sv_clear -X<sv_clear> - -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<not> freed, although -its type is set to all 1's so that it won't inadvertently be assumed -to be live during global destruction etc. -This function should only be called when REFCNT is zero. Most of the time -you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>) -instead. - - void sv_clear(SV *const orig_sv) - -=for hackers -Found in file sv.c - -=item sv_cmp -X<sv_cmp> - -Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the -string in C<sv1> is less than, equal to, or greater than the string in -C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will -coerce its args to strings if necessary. See also C<sv_cmp_locale>. - - I32 sv_cmp(SV *const sv1, SV *const sv2) - -=for hackers -Found in file sv.c - -=item sv_cmp_flags -X<sv_cmp_flags> - -Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the -string in C<sv1> is less than, equal to, or greater than the string in -C<sv2>. Is UTF-8 and 'use bytes' aware and will coerce its args to strings -if necessary. If the flags include SV_GMAGIC, it handles get magic. See -also C<sv_cmp_locale_flags>. - - I32 sv_cmp_flags(SV *const sv1, SV *const sv2, - const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_cmp_locale -X<sv_cmp_locale> - -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 -if necessary. See also C<sv_cmp>. - - I32 sv_cmp_locale(SV *const sv1, SV *const sv2) - -=for hackers -Found in file sv.c - -=item sv_cmp_locale_flags -X<sv_cmp_locale_flags> - -Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and -'use bytes' aware and will coerce its args to strings if necessary. If the -flags contain SV_GMAGIC, it handles get magic. See also C<sv_cmp_flags>. - - I32 sv_cmp_locale_flags(SV *const sv1, - SV *const sv2, - const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_collxfrm -X<sv_collxfrm> - -This calls C<sv_collxfrm_flags> with the SV_GMAGIC flag. See -C<sv_collxfrm_flags>. - - char* sv_collxfrm(SV *const sv, STRLEN *const nxp) - -=for hackers -Found in file sv.c - -=item sv_collxfrm_flags -X<sv_collxfrm_flags> - -Add Collate Transform magic to an SV if it doesn't already have it. If the -flags contain SV_GMAGIC, it handles get-magic. - -Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the -scalar data of the variable, but transformed to such a format that a normal -memory comparison can be used to compare the data according to the locale -settings. - - char* sv_collxfrm_flags(SV *const sv, - STRLEN *const nxp, - I32 const flags) - -=for hackers -Found in file sv.c - -=item sv_copypv -X<sv_copypv> - -Copies a stringified representation of the source SV into the -destination SV. Automatically performs any necessary mg_get and -coercion of numeric values into strings. Guaranteed to preserve -UTF8 flag even from overloaded objects. Similar in nature to -sv_2pv[_flags] but operates directly on an SV instead of just the -string. Mostly uses sv_2pv_flags to do its work, except when that -would lose the UTF-8'ness of the PV. - - void sv_copypv(SV *const dsv, SV *const ssv) - -=for hackers -Found in file sv.c - -=item sv_dec -X<sv_dec> - -Auto-decrement of the value in the SV, doing string to numeric conversion -if necessary. Handles 'get' magic and operator overloading. - - void sv_dec(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_dec_nomg -X<sv_dec_nomg> - -Auto-decrement of the value in the SV, doing string to numeric conversion -if necessary. Handles operator overloading. Skips handling 'get' magic. - - void sv_dec_nomg(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_eq -X<sv_eq> - -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 -coerce its args to strings if necessary. - - I32 sv_eq(SV* sv1, SV* sv2) - -=for hackers -Found in file sv.c - -=item sv_eq_flags -X<sv_eq_flags> - -Returns a boolean indicating whether the strings in the two SVs are -identical. Is UTF-8 and 'use bytes' aware and coerces its args to strings -if necessary. If the flags include SV_GMAGIC, it handles get-magic, too. - - I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_force_normal_flags -X<sv_force_normal_flags> - -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; if we're a copy-on-write scalar, this is the on-write time when -we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set -then a copy-on-write scalar drops its PV buffer (if any) and becomes -SvPOK_off rather than making a copy. (Used where this -scalar is about to be set to some other value.) In addition, -the C<flags> parameter gets passed to C<sv_unref_flags()> -when unreffing. C<sv_force_normal> calls this function -with flags set to 0. - - void sv_force_normal_flags(SV *const sv, - const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_free -X<sv_free> - -Decrement an SV's reference count, and if it drops to zero, call -C<sv_clear> to invoke destructors and free up any memory used by -the body; finally, deallocate the SV's head itself. -Normally called via a wrapper macro C<SvREFCNT_dec>. - - void sv_free(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_gets -X<sv_gets> - -Get a line from the filehandle and store it into the SV, optionally -appending to the currently-stored string. - - char* sv_gets(SV *const sv, PerlIO *const fp, - I32 append) - -=for hackers -Found in file sv.c - -=item sv_grow -X<sv_grow> - -Expands the character buffer in the SV. If necessary, uses C<sv_unref> and -upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer. -Use the C<SvGROW> wrapper instead. - - char* sv_grow(SV *const sv, STRLEN newlen) - -=for hackers -Found in file sv.c - -=item sv_inc -X<sv_inc> - -Auto-increment of the value in the SV, doing string to numeric conversion -if necessary. Handles 'get' magic and operator overloading. - - void sv_inc(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_inc_nomg -X<sv_inc_nomg> - -Auto-increment of the value in the SV, doing string to numeric conversion -if necessary. Handles operator overloading. Skips handling 'get' magic. - - void sv_inc_nomg(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_insert -X<sv_insert> - -Inserts a string at the specified offset/length within the SV. Similar to -the Perl substr() function. Handles get magic. - - void sv_insert(SV *const bigstr, const STRLEN offset, - const STRLEN len, - const char *const little, - const STRLEN littlelen) - -=for hackers -Found in file sv.c - -=item sv_insert_flags -X<sv_insert_flags> - -Same as C<sv_insert>, but the extra C<flags> are passed to the -C<SvPV_force_flags> that applies to C<bigstr>. - - void sv_insert_flags(SV *const bigstr, - const STRLEN offset, - const STRLEN len, - const char *const little, - const STRLEN littlelen, - const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_isa -X<sv_isa> - -Returns a boolean indicating whether the SV is blessed into the specified -class. This does not check for subtypes; use C<sv_derived_from> to verify -an inheritance relationship. - - int sv_isa(SV* sv, const char *const name) - -=for hackers -Found in file sv.c - -=item sv_isobject -X<sv_isobject> - -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 -will return false. - - int sv_isobject(SV* sv) - -=for hackers -Found in file sv.c - -=item sv_len -X<sv_len> - -Returns the length of the string in the SV. Handles magic and type -coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot. - - STRLEN sv_len(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_len_utf8 -X<sv_len_utf8> - -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. - - STRLEN sv_len_utf8(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_magic -X<sv_magic> - -Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if -necessary, then adds a new magic item of type C<how> to the head of the -magic list. - -See C<sv_magicext> (which C<sv_magic> now calls) for a description of the -handling of the C<name> and C<namlen> arguments. - -You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also -to add more than one instance of the same 'how'. - - void sv_magic(SV *const sv, SV *const obj, - const int how, const char *const name, - const I32 namlen) - -=for hackers -Found in file sv.c - -=item sv_magicext -X<sv_magicext> - -Adds magic to an SV, upgrading it if necessary. Applies the -supplied vtable and returns a pointer to the magic added. - -Note that C<sv_magicext> will allow things that C<sv_magic> will not. -In particular, you can add magic to SvREADONLY SVs, and add more than -one instance of the same 'how'. - -If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is -stored, if C<namlen> is zero then C<name> is stored as-is and - as another -special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed -to contain an C<SV*> and is stored as-is with its REFCNT incremented. - -(This is now used as a subroutine by C<sv_magic>.) - - MAGIC * sv_magicext(SV *const sv, SV *const obj, - const int how, - const MGVTBL *const vtbl, - const char *const name, - const I32 namlen) - -=for hackers -Found in file sv.c - -=item sv_mortalcopy -X<sv_mortalcopy> - -Creates a new SV which is a copy of the original SV (using C<sv_setsv>). -The new SV is marked as mortal. It will be destroyed "soon", either by an -explicit call to FREETMPS, or by an implicit call at places such as -statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>. - - SV* sv_mortalcopy(SV *const oldsv) - -=for hackers -Found in file sv.c - -=item sv_newmortal -X<sv_newmortal> - -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 -FREETMPS, or by an implicit call at places such as statement boundaries. -See also C<sv_mortalcopy> and C<sv_2mortal>. - - SV* sv_newmortal() - -=for hackers -Found in file sv.c - -=item sv_newref -X<sv_newref> - -Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper -instead. - - SV* sv_newref(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_pos_b2u -X<sv_pos_b2u> - -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. -Handles magic and type coercion. - - void sv_pos_b2u(SV *const sv, I32 *const offsetp) - -=for hackers -Found in file sv.c - -=item sv_pos_u2b -X<sv_pos_u2b> - -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 -lenp is non-zero, it does the same to lenp, but this time starting from -the offset, rather than from the start of the string. Handles magic and -type coercion. - -Use C<sv_pos_u2b_flags> in preference, which correctly handles strings longer -than 2Gb. - - void sv_pos_u2b(SV *const sv, I32 *const offsetp, - I32 *const lenp) - -=for hackers -Found in file sv.c - -=item sv_pos_u2b_flags -X<sv_pos_u2b_flags> - -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 -lenp is non-zero, it does the same to lenp, but this time starting from -the offset, rather than from the start -of the string. Handles type coercion. -I<flags> is passed to C<SvPV_flags>, and usually should be -C<SV_GMAGIC|SV_CONST_RETURN> to handle magic. - - STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset, - STRLEN *const lenp, U32 flags) - -=for hackers -Found in file sv.c - -=item sv_pvbyten_force -X<sv_pvbyten_force> - -The backend for the C<SvPVbytex_force> macro. Always use the macro -instead. - - char* sv_pvbyten_force(SV *const sv, STRLEN *const lp) - -=for hackers -Found in file sv.c - -=item sv_pvn_force -X<sv_pvn_force> - -Get a sensible string out of the SV somehow. -A private implementation of the C<SvPV_force> macro for compilers which -can't cope with complex macro expressions. Always use the macro instead. - - char* sv_pvn_force(SV* sv, STRLEN* lp) - -=for hackers -Found in file sv.c - -=item sv_pvn_force_flags -X<sv_pvn_force_flags> - -Get a sensible string out of the SV somehow. -If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if -appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are -implemented in terms of this function. -You normally want to use the various wrapper macros instead: see -C<SvPV_force> and C<SvPV_force_nomg> - - char* sv_pvn_force_flags(SV *const sv, - STRLEN *const lp, - const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_pvutf8n_force -X<sv_pvutf8n_force> - -The backend for the C<SvPVutf8x_force> macro. Always use the macro -instead. - - char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp) - -=for hackers -Found in file sv.c - -=item sv_reftype -X<sv_reftype> - -Returns a string describing what the SV is a reference to. - - const char* sv_reftype(const SV *const sv, const int ob) - -=for hackers -Found in file sv.c - -=item sv_replace -X<sv_replace> - -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 -and inherits its flags; however, the target keeps any magic it owns, -and any magic in the source is discarded. -Note that this is a rather specialist SV copying operation; most of the -time you'll want to use C<sv_setsv> or one of its many macro front-ends. - - void sv_replace(SV *const sv, SV *const nsv) - -=for hackers -Found in file sv.c - -=item sv_reset -X<sv_reset> - -Underlying implementation for the C<reset> Perl function. -Note that the perl-level function is vaguely deprecated. - - void sv_reset(const char* s, HV *const stash) - -=for hackers -Found in file sv.c - -=item sv_rvweaken -X<sv_rvweaken> - -Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the -referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and -push a back-reference to this RV onto the array of backreferences -associated with that magic. If the RV is magical, set magic will be -called after the RV is cleared. - - SV* sv_rvweaken(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_setiv -X<sv_setiv> - -Copies an integer into the given SV, upgrading first if necessary. -Does not handle 'set' magic. See also C<sv_setiv_mg>. - - void sv_setiv(SV *const sv, const IV num) - -=for hackers -Found in file sv.c - -=item sv_setiv_mg -X<sv_setiv_mg> - -Like C<sv_setiv>, but also handles 'set' magic. - - void sv_setiv_mg(SV *const sv, const IV i) - -=for hackers -Found in file sv.c - -=item sv_setnv -X<sv_setnv> - -Copies a double into the given SV, upgrading first if necessary. -Does not handle 'set' magic. See also C<sv_setnv_mg>. - - void sv_setnv(SV *const sv, const NV num) - -=for hackers -Found in file sv.c - -=item sv_setnv_mg -X<sv_setnv_mg> - -Like C<sv_setnv>, but also handles 'set' magic. - - void sv_setnv_mg(SV *const sv, const NV num) - -=for hackers -Found in file sv.c - -=item sv_setpv -X<sv_setpv> - -Copies a string into an SV. The string must be null-terminated. Does not -handle 'set' magic. See C<sv_setpv_mg>. - - void sv_setpv(SV *const sv, const char *const ptr) - -=for hackers -Found in file sv.c - -=item sv_setpvf -X<sv_setpvf> - -Works like C<sv_catpvf> but copies the text into the SV instead of -appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>. - - void sv_setpvf(SV *const sv, const char *const pat, - ...) - -=for hackers -Found in file sv.c - -=item sv_setpvf_mg -X<sv_setpvf_mg> - -Like C<sv_setpvf>, but also handles 'set' magic. - - void sv_setpvf_mg(SV *const sv, - const char *const pat, ...) - -=for hackers -Found in file sv.c - -=item sv_setpviv -X<sv_setpviv> - -Copies an integer into the given SV, also updating its string value. -Does not handle 'set' magic. See C<sv_setpviv_mg>. - - void sv_setpviv(SV *const sv, const IV num) - -=for hackers -Found in file sv.c - -=item sv_setpviv_mg -X<sv_setpviv_mg> - -Like C<sv_setpviv>, but also handles 'set' magic. - - void sv_setpviv_mg(SV *const sv, const IV iv) - -=for hackers -Found in file sv.c - -=item sv_setpvn -X<sv_setpvn> - -Copies a string into an SV. The C<len> parameter indicates the number of -bytes to be copied. If the C<ptr> argument is NULL the SV will become -undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>. - - void sv_setpvn(SV *const sv, const char *const ptr, - const STRLEN len) - -=for hackers -Found in file sv.c - -=item sv_setpvn_mg -X<sv_setpvn_mg> - -Like C<sv_setpvn>, but also handles 'set' magic. - - void sv_setpvn_mg(SV *const sv, - const char *const ptr, - const STRLEN len) - -=for hackers -Found in file sv.c - -=item sv_setpvs -X<sv_setpvs> - -Like C<sv_setpvn>, 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_setpvs_mg -X<sv_setpvs_mg> - -Like C<sv_setpvn_mg>, but takes a literal string instead of a -string/length pair. - - void sv_setpvs_mg(SV* sv, const char* s) - -=for hackers -Found in file handy.h - -=item sv_setpv_mg -X<sv_setpv_mg> - -Like C<sv_setpv>, but also handles 'set' magic. - - void sv_setpv_mg(SV *const sv, const char *const ptr) - -=for hackers -Found in file sv.c - -=item sv_setref_iv -X<sv_setref_iv> - -Copies an integer into a new SV, optionally blessing the SV. The C<rv> -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. The C<classname> argument indicates the package for the -blessing. Set C<classname> to C<NULL> 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 *const rv, - const char *const classname, - const IV iv) - -=for hackers -Found in file sv.c - -=item sv_setref_nv -X<sv_setref_nv> - -Copies a double into a new SV, optionally blessing the SV. The C<rv> -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. The C<classname> argument indicates the package for the -blessing. Set C<classname> to C<NULL> 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 *const rv, - const char *const classname, - const NV nv) - -=for hackers -Found in file sv.c - -=item sv_setref_pv -X<sv_setref_pv> - -Copies a pointer into a new SV, optionally blessing the SV. The C<rv> -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed -into the SV. The C<classname> argument indicates the package for the -blessing. Set C<classname> to C<NULL> 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 -objects will become corrupted by the pointer copy process. - -Note that C<sv_setref_pvn> copies the string while this copies the pointer. - - SV* sv_setref_pv(SV *const rv, - const char *const classname, - void *const pv) - -=for hackers -Found in file sv.c - -=item sv_setref_pvn -X<sv_setref_pvn> - -Copies a string into a new SV, optionally blessing the SV. The length of the -string must be specified with C<n>. The C<rv> argument will be upgraded to -an RV. That RV will be modified to point to the new SV. The C<classname> -argument indicates the package for the blessing. Set C<classname> to -C<NULL> to avoid the blessing. The new SV will have a reference count -of 1, and the RV will be returned. - -Note that C<sv_setref_pv> copies the pointer while this copies the string. - - SV* sv_setref_pvn(SV *const rv, - const char *const classname, - const char *const pv, - const STRLEN n) - -=for hackers -Found in file sv.c - -=item sv_setref_pvs -X<sv_setref_pvs> - -Like C<sv_setref_pvn>, but takes a literal string instead of a -string/length pair. - - SV * sv_setref_pvs(const char* s) - -=for hackers -Found in file handy.h - -=item sv_setref_uv -X<sv_setref_uv> - -Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv> -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. The C<classname> argument indicates the package for the -blessing. Set C<classname> to C<NULL> 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 *const rv, - const char *const classname, - const UV uv) - -=for hackers -Found in file sv.c - -=item sv_setsv -X<sv_setsv> - -Copies the contents of the source SV C<ssv> into the destination SV -C<dsv>. The source SV may be destroyed if it is mortal, so don't use this -function if the source SV needs to be reused. Does not handle 'set' magic. -Loosely speaking, it performs a copy-by-value, obliterating any previous -content of the destination. - -You probably want to use one of the assortment of wrappers, such as -C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and -C<SvSetMagicSV_nosteal>. - - void sv_setsv(SV *dstr, SV *sstr) - -=for hackers -Found in file sv.c - -=item sv_setsv_flags -X<sv_setsv_flags> - -Copies the contents of the source SV C<ssv> into the destination SV -C<dsv>. The source SV may be destroyed if it is mortal, so don't use this -function if the source SV needs to be reused. Does not handle 'set' magic. -Loosely speaking, it performs a copy-by-value, obliterating any previous -content of the destination. -If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on -C<ssv> if appropriate, else not. If the C<flags> -parameter has the C<NOSTEAL> bit set then the -buffers of temps will not be stolen. <sv_setsv> -and C<sv_setsv_nomg> are implemented in terms of this function. - -You probably want to use one of the assortment of wrappers, such as -C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and -C<SvSetMagicSV_nosteal>. - -This is the primary function for copying scalars, and most other -copy-ish functions and macros use this underneath. - - void sv_setsv_flags(SV *dstr, SV *sstr, - const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_setsv_mg -X<sv_setsv_mg> - -Like C<sv_setsv>, but also handles 'set' magic. - - void sv_setsv_mg(SV *const dstr, SV *const sstr) - -=for hackers -Found in file sv.c - -=item sv_setuv -X<sv_setuv> - -Copies an unsigned integer into the given SV, upgrading first if necessary. -Does not handle 'set' magic. See also C<sv_setuv_mg>. - - void sv_setuv(SV *const sv, const UV num) - -=for hackers -Found in file sv.c - -=item sv_setuv_mg -X<sv_setuv_mg> - -Like C<sv_setuv>, but also handles 'set' magic. - - void sv_setuv_mg(SV *const sv, const UV u) - -=for hackers -Found in file sv.c - -=item sv_tainted -X<sv_tainted> - -Test an SV for taintedness. Use C<SvTAINTED> instead. - - bool sv_tainted(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_true -X<sv_true> - -Returns true if the SV has a true value by Perl's rules. -Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may -instead use an in-line version. - - I32 sv_true(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_unmagic -X<sv_unmagic> - -Removes all magic of type C<type> from an SV. - - int sv_unmagic(SV *const sv, const int type) - -=for hackers -Found in file sv.c - -=item sv_unmagicext -X<sv_unmagicext> - -Removes all magic of type C<type> with the specified C<vtbl> from an SV. - - int sv_unmagicext(SV *const sv, const int type, - MGVTBL *vtbl) - -=for hackers -Found in file sv.c - -=item sv_unref_flags -X<sv_unref_flags> - -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<newSVrv>. The C<cflags> argument can contain -C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented -(otherwise the decrementing is conditional on the reference count being -different from one or the reference being a readonly SV). -See C<SvROK_off>. - - void sv_unref_flags(SV *const ref, const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_untaint -X<sv_untaint> - -Untaint an SV. Use C<SvTAINTED_off> instead. - - void sv_untaint(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_upgrade -X<sv_upgrade> - -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. -It croaks if the SV is already in a more complex form than requested. You -generally want to use the C<SvUPGRADE> macro wrapper, which checks the type -before calling C<sv_upgrade>, and hence does not croak. See also -C<svtype>. - - void sv_upgrade(SV *const sv, svtype new_type) - -=for hackers -Found in file sv.c - -=item sv_usepvn_flags -X<sv_usepvn_flags> - -Tells an SV to use C<ptr> 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<ptr> should point to memory that was allocated -by C<malloc>. It must be the start of a mallocked block -of memory, and not a pointer to the middle of it. The -string length, C<len>, must be supplied. By default -this function will realloc (i.e. move) the memory pointed to by C<ptr>, -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. - -If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> & -SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc -will be skipped (i.e. the buffer is actually at least 1 byte longer than -C<len>, and already meets the requirements for storing in C<SvPVX>). - - void sv_usepvn_flags(SV *const sv, char* ptr, - const STRLEN len, - const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_utf8_decode -X<sv_utf8_decode> - -If the PV of the SV is an octet sequence in UTF-8 -and contains a multiple-byte character, the C<SvUTF8> flag is turned on -so that it looks like a character. If the PV contains only single-byte -characters, the C<SvUTF8> flag stays off. -Scans PV for validity and returns false if the PV is invalid UTF-8. - -NOTE: this function is experimental and may change or be -removed without notice. - - bool sv_utf8_decode(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_utf8_downgrade -X<sv_utf8_downgrade> - -Attempts to convert the PV of an SV from characters to bytes. -If the PV contains a character that cannot fit -in a byte, this conversion will fail; -in this case, either returns false or, if C<fail_ok> is not -true, croaks. - -This is not as a general purpose Unicode to byte encoding interface: -use the Encode extension for that. - -NOTE: this function is experimental and may change or be -removed without notice. - - bool sv_utf8_downgrade(SV *const sv, - const bool fail_ok) - -=for hackers -Found in file sv.c - -=item sv_utf8_encode -X<sv_utf8_encode> - -Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8> -flag off so that it looks like octets again. - - void sv_utf8_encode(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_utf8_upgrade -X<sv_utf8_upgrade> - -Converts the PV of an SV to its UTF-8-encoded form. -Forces the SV to string form if it is not already. -Will C<mg_get> on C<sv> if appropriate. -Always sets the SvUTF8 flag to avoid future validity checks even -if the whole string is the same in UTF-8 as not. -Returns the number of bytes in the converted string - -This is not as a general purpose byte encoding to Unicode interface: -use the Encode extension for that. - - STRLEN sv_utf8_upgrade(SV *sv) - -=for hackers -Found in file sv.c - -=item sv_utf8_upgrade_flags -X<sv_utf8_upgrade_flags> - -Converts the PV of an SV to its UTF-8-encoded form. -Forces the SV to string form if it is not already. -Always sets the SvUTF8 flag to avoid future validity checks even -if all the bytes are invariant in UTF-8. -If C<flags> has C<SV_GMAGIC> bit set, -will C<mg_get> on C<sv> if appropriate, else not. -Returns the number of bytes in the converted string -C<sv_utf8_upgrade> and -C<sv_utf8_upgrade_nomg> are implemented in terms of this function. - -This is not as a general purpose byte encoding to Unicode interface: -use the Encode extension for that. - - STRLEN sv_utf8_upgrade_flags(SV *const sv, - const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_utf8_upgrade_nomg -X<sv_utf8_upgrade_nomg> - -Like sv_utf8_upgrade, but doesn't do magic on C<sv>. - - STRLEN sv_utf8_upgrade_nomg(SV *sv) - -=for hackers -Found in file sv.c - -=item sv_vcatpvf -X<sv_vcatpvf> - -Processes its arguments like C<vsprintf> and appends the formatted output -to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>. - -Usually used via its frontend C<sv_catpvf>. - - void sv_vcatpvf(SV *const sv, const char *const pat, - va_list *const args) - -=for hackers -Found in file sv.c - -=item sv_vcatpvfn -X<sv_vcatpvfn> - -Processes its arguments like C<vsprintf> and appends the formatted output -to an SV. Uses an array of SVs if the C style variable argument list is -missing (NULL). When running with taint checks enabled, indicates via -C<maybe_tainted> if results are untrustworthy (often due to the use of -locales). - -Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>. - - void sv_vcatpvfn(SV *const sv, const char *const pat, - const STRLEN patlen, - va_list *const args, - SV **const svargs, const I32 svmax, - bool *const maybe_tainted) - -=for hackers -Found in file sv.c - -=item sv_vcatpvf_mg -X<sv_vcatpvf_mg> - -Like C<sv_vcatpvf>, but also handles 'set' magic. - -Usually used via its frontend C<sv_catpvf_mg>. - - void sv_vcatpvf_mg(SV *const sv, - const char *const pat, - va_list *const args) - -=for hackers -Found in file sv.c - -=item sv_vsetpvf -X<sv_vsetpvf> - -Works like C<sv_vcatpvf> but copies the text into the SV instead of -appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>. - -Usually used via its frontend C<sv_setpvf>. - - void sv_vsetpvf(SV *const sv, const char *const pat, - va_list *const args) - -=for hackers -Found in file sv.c - -=item sv_vsetpvfn -X<sv_vsetpvfn> - -Works like C<sv_vcatpvfn> but copies the text into the SV instead of -appending it. - -Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>. - - void sv_vsetpvfn(SV *const sv, const char *const pat, - const STRLEN patlen, - va_list *const args, - SV **const svargs, const I32 svmax, - bool *const maybe_tainted) - -=for hackers -Found in file sv.c - -=item sv_vsetpvf_mg -X<sv_vsetpvf_mg> - -Like C<sv_vsetpvf>, but also handles 'set' magic. - -Usually used via its frontend C<sv_setpvf_mg>. - - void sv_vsetpvf_mg(SV *const sv, - const char *const pat, - va_list *const args) - -=for hackers -Found in file sv.c - - -=back - -=head1 Unicode Support - -=over 8 - -=item bytes_cmp_utf8 -X<bytes_cmp_utf8> - -Compares the sequence of characters (stored as octets) in C<b>, C<blen> with the -sequence of characters (stored as UTF-8) in C<u>, C<ulen>. Returns 0 if they are -equal, -1 or -2 if the first string is less than the second string, +1 or +2 -if the first string is greater than the second string. - --1 or +1 is returned if the shorter string was identical to the start of the -longer string. -2 or +2 is returned if the was a difference between characters -within the strings. - - int bytes_cmp_utf8(const U8 *b, STRLEN blen, - const U8 *u, STRLEN ulen) - -=for hackers -Found in file utf8.c - -=item bytes_from_utf8 -X<bytes_from_utf8> - -Converts a string C<s> of length C<len> from UTF-8 into native byte encoding. -Unlike L</utf8_to_bytes> but like L</bytes_to_utf8>, returns a pointer to -the newly-created string, and updates C<len> to contain the new -length. Returns the original string if no conversion occurs, C<len> -is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to -0 if C<s> is converted or consisted entirely of characters that are invariant -in utf8 (i.e., US-ASCII on non-EBCDIC machines). - -NOTE: this function is experimental and may change or be -removed without notice. - - U8* bytes_from_utf8(const U8 *s, STRLEN *len, - bool *is_utf8) - -=for hackers -Found in file utf8.c - -=item bytes_to_utf8 -X<bytes_to_utf8> - -Converts a string C<s> of length C<len> bytes from the native encoding into -UTF-8. -Returns a pointer to the newly-created string, and sets C<len> to -reflect the new length in bytes. - -A NUL character will be written after the end of the string. - -If you want to convert to UTF-8 from encodings other than -the native (Latin1 or EBCDIC), -see L</sv_recode_to_utf8>(). - -NOTE: this function is experimental and may change or be -removed without notice. - - U8* bytes_to_utf8(const U8 *s, STRLEN *len) - -=for hackers -Found in file utf8.c - -=item foldEQ_utf8 -X<foldEQ_utf8> - -Returns true if the leading portions of the strings C<s1> and C<s2> (either or both -of which may be in UTF-8) are the same case-insensitively; false otherwise. -How far into the strings to compare is determined by other input parameters. - -If C<u1> is true, the string C<s1> is assumed to be in UTF-8-encoded Unicode; -otherwise it is assumed to be in native 8-bit encoding. Correspondingly for C<u2> -with respect to C<s2>. - -If the byte length C<l1> is non-zero, it says how far into C<s1> to check for fold -equality. In other words, C<s1>+C<l1> will be used as a goal to reach. The -scan will not be considered to be a match unless the goal is reached, and -scanning won't continue past that goal. Correspondingly for C<l2> with respect to -C<s2>. - -If C<pe1> is non-NULL and the pointer it points to is not NULL, that pointer is -considered an end pointer beyond which scanning of C<s1> will not continue under -any circumstances. This means that if both C<l1> and C<pe1> are specified, and -C<pe1> -is less than C<s1>+C<l1>, the match will never be successful because it can -never -get as far as its goal (and in fact is asserted against). Correspondingly for -C<pe2> with respect to C<s2>. - -At least one of C<s1> and C<s2> must have a goal (at least one of C<l1> and -C<l2> must be non-zero), and if both do, both have to be -reached for a successful match. Also, if the fold of a character is multiple -characters, all of them must be matched (see tr21 reference below for -'folding'). - -Upon a successful match, if C<pe1> is non-NULL, -it will be set to point to the beginning of the I<next> character of C<s1> -beyond what was matched. Correspondingly for C<pe2> and C<s2>. - -For case-insensitiveness, the "casefolding" of Unicode is used -instead of upper/lowercasing both the characters, see -L<http://www.unicode.org/unicode/reports/tr21/> (Case Mappings). - - I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, - bool u1, const char *s2, char **pe2, - UV l2, bool u2) - -=for hackers -Found in file utf8.c - -=item is_ascii_string -X<is_ascii_string> - -Returns true if the first C<len> bytes of the string C<s> are the same whether -or not the string is encoded in UTF-8 (or UTF-EBCDIC on EBCDIC machines). That -is, if they are invariant. On ASCII-ish machines, only ASCII characters -fit this definition, hence the function's name. - -If C<len> is 0, it will be calculated using C<strlen(s)>. - -See also L</is_utf8_string>(), L</is_utf8_string_loclen>(), and L</is_utf8_string_loc>(). - - bool is_ascii_string(const U8 *s, STRLEN len) - -=for hackers -Found in file utf8.c - -=item is_utf8_char -X<is_utf8_char> - -DEPRECATED! - -Tests if some arbitrary number of bytes begins in a valid UTF-8 -character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines) -character is a valid UTF-8 character. The actual number of bytes in the UTF-8 -character will be returned if it is valid, otherwise 0. - -This function is deprecated due to the possibility that malformed input could -cause reading beyond the end of the input buffer. Use L</is_utf8_char_buf> -instead. - - STRLEN is_utf8_char(const U8 *s) - -=for hackers -Found in file utf8.c - -=item is_utf8_char_buf -X<is_utf8_char_buf> - -Returns the number of bytes that comprise the first UTF-8 encoded character in -buffer C<buf>. C<buf_end> should point to one position beyond the end of the -buffer. 0 is returned if C<buf> does not point to a complete, valid UTF-8 -encoded character. - -Note that an INVARIANT character (i.e. ASCII on non-EBCDIC -machines) is a valid UTF-8 character. - - STRLEN is_utf8_char_buf(const U8 *buf, - const U8 *buf_end) - -=for hackers -Found in file utf8.c - -=item is_utf8_string -X<is_utf8_string> - -Returns true if the first C<len> bytes of string C<s> form a valid -UTF-8 string, false otherwise. If C<len> is 0, it will be calculated -using C<strlen(s)> (which means if you use this option, that C<s> has to have a -terminating NUL byte). Note that all characters being ASCII constitute 'a -valid UTF-8 string'. - -See also L</is_ascii_string>(), L</is_utf8_string_loclen>(), and L</is_utf8_string_loc>(). - - bool is_utf8_string(const U8 *s, STRLEN len) - -=for hackers -Found in file utf8.c - -=item is_utf8_string_loc -X<is_utf8_string_loc> - -Like L</is_utf8_string> but stores the location of the failure (in the -case of "utf8ness failure") or the location C<s>+C<len> (in the case of -"utf8ness success") in the C<ep>. - -See also L</is_utf8_string_loclen>() and L</is_utf8_string>(). - - bool is_utf8_string_loc(const U8 *s, STRLEN len, - const U8 **p) - -=for hackers -Found in file utf8.c - -=item is_utf8_string_loclen -X<is_utf8_string_loclen> - -Like L</is_utf8_string>() but stores the location of the failure (in the -case of "utf8ness failure") or the location C<s>+C<len> (in the case of -"utf8ness success") in the C<ep>, and the number of UTF-8 -encoded characters in the C<el>. - -See also L</is_utf8_string_loc>() and L</is_utf8_string>(). - - bool is_utf8_string_loclen(const U8 *s, STRLEN len, - const U8 **ep, STRLEN *el) - -=for hackers -Found in file utf8.c - -=item pv_uni_display -X<pv_uni_display> - -Build to the scalar C<dsv> a displayable version of the string C<spv>, -length C<len>, the displayable version being at most C<pvlim> bytes long -(if longer, the rest is truncated and "..." will be appended). - -The C<flags> argument can have UNI_DISPLAY_ISPRINT set to display -isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH -to display the \\[nrfta\\] as the backslashed versions (like '\n') -(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). -UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both -UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on. - -The pointer to the PV of the C<dsv> is returned. - - char* pv_uni_display(SV *dsv, const U8 *spv, - STRLEN len, STRLEN pvlim, - UV flags) - -=for hackers -Found in file utf8.c - -=item sv_cat_decode -X<sv_cat_decode> - -The encoding is assumed to be an Encode object, the PV of the ssv is -assumed to be octets in that encoding and decoding the input starts -from the position which (PV + *offset) pointed to. The dsv will be -concatenated the decoded UTF-8 string from ssv. Decoding will terminate -when the string tstr appears in decoding output or the input ends on -the PV of the ssv. The value which the offset points will be modified -to the last input position on the ssv. - -Returns TRUE if the terminator was found, else returns FALSE. - - bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, - int *offset, char* tstr, int tlen) - -=for hackers -Found in file sv.c - -=item sv_recode_to_utf8 -X<sv_recode_to_utf8> - -The encoding is assumed to be an Encode object, on entry the PV -of the sv is assumed to be octets in that encoding, and the sv -will be converted into Unicode (and UTF-8). - -If the sv already is UTF-8 (or if it is not POK), or if the encoding -is not a reference, nothing is done to the sv. If the encoding is not -an C<Encode::XS> Encoding object, bad things will happen. -(See F<lib/encoding.pm> and L<Encode>.) - -The PV of the sv is returned. - - char* sv_recode_to_utf8(SV* sv, SV *encoding) - -=for hackers -Found in file sv.c - -=item sv_uni_display -X<sv_uni_display> - -Build to the scalar C<dsv> a displayable version of the scalar C<sv>, -the displayable version being at most C<pvlim> bytes long -(if longer, the rest is truncated and "..." will be appended). - -The C<flags> argument is as in L</pv_uni_display>(). - -The pointer to the PV of the C<dsv> is returned. - - char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, - UV flags) - -=for hackers -Found in file utf8.c - -=item to_utf8_case -X<to_utf8_case> - -The C<p> contains the pointer to the UTF-8 string encoding -the character that is being converted. This routine assumes that the character -at C<p> is well-formed. - -The C<ustrp> is a pointer to the character buffer to put the -conversion result to. The C<lenp> is a pointer to the length -of the result. - -The C<swashp> is a pointer to the swash to use. - -Both the special and normal mappings are stored in F<lib/unicore/To/Foo.pl>, -and loaded by SWASHNEW, using F<lib/utf8_heavy.pl>. The C<special> (usually, -but not always, a multicharacter mapping), is tried first. - -The C<special> is a string like "utf8::ToSpecLower", which means the -hash %utf8::ToSpecLower. The access to the hash is through -Perl_to_utf8_case(). - -The C<normal> is a string like "ToLower" which means the swash -%utf8::ToLower. - - 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<to_utf8_fold> - -Convert the UTF-8 encoded character at C<p> to its foldcase version and -store that in UTF-8 in C<ustrp> and its length in bytes in C<lenp>. Note -that the C<ustrp> needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the -foldcase version may be longer than the original character (up to -three characters). - -The first character of the foldcased version is returned -(but note, as explained above, that there may be more.) - -The character at C<p> is assumed by this routine to be well-formed. - - UV to_utf8_fold(const U8 *p, U8* ustrp, - STRLEN *lenp) - -=for hackers -Found in file utf8.c - -=item to_utf8_lower -X<to_utf8_lower> - -Convert the UTF-8 encoded character at C<p> to its lowercase version and -store that in UTF-8 in ustrp and its length in bytes in C<lenp>. Note -that the C<ustrp> needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the -lowercase version may be longer than the original character. - -The first character of the lowercased version is returned -(but note, as explained above, that there may be more.) - -The character at C<p> is assumed by this routine to be well-formed. - - UV to_utf8_lower(const U8 *p, U8* ustrp, - STRLEN *lenp) - -=for hackers -Found in file utf8.c - -=item to_utf8_title -X<to_utf8_title> - -Convert the UTF-8 encoded character at C<p> to its titlecase version and -store that in UTF-8 in C<ustrp> and its length in bytes in C<lenp>. Note -that the C<ustrp> needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the -titlecase version may be longer than the original character. - -The first character of the titlecased version is returned -(but note, as explained above, that there may be more.) - -The character at C<p> is assumed by this routine to be well-formed. - - UV to_utf8_title(const U8 *p, U8* ustrp, - STRLEN *lenp) - -=for hackers -Found in file utf8.c - -=item to_utf8_upper -X<to_utf8_upper> - -Convert the UTF-8 encoded character at C<p> to its uppercase version and -store that in UTF-8 in C<ustrp> and its length in bytes in C<lenp>. Note -that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since -the uppercase version may be longer than the original character. - -The first character of the uppercased version is returned -(but note, as explained above, that there may be more.) - -The character at C<p> is assumed by this routine to be well-formed. - - UV to_utf8_upper(const U8 *p, U8* ustrp, - STRLEN *lenp) - -=for hackers -Found in file utf8.c - -=item utf8n_to_uvchr -X<utf8n_to_uvchr> - -Returns the native character value of the first character in the string -C<s> -which is assumed to be in UTF-8 encoding; C<retlen> will be set to the -length, in bytes, of that character. - -C<length> and C<flags> are the same as L</utf8n_to_uvuni>(). - - 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<utf8n_to_uvuni> - -Bottom level UTF-8 decode routine. -Returns the code point value of the first character in the string C<s>, -which is assumed to be in UTF-8 (or UTF-EBCDIC) encoding, and no longer than -C<curlen> bytes; C<*retlen> (if C<retlen> isn't NULL) will be set to -the length, in bytes, of that character. - -The value of C<flags> determines the behavior when C<s> does not point to a -well-formed UTF-8 character. If C<flags> is 0, when a malformation is found, -zero is returned and C<*retlen> is set so that (S<C<s> + C<*retlen>>) is the -next possible position in C<s> that could begin a non-malformed character. -Also, if UTF-8 warnings haven't been lexically disabled, a warning is raised. - -Various ALLOW flags can be set in C<flags> to allow (and not warn on) -individual types of malformations, such as the sequence being overlong (that -is, when there is a shorter sequence that can express the same code point; -overlong sequences are expressly forbidden in the UTF-8 standard due to -potential security issues). Another malformation example is the first byte of -a character not being a legal first byte. See F<utf8.h> for the list of such -flags. For allowed 0 length strings, this function returns 0; for allowed -overlong sequences, the computed code point is returned; for all other allowed -malformations, the Unicode REPLACEMENT CHARACTER is returned, as these have no -determinable reasonable value. - -The UTF8_CHECK_ONLY flag overrides the behavior when a non-allowed (by other -flags) malformation is found. If this flag is set, the routine assumes that -the caller will raise a warning, and this function will silently just set -C<retlen> to C<-1> and return zero. - -Certain code points are considered problematic. These are Unicode surrogates, -Unicode non-characters, and code points above the Unicode maximum of 0x10FFFF. -By default these are considered regular code points, but certain situations -warrant special handling for them. If C<flags> contains -UTF8_DISALLOW_ILLEGAL_INTERCHANGE, all three classes are treated as -malformations and handled as such. The flags UTF8_DISALLOW_SURROGATE, -UTF8_DISALLOW_NONCHAR, and UTF8_DISALLOW_SUPER (meaning above the legal Unicode -maximum) can be set to disallow these categories individually. - -The flags UTF8_WARN_ILLEGAL_INTERCHANGE, UTF8_WARN_SURROGATE, -UTF8_WARN_NONCHAR, and UTF8_WARN_SUPER will cause warning messages to be raised -for their respective categories, but otherwise the code points are considered -valid (not malformations). To get a category to both be treated as a -malformation and raise a warning, specify both the WARN and DISALLOW flags. -(But note that warnings are not raised if lexically disabled nor if -UTF8_CHECK_ONLY is also specified.) - -Very large code points (above 0x7FFF_FFFF) are considered more problematic than -the others that are above the Unicode legal maximum. There are several -reasons: they requre at least 32 bits to represent them on ASCII platforms, are -not representable at all on EBCDIC platforms, and the original UTF-8 -specification never went above this number (the current 0x10FFFF limit was -imposed later). (The smaller ones, those that fit into 32 bits, are -representable by a UV on ASCII platforms, but not by an IV, which means that -the number of operations that can be performed on them is quite restricted.) -The UTF-8 encoding on ASCII platforms for these large code points begins with a -byte containing 0xFE or 0xFF. The UTF8_DISALLOW_FE_FF flag will cause them to -be treated as malformations, while allowing smaller above-Unicode code points. -(Of course UTF8_DISALLOW_SUPER will treat all above-Unicode code points, -including these, as malformations.) Similarly, UTF8_WARN_FE_FF acts just like -the other WARN flags, but applies just to these code points. - -All other code points corresponding to Unicode characters, including private -use and those yet to be assigned, are never considered malformed and never -warn. - -Most code should use L</utf8_to_uvchr_buf>() rather than call this directly. - - UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, - STRLEN *retlen, U32 flags) - -=for hackers -Found in file utf8.c - -=item utf8_distance -X<utf8_distance> - -Returns the number of UTF-8 characters between the UTF-8 pointers C<a> -and C<b>. - -WARNING: use only if you *know* that the pointers point inside the -same UTF-8 buffer. - - IV utf8_distance(const U8 *a, const U8 *b) - -=for hackers -Found in file utf8.c - -=item utf8_hop -X<utf8_hop> - -Return the UTF-8 pointer C<s> displaced by C<off> characters, either -forward or backward. - -WARNING: do not use the following unless you *know* C<off> is within -the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned -on the first byte of character or just after the last byte of a character. - - U8* utf8_hop(const U8 *s, I32 off) - -=for hackers -Found in file utf8.c - -=item utf8_length -X<utf8_length> - -Return the length of the UTF-8 char encoded string C<s> in characters. -Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end -up past C<e>, croaks. - - STRLEN utf8_length(const U8* s, const U8 *e) - -=for hackers -Found in file utf8.c - -=item utf8_to_bytes -X<utf8_to_bytes> - -Converts a string C<s> of length C<len> from UTF-8 into native byte encoding. -Unlike L</bytes_to_utf8>, this over-writes the original string, and -updates C<len> to contain the new length. -Returns zero on failure, setting C<len> to -1. - -If you need a copy of the string, see L</bytes_from_utf8>. - -NOTE: this function is experimental and may change or be -removed without notice. - - U8* utf8_to_bytes(U8 *s, STRLEN *len) - -=for hackers -Found in file utf8.c - -=item utf8_to_uvchr -X<utf8_to_uvchr> - -DEPRECATED! - -Returns the native code point of the first character in the string C<s> -which is assumed to be in UTF-8 encoding; C<retlen> will be set to the -length, in bytes, of that character. - -Some, but not all, UTF-8 malformations are detected, and in fact, some -malformed input could cause reading beyond the end of the input buffer, which -is why this function is deprecated. Use L</utf8_to_uvchr_buf> instead. - -If C<s> points to one of the detected malformations, and UTF8 warnings are -enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't -NULL) to -1. If those warnings are off, the computed value if well-defined (or -the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen> -is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the -next possible position in C<s> that could begin a non-malformed character. -See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned. - - UV utf8_to_uvchr(const U8 *s, STRLEN *retlen) - -=for hackers -Found in file utf8.c - -=item utf8_to_uvchr_buf -X<utf8_to_uvchr_buf> - -Returns the native code point of the first character in the string C<s> which -is assumed to be in UTF-8 encoding; C<send> points to 1 beyond the end of C<s>. -C<*retlen> will be set to the length, in bytes, of that character. - -If C<s> does not point to a well-formed UTF-8 character and UTF8 warnings are -enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't -NULL) to -1. If those warnings are off, the computed value if well-defined (or -the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen> -is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the -next possible position in C<s> that could begin a non-malformed character. -See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned. - - UV utf8_to_uvchr_buf(const U8 *s, const U8 *send, - STRLEN *retlen) - -=for hackers -Found in file utf8.c - -=item utf8_to_uvuni -X<utf8_to_uvuni> - -DEPRECATED! - -Returns the Unicode code point of the first character in the string C<s> -which is assumed to be in UTF-8 encoding; C<retlen> will be set to the -length, in bytes, of that character. - -This function should only be used when the returned UV is considered -an index into the Unicode semantic tables (e.g. swashes). - -Some, but not all, UTF-8 malformations are detected, and in fact, some -malformed input could cause reading beyond the end of the input buffer, which -is why this function is deprecated. Use L</utf8_to_uvuni_buf> instead. - -If C<s> points to one of the detected malformations, and UTF8 warnings are -enabled, zero is returned and C<*retlen> is set (if C<retlen> doesn't point to -NULL) to -1. If those warnings are off, the computed value if well-defined (or -the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen> -is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the -next possible position in C<s> that could begin a non-malformed character. -See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned. - - UV utf8_to_uvuni(const U8 *s, STRLEN *retlen) - -=for hackers -Found in file utf8.c - -=item utf8_to_uvuni_buf -X<utf8_to_uvuni_buf> - -Returns the Unicode code point of the first character in the string C<s> which -is assumed to be in UTF-8 encoding; C<send> points to 1 beyond the end of C<s>. -C<retlen> will be set to the length, in bytes, of that character. - -This function should only be used when the returned UV is considered -an index into the Unicode semantic tables (e.g. swashes). - -If C<s> does not point to a well-formed UTF-8 character and UTF8 warnings are -enabled, zero is returned and C<*retlen> is set (if C<retlen> isn't -NULL) to -1. If those warnings are off, the computed value if well-defined (or -the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and C<*retlen> -is set (if C<retlen> isn't NULL) so that (S<C<s> + C<*retlen>>) is the -next possible position in C<s> that could begin a non-malformed character. -See L</utf8n_to_uvuni> for details on when the REPLACEMENT CHARACTER is returned. - - UV utf8_to_uvuni_buf(const U8 *s, const U8 *send, - STRLEN *retlen) - -=for hackers -Found in file utf8.c - -=item uvchr_to_utf8 -X<uvchr_to_utf8> - -Adds the UTF-8 representation of the Native code point C<uv> to the end -of the string C<d>; C<d> should have at least C<UTF8_MAXBYTES+1> free -bytes available. The return value is the pointer to the byte after the -end of the new character. In other words, - - d = uvchr_to_utf8(d, uv); - -is the recommended wide native character-aware way of saying - - *(d++) = uv; - - U8* uvchr_to_utf8(U8 *d, UV uv) - -=for hackers -Found in file utf8.c - -=item uvuni_to_utf8_flags -X<uvuni_to_utf8_flags> - -Adds the UTF-8 representation of the code point C<uv> to the end -of the string C<d>; C<d> should have at least C<UTF8_MAXBYTES+1> free -bytes available. The return value is the pointer to the byte after the -end of the new character. In other words, - - d = uvuni_to_utf8_flags(d, uv, flags); - -or, in most cases, - - d = uvuni_to_utf8(d, uv); - -(which is equivalent to) - - d = uvuni_to_utf8_flags(d, uv, 0); - -This is the recommended Unicode-aware way of saying - - *(d++) = uv; - -This function will convert to UTF-8 (and not warn) even code points that aren't -legal Unicode or are problematic, unless C<flags> contains one or more of the -following flags: - -If C<uv> is a Unicode surrogate code point and UNICODE_WARN_SURROGATE is set, -the function will raise a warning, provided UTF8 warnings are enabled. If instead -UNICODE_DISALLOW_SURROGATE is set, the function will fail and return NULL. -If both flags are set, the function will both warn and return NULL. - -The UNICODE_WARN_NONCHAR and UNICODE_DISALLOW_NONCHAR flags correspondingly -affect how the function handles a Unicode non-character. And, likewise for the -UNICODE_WARN_SUPER and UNICODE_DISALLOW_SUPER flags, and code points that are -above the Unicode maximum of 0x10FFFF. Code points above 0x7FFF_FFFF (which are -even less portable) can be warned and/or disallowed even if other above-Unicode -code points are accepted by the UNICODE_WARN_FE_FF and UNICODE_DISALLOW_FE_FF -flags. - -And finally, the flag UNICODE_WARN_ILLEGAL_INTERCHANGE selects all four of the -above WARN flags; and UNICODE_DISALLOW_ILLEGAL_INTERCHANGE selects all four -DISALLOW flags. - - - U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags) - -=for hackers -Found in file utf8.c - - -=back - -=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions - -=over 8 - -=item ax -X<ax> - -Variable which is setup by C<xsubpp> to indicate the stack base offset, -used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro -must be called prior to setup the C<MARK> variable. - - I32 ax - -=for hackers -Found in file XSUB.h - -=item CLASS -X<CLASS> - -Variable which is setup by C<xsubpp> to indicate the -class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>. - - char* CLASS - -=for hackers -Found in file XSUB.h - -=item dAX -X<dAX> - -Sets up the C<ax> variable. -This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>. - - dAX; - -=for hackers -Found in file XSUB.h - -=item dAXMARK -X<dAXMARK> - -Sets up the C<ax> variable and stack marker variable C<mark>. -This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>. - - dAXMARK; - -=for hackers -Found in file XSUB.h - -=item dITEMS -X<dITEMS> - -Sets up the C<items> variable. -This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>. - - dITEMS; - -=for hackers -Found in file XSUB.h - -=item dUNDERBAR -X<dUNDERBAR> - -Sets up any variable needed by the C<UNDERBAR> macro. It used to define -C<padoff_du>, but it is currently a noop. However, it is strongly advised -to still use it for ensuring past and future compatibility. - - dUNDERBAR; - -=for hackers -Found in file XSUB.h - -=item dXSARGS -X<dXSARGS> - -Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. -Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>. -This is usually handled automatically by C<xsubpp>. - - dXSARGS; - -=for hackers -Found in file XSUB.h - -=item dXSI32 -X<dXSI32> - -Sets up the C<ix> variable for an XSUB which has aliases. This is usually -handled automatically by C<xsubpp>. - - dXSI32; - -=for hackers -Found in file XSUB.h - -=item items -X<items> - -Variable which is setup by C<xsubpp> to indicate the number of -items on the stack. See L<perlxs/"Variable-length Parameter Lists">. - - I32 items - -=for hackers -Found in file XSUB.h - -=item ix -X<ix> - -Variable which is setup by C<xsubpp> to indicate which of an -XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">. - - I32 ix - -=for hackers -Found in file XSUB.h - -=item newXSproto -X<newXSproto> - -Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to -the subs. - -=for hackers -Found in file XSUB.h - -=item RETVAL -X<RETVAL> - -Variable which is setup by C<xsubpp> to hold the return value for an -XSUB. This is always the proper type for the XSUB. See -L<perlxs/"The RETVAL Variable">. - - (whatever) RETVAL - -=for hackers -Found in file XSUB.h - -=item ST -X<ST> - -Used to access elements on the XSUB's stack. - - SV* ST(int ix) - -=for hackers -Found in file XSUB.h - -=item THIS -X<THIS> - -Variable which is setup by C<xsubpp> to designate the object in a C++ -XSUB. This is always the proper type for the C++ object. See C<CLASS> and -L<perlxs/"Using XS With C++">. - - (whatever) THIS - -=for hackers -Found in file XSUB.h - -=item UNDERBAR -X<UNDERBAR> - -The SV* corresponding to the $_ variable. Works even if there -is a lexical $_ in scope. - -=for hackers -Found in file XSUB.h - -=item XS -X<XS> - -Macro to declare an XSUB and its C parameter list. This is handled by -C<xsubpp>. It is the same as using the more explicit XS_EXTERNAL macro. - -=for hackers -Found in file XSUB.h - -=item XS_APIVERSION_BOOTCHECK -X<XS_APIVERSION_BOOTCHECK> - -Macro to verify that the perl api version an XS module has been compiled against -matches the api version of the perl interpreter it's being loaded into. - - XS_APIVERSION_BOOTCHECK; - -=for hackers -Found in file XSUB.h - -=item XS_EXTERNAL -X<XS_EXTERNAL> - -Macro to declare an XSUB and its C parameter list explicitly exporting the symbols. - -=for hackers -Found in file XSUB.h - -=item XS_INTERNAL -X<XS_INTERNAL> - -Macro to declare an XSUB and its C parameter list without exporting the symbols. -This is handled by C<xsubpp> and generally preferable over exporting the XSUB -symbols unnecessarily. - -=for hackers -Found in file XSUB.h - -=item XS_VERSION -X<XS_VERSION> - -The version identifier for an XS module. This is usually -handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>. - -=for hackers -Found in file XSUB.h - -=item XS_VERSION_BOOTCHECK -X<XS_VERSION_BOOTCHECK> - -Macro to verify that a PM module's $VERSION variable matches the XS -module's C<XS_VERSION> variable. This is usually handled automatically by -C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">. - - XS_VERSION_BOOTCHECK; - -=for hackers -Found in file XSUB.h - - -=back - -=head1 Warning and Dieing - -=over 8 - -=item croak -X<croak> - -This is an XS interface to Perl's C<die> function. - -Take a sprintf-style format pattern and argument list. These are used to -generate a string message. If the message does not end with a newline, -then it will be extended with some indication of the current location -in the code, as described for L</mess_sv>. - -The error message will be used as an exception, by default -returning control to the nearest enclosing C<eval>, but subject to -modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak> -function never returns normally. - -For historical reasons, if C<pat> is null then the contents of C<ERRSV> -(C<$@>) will be used as an error message or object instead of building an -error message from arguments. If you want to throw a non-string object, -or build an error message in an SV yourself, it is preferable to use -the L</croak_sv> function, which does not involve clobbering C<ERRSV>. - - void croak(const char *pat, ...) - -=for hackers -Found in file util.c - -=item croak_no_modify -X<croak_no_modify> - -Exactly equivalent to C<Perl_croak(aTHX_ "%s", PL_no_modify)>, but generates -terser object code than using C<Perl_croak>. Less code used on exception code -paths reduces CPU cache pressure. - - void croak_no_modify() - -=for hackers -Found in file util.c - -=item croak_sv -X<croak_sv> - -This is an XS interface to Perl's C<die> function. - -C<baseex> is the error message or object. If it is a reference, it -will be used as-is. Otherwise it is used as a string, and if it does -not end with a newline then it will be extended with some indication of -the current location in the code, as described for L</mess_sv>. - -The error message or object will be used as an exception, by default -returning control to the nearest enclosing C<eval>, but subject to -modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak_sv> -function never returns normally. - -To die with a simple string message, the L</croak> function may be -more convenient. - - void croak_sv(SV *baseex) - -=for hackers -Found in file util.c - -=item die -X<die> - -Behaves the same as L</croak>, except for the return type. -It should be used only where the C<OP *> return type is required. -The function never actually returns. - - OP * die(const char *pat, ...) - -=for hackers -Found in file util.c - -=item die_sv -X<die_sv> - -Behaves the same as L</croak_sv>, except for the return type. -It should be used only where the C<OP *> return type is required. -The function never actually returns. - - OP * die_sv(SV *baseex) - -=for hackers -Found in file util.c - -=item vcroak -X<vcroak> - -This is an XS interface to Perl's C<die> function. - -C<pat> and C<args> are a sprintf-style format pattern and encapsulated -argument list. These are used to generate a string message. If the -message does not end with a newline, then it will be extended with -some indication of the current location in the code, as described for -L</mess_sv>. - -The error message will be used as an exception, by default -returning control to the nearest enclosing C<eval>, but subject to -modification by a C<$SIG{__DIE__}> handler. In any case, the C<croak> -function never returns normally. - -For historical reasons, if C<pat> is null then the contents of C<ERRSV> -(C<$@>) will be used as an error message or object instead of building an -error message from arguments. If you want to throw a non-string object, -or build an error message in an SV yourself, it is preferable to use -the L</croak_sv> function, which does not involve clobbering C<ERRSV>. - - void vcroak(const char *pat, va_list *args) - -=for hackers -Found in file util.c - -=item vwarn -X<vwarn> - -This is an XS interface to Perl's C<warn> function. - -C<pat> and C<args> are a sprintf-style format pattern and encapsulated -argument list. These are used to generate a string message. If the -message does not end with a newline, then it will be extended with -some indication of the current location in the code, as described for -L</mess_sv>. - -The error message or object will by default be written to standard error, -but this is subject to modification by a C<$SIG{__WARN__}> handler. - -Unlike with L</vcroak>, C<pat> is not permitted to be null. - - void vwarn(const char *pat, va_list *args) - -=for hackers -Found in file util.c - -=item warn -X<warn> - -This is an XS interface to Perl's C<warn> function. - -Take a sprintf-style format pattern and argument list. These are used to -generate a string message. If the message does not end with a newline, -then it will be extended with some indication of the current location -in the code, as described for L</mess_sv>. - -The error message or object will by default be written to standard error, -but this is subject to modification by a C<$SIG{__WARN__}> handler. - -Unlike with L</croak>, C<pat> is not permitted to be null. - - void warn(const char *pat, ...) - -=for hackers -Found in file util.c - -=item warn_sv -X<warn_sv> - -This is an XS interface to Perl's C<warn> function. - -C<baseex> is the error message or object. If it is a reference, it -will be used as-is. Otherwise it is used as a string, and if it does -not end with a newline then it will be extended with some indication of -the current location in the code, as described for L</mess_sv>. - -The error message or object will by default be written to standard error, -but this is subject to modification by a C<$SIG{__WARN__}> handler. - -To warn with a simple string message, the L</warn> function may be -more convenient. - - void warn_sv(SV *baseex) - -=for hackers -Found in file util.c - - -=back - -=head1 Undocumented functions - -The following functions have been flagged as part of the public API, -but are currently undocumented. Use them at your own risk, as the -interfaces are subject to change. - -If you use one of them, you may wish to consider creating and submitting -documentation for it. If your patch is accepted, this will indicate that -the interface is stable (unless it is explicitly marked otherwise). - -=over - -=item GetVars -X<GetVars> - -=item Gv_AMupdate -X<Gv_AMupdate> - -=item PerlIO_clearerr -X<PerlIO_clearerr> - -=item PerlIO_close -X<PerlIO_close> - -=item PerlIO_context_layers -X<PerlIO_context_layers> - -=item PerlIO_eof -X<PerlIO_eof> - -=item PerlIO_error -X<PerlIO_error> - -=item PerlIO_fileno -X<PerlIO_fileno> - -=item PerlIO_fill -X<PerlIO_fill> - -=item PerlIO_flush -X<PerlIO_flush> - -=item PerlIO_get_base -X<PerlIO_get_base> - -=item PerlIO_get_bufsiz -X<PerlIO_get_bufsiz> - -=item PerlIO_get_cnt -X<PerlIO_get_cnt> - -=item PerlIO_get_ptr -X<PerlIO_get_ptr> - -=item PerlIO_read -X<PerlIO_read> - -=item PerlIO_seek -X<PerlIO_seek> - -=item PerlIO_set_cnt -X<PerlIO_set_cnt> - -=item PerlIO_set_ptrcnt -X<PerlIO_set_ptrcnt> - -=item PerlIO_setlinebuf -X<PerlIO_setlinebuf> - -=item PerlIO_stderr -X<PerlIO_stderr> - -=item PerlIO_stdin -X<PerlIO_stdin> - -=item PerlIO_stdout -X<PerlIO_stdout> - -=item PerlIO_tell -X<PerlIO_tell> - -=item PerlIO_unread -X<PerlIO_unread> - -=item PerlIO_write -X<PerlIO_write> - -=item Slab_Alloc -X<Slab_Alloc> - -=item Slab_Free -X<Slab_Free> - -=item _is_utf8_quotemeta -X<_is_utf8_quotemeta> - -=item amagic_call -X<amagic_call> - -=item amagic_deref_call -X<amagic_deref_call> - -=item any_dup -X<any_dup> - -=item atfork_lock -X<atfork_lock> - -=item atfork_unlock -X<atfork_unlock> - -=item av_arylen_p -X<av_arylen_p> - -=item av_iter_p -X<av_iter_p> - -=item block_gimme -X<block_gimme> - -=item call_atexit -X<call_atexit> - -=item call_list -X<call_list> - -=item calloc -X<calloc> - -=item cast_i32 -X<cast_i32> - -=item cast_iv -X<cast_iv> - -=item cast_ulong -X<cast_ulong> - -=item cast_uv -X<cast_uv> - -=item ck_warner -X<ck_warner> - -=item ck_warner_d -X<ck_warner_d> - -=item ckwarn -X<ckwarn> - -=item ckwarn_d -X<ckwarn_d> - -=item clone_params_del -X<clone_params_del> - -=item clone_params_new -X<clone_params_new> - -=item croak_nocontext -X<croak_nocontext> - -=item csighandler -X<csighandler> - -=item cx_dump -X<cx_dump> - -=item cx_dup -X<cx_dup> - -=item cxinc -X<cxinc> - -=item deb -X<deb> - -=item deb_nocontext -X<deb_nocontext> - -=item debop -X<debop> - -=item debprofdump -X<debprofdump> - -=item debstack -X<debstack> - -=item debstackptrs -X<debstackptrs> - -=item delimcpy -X<delimcpy> - -=item despatch_signals -X<despatch_signals> - -=item die_nocontext -X<die_nocontext> - -=item dirp_dup -X<dirp_dup> - -=item do_aspawn -X<do_aspawn> - -=item do_binmode -X<do_binmode> - -=item do_close -X<do_close> - -=item do_gv_dump -X<do_gv_dump> - -=item do_gvgv_dump -X<do_gvgv_dump> - -=item do_hv_dump -X<do_hv_dump> - -=item do_join -X<do_join> - -=item do_magic_dump -X<do_magic_dump> - -=item do_op_dump -X<do_op_dump> - -=item do_open -X<do_open> - -=item do_open9 -X<do_open9> - -=item do_openn -X<do_openn> - -=item do_pmop_dump -X<do_pmop_dump> - -=item do_spawn -X<do_spawn> - -=item do_spawn_nowait -X<do_spawn_nowait> - -=item do_sprintf -X<do_sprintf> - -=item do_sv_dump -X<do_sv_dump> - -=item doing_taint -X<doing_taint> - -=item doref -X<doref> - -=item dounwind -X<dounwind> - -=item dowantarray -X<dowantarray> - -=item dump_all -X<dump_all> - -=item dump_eval -X<dump_eval> - -=item dump_fds -X<dump_fds> - -=item dump_form -X<dump_form> - -=item dump_indent -X<dump_indent> - -=item dump_mstats -X<dump_mstats> - -=item dump_packsubs -X<dump_packsubs> - -=item dump_sub -X<dump_sub> - -=item dump_vindent -X<dump_vindent> - -=item filter_add -X<filter_add> - -=item filter_del -X<filter_del> - -=item filter_read -X<filter_read> - -=item foldEQ_latin1 -X<foldEQ_latin1> - -=item form_nocontext -X<form_nocontext> - -=item fp_dup -X<fp_dup> - -=item fprintf_nocontext -X<fprintf_nocontext> - -=item free_global_struct -X<free_global_struct> - -=item free_tmps -X<free_tmps> - -=item get_context -X<get_context> - -=item get_mstats -X<get_mstats> - -=item get_op_descs -X<get_op_descs> - -=item get_op_names -X<get_op_names> - -=item get_ppaddr -X<get_ppaddr> - -=item get_vtbl -X<get_vtbl> - -=item gp_dup -X<gp_dup> - -=item gp_free -X<gp_free> - -=item gp_ref -X<gp_ref> - -=item gv_AVadd -X<gv_AVadd> - -=item gv_HVadd -X<gv_HVadd> - -=item gv_IOadd -X<gv_IOadd> - -=item gv_SVadd -X<gv_SVadd> - -=item gv_add_by_type -X<gv_add_by_type> - -=item gv_autoload4 -X<gv_autoload4> - -=item gv_autoload_pv -X<gv_autoload_pv> - -=item gv_autoload_pvn -X<gv_autoload_pvn> - -=item gv_autoload_sv -X<gv_autoload_sv> - -=item gv_check -X<gv_check> - -=item gv_dump -X<gv_dump> - -=item gv_efullname -X<gv_efullname> - -=item gv_efullname3 -X<gv_efullname3> - -=item gv_efullname4 -X<gv_efullname4> - -=item gv_fetchfile -X<gv_fetchfile> - -=item gv_fetchfile_flags -X<gv_fetchfile_flags> - -=item gv_fetchpv -X<gv_fetchpv> - -=item gv_fetchpvn_flags -X<gv_fetchpvn_flags> - -=item gv_fetchsv -X<gv_fetchsv> - -=item gv_fullname -X<gv_fullname> - -=item gv_fullname3 -X<gv_fullname3> - -=item gv_fullname4 -X<gv_fullname4> - -=item gv_handler -X<gv_handler> - -=item gv_name_set -X<gv_name_set> - -=item he_dup -X<he_dup> - -=item hek_dup -X<hek_dup> - -=item hv_common -X<hv_common> - -=item hv_common_key_len -X<hv_common_key_len> - -=item hv_delayfree_ent -X<hv_delayfree_ent> - -=item hv_eiter_p -X<hv_eiter_p> - -=item hv_eiter_set -X<hv_eiter_set> - -=item hv_free_ent -X<hv_free_ent> - -=item hv_ksplit -X<hv_ksplit> - -=item hv_name_set -X<hv_name_set> - -=item hv_placeholders_get -X<hv_placeholders_get> - -=item hv_placeholders_p -X<hv_placeholders_p> - -=item hv_placeholders_set -X<hv_placeholders_set> - -=item hv_riter_p -X<hv_riter_p> - -=item hv_riter_set -X<hv_riter_set> - -=item init_global_struct -X<init_global_struct> - -=item init_i18nl10n -X<init_i18nl10n> - -=item init_i18nl14n -X<init_i18nl14n> - -=item init_stacks -X<init_stacks> - -=item init_tm -X<init_tm> - -=item instr -X<instr> - -=item is_lvalue_sub -X<is_lvalue_sub> - -=item is_uni_alnum -X<is_uni_alnum> - -=item is_uni_alnum_lc -X<is_uni_alnum_lc> - -=item is_uni_alpha -X<is_uni_alpha> - -=item is_uni_alpha_lc -X<is_uni_alpha_lc> - -=item is_uni_ascii -X<is_uni_ascii> - -=item is_uni_ascii_lc -X<is_uni_ascii_lc> - -=item is_uni_cntrl -X<is_uni_cntrl> - -=item is_uni_cntrl_lc -X<is_uni_cntrl_lc> - -=item is_uni_digit -X<is_uni_digit> - -=item is_uni_digit_lc -X<is_uni_digit_lc> - -=item is_uni_graph -X<is_uni_graph> - -=item is_uni_graph_lc -X<is_uni_graph_lc> - -=item is_uni_idfirst -X<is_uni_idfirst> - -=item is_uni_idfirst_lc -X<is_uni_idfirst_lc> - -=item is_uni_lower -X<is_uni_lower> - -=item is_uni_lower_lc -X<is_uni_lower_lc> - -=item is_uni_print -X<is_uni_print> - -=item is_uni_print_lc -X<is_uni_print_lc> - -=item is_uni_punct -X<is_uni_punct> - -=item is_uni_punct_lc -X<is_uni_punct_lc> - -=item is_uni_space -X<is_uni_space> - -=item is_uni_space_lc -X<is_uni_space_lc> - -=item is_uni_upper -X<is_uni_upper> - -=item is_uni_upper_lc -X<is_uni_upper_lc> - -=item is_uni_xdigit -X<is_uni_xdigit> - -=item is_uni_xdigit_lc -X<is_uni_xdigit_lc> - -=item is_utf8_alnum -X<is_utf8_alnum> - -=item is_utf8_alpha -X<is_utf8_alpha> - -=item is_utf8_ascii -X<is_utf8_ascii> - -=item is_utf8_cntrl -X<is_utf8_cntrl> - -=item is_utf8_digit -X<is_utf8_digit> - -=item is_utf8_graph -X<is_utf8_graph> - -=item is_utf8_idcont -X<is_utf8_idcont> - -=item is_utf8_idfirst -X<is_utf8_idfirst> - -=item is_utf8_lower -X<is_utf8_lower> - -=item is_utf8_mark -X<is_utf8_mark> - -=item is_utf8_perl_space -X<is_utf8_perl_space> - -=item is_utf8_perl_word -X<is_utf8_perl_word> - -=item is_utf8_posix_digit -X<is_utf8_posix_digit> - -=item is_utf8_print -X<is_utf8_print> - -=item is_utf8_punct -X<is_utf8_punct> - -=item is_utf8_space -X<is_utf8_space> - -=item is_utf8_upper -X<is_utf8_upper> - -=item is_utf8_xdigit -X<is_utf8_xdigit> - -=item is_utf8_xidcont -X<is_utf8_xidcont> - -=item is_utf8_xidfirst -X<is_utf8_xidfirst> - -=item leave_scope -X<leave_scope> - -=item load_module_nocontext -X<load_module_nocontext> - -=item magic_dump -X<magic_dump> - -=item malloc -X<malloc> - -=item markstack_grow -X<markstack_grow> - -=item mess_nocontext -X<mess_nocontext> - -=item mfree -X<mfree> - -=item mg_dup -X<mg_dup> - -=item mg_size -X<mg_size> - -=item mini_mktime -X<mini_mktime> - -=item moreswitches -X<moreswitches> - -=item mro_get_from_name -X<mro_get_from_name> - -=item mro_get_private_data -X<mro_get_private_data> - -=item mro_set_mro -X<mro_set_mro> - -=item mro_set_private_data -X<mro_set_private_data> - -=item my_atof -X<my_atof> - -=item my_atof2 -X<my_atof2> - -=item my_bcopy -X<my_bcopy> - -=item my_bzero -X<my_bzero> - -=item my_chsize -X<my_chsize> - -=item my_cxt_index -X<my_cxt_index> - -=item my_cxt_init -X<my_cxt_init> - -=item my_dirfd -X<my_dirfd> - -=item my_exit -X<my_exit> - -=item my_failure_exit -X<my_failure_exit> - -=item my_fflush_all -X<my_fflush_all> - -=item my_fork -X<my_fork> - -=item my_htonl -X<my_htonl> - -=item my_lstat -X<my_lstat> - -=item my_memcmp -X<my_memcmp> - -=item my_memset -X<my_memset> - -=item my_ntohl -X<my_ntohl> - -=item my_pclose -X<my_pclose> - -=item my_popen -X<my_popen> - -=item my_popen_list -X<my_popen_list> - -=item my_setenv -X<my_setenv> - -=item my_socketpair -X<my_socketpair> - -=item my_stat -X<my_stat> - -=item my_strftime -X<my_strftime> - -=item my_strlcat -X<my_strlcat> - -=item my_strlcpy -X<my_strlcpy> - -=item my_swap -X<my_swap> - -=item newANONATTRSUB -X<newANONATTRSUB> - -=item newANONHASH -X<newANONHASH> - -=item newANONLIST -X<newANONLIST> - -=item newANONSUB -X<newANONSUB> - -=item newATTRSUB -X<newATTRSUB> - -=item newAVREF -X<newAVREF> - -=item newCVREF -X<newCVREF> - -=item newFORM -X<newFORM> - -=item newGVREF -X<newGVREF> - -=item newGVgen -X<newGVgen> - -=item newGVgen_flags -X<newGVgen_flags> - -=item newHVREF -X<newHVREF> - -=item newHVhv -X<newHVhv> - -=item newIO -X<newIO> - -=item newMYSUB -X<newMYSUB> - -=item newPROG -X<newPROG> - -=item newRV -X<newRV> - -=item newSUB -X<newSUB> - -=item newSVREF -X<newSVREF> - -=item newSVpvf_nocontext -X<newSVpvf_nocontext> - -=item new_collate -X<new_collate> - -=item new_ctype -X<new_ctype> - -=item new_numeric -X<new_numeric> - -=item new_stackinfo -X<new_stackinfo> - -=item ninstr -X<ninstr> - -=item op_dump -X<op_dump> - -=item op_free -X<op_free> - -=item op_null -X<op_null> - -=item op_refcnt_lock -X<op_refcnt_lock> - -=item op_refcnt_unlock -X<op_refcnt_unlock> - -=item parser_dup -X<parser_dup> - -=item perl_alloc_using -X<perl_alloc_using> - -=item perl_clone_using -X<perl_clone_using> - -=item pmop_dump -X<pmop_dump> - -=item pop_scope -X<pop_scope> - -=item pregcomp -X<pregcomp> - -=item pregexec -X<pregexec> - -=item pregfree -X<pregfree> - -=item pregfree2 -X<pregfree2> - -=item printf_nocontext -X<printf_nocontext> - -=item ptr_table_clear -X<ptr_table_clear> - -=item ptr_table_fetch -X<ptr_table_fetch> - -=item ptr_table_free -X<ptr_table_free> - -=item ptr_table_new -X<ptr_table_new> - -=item ptr_table_split -X<ptr_table_split> - -=item ptr_table_store -X<ptr_table_store> - -=item push_scope -X<push_scope> - -=item re_compile -X<re_compile> - -=item re_dup_guts -X<re_dup_guts> - -=item re_intuit_start -X<re_intuit_start> - -=item re_intuit_string -X<re_intuit_string> - -=item realloc -X<realloc> - -=item reentrant_free -X<reentrant_free> - -=item reentrant_init -X<reentrant_init> - -=item reentrant_retry -X<reentrant_retry> - -=item reentrant_size -X<reentrant_size> - -=item ref -X<ref> - -=item reg_named_buff_all -X<reg_named_buff_all> - -=item reg_named_buff_exists -X<reg_named_buff_exists> - -=item reg_named_buff_fetch -X<reg_named_buff_fetch> - -=item reg_named_buff_firstkey -X<reg_named_buff_firstkey> - -=item reg_named_buff_nextkey -X<reg_named_buff_nextkey> - -=item reg_named_buff_scalar -X<reg_named_buff_scalar> - -=item regclass_swash -X<regclass_swash> - -=item regdump -X<regdump> - -=item regdupe_internal -X<regdupe_internal> - -=item regexec_flags -X<regexec_flags> - -=item regfree_internal -X<regfree_internal> - -=item reginitcolors -X<reginitcolors> - -=item regnext -X<regnext> - -=item repeatcpy -X<repeatcpy> - -=item rninstr -X<rninstr> - -=item rsignal -X<rsignal> - -=item rsignal_state -X<rsignal_state> - -=item runops_debug -X<runops_debug> - -=item runops_standard -X<runops_standard> - -=item rvpv_dup -X<rvpv_dup> - -=item safesyscalloc -X<safesyscalloc> - -=item safesysfree -X<safesysfree> - -=item safesysmalloc -X<safesysmalloc> - -=item safesysrealloc -X<safesysrealloc> - -=item save_I16 -X<save_I16> - -=item save_I32 -X<save_I32> - -=item save_I8 -X<save_I8> - -=item save_adelete -X<save_adelete> - -=item save_aelem -X<save_aelem> - -=item save_aelem_flags -X<save_aelem_flags> - -=item save_alloc -X<save_alloc> - -=item save_aptr -X<save_aptr> - -=item save_ary -X<save_ary> - -=item save_bool -X<save_bool> - -=item save_clearsv -X<save_clearsv> - -=item save_delete -X<save_delete> - -=item save_destructor -X<save_destructor> - -=item save_destructor_x -X<save_destructor_x> - -=item save_freeop -X<save_freeop> - -=item save_freepv -X<save_freepv> - -=item save_freesv -X<save_freesv> - -=item save_generic_pvref -X<save_generic_pvref> - -=item save_generic_svref -X<save_generic_svref> - -=item save_gp -X<save_gp> - -=item save_hash -X<save_hash> - -=item save_hdelete -X<save_hdelete> - -=item save_helem -X<save_helem> - -=item save_helem_flags -X<save_helem_flags> - -=item save_hints -X<save_hints> - -=item save_hptr -X<save_hptr> - -=item save_int -X<save_int> - -=item save_item -X<save_item> - -=item save_iv -X<save_iv> - -=item save_list -X<save_list> - -=item save_long -X<save_long> - -=item save_mortalizesv -X<save_mortalizesv> - -=item save_nogv -X<save_nogv> - -=item save_op -X<save_op> - -=item save_padsv_and_mortalize -X<save_padsv_and_mortalize> - -=item save_pptr -X<save_pptr> - -=item save_pushi32ptr -X<save_pushi32ptr> - -=item save_pushptr -X<save_pushptr> - -=item save_pushptrptr -X<save_pushptrptr> - -=item save_re_context -X<save_re_context> - -=item save_scalar -X<save_scalar> - -=item save_set_svflags -X<save_set_svflags> - -=item save_shared_pvref -X<save_shared_pvref> - -=item save_sptr -X<save_sptr> - -=item save_svref -X<save_svref> - -=item save_vptr -X<save_vptr> - -=item savestack_grow -X<savestack_grow> - -=item savestack_grow_cnt -X<savestack_grow_cnt> - -=item scan_num -X<scan_num> - -=item scan_vstring -X<scan_vstring> - -=item screaminstr -X<screaminstr> - -=item seed -X<seed> - -=item set_context -X<set_context> - -=item set_numeric_local -X<set_numeric_local> - -=item set_numeric_radix -X<set_numeric_radix> - -=item set_numeric_standard -X<set_numeric_standard> - -=item share_hek -X<share_hek> - -=item si_dup -X<si_dup> - -=item ss_dup -X<ss_dup> - -=item stack_grow -X<stack_grow> - -=item start_subparse -X<start_subparse> - -=item stashpv_hvname_match -X<stashpv_hvname_match> - -=item str_to_version -X<str_to_version> - -=item sv_2iv -X<sv_2iv> - -=item sv_2pv -X<sv_2pv> - -=item sv_2uv -X<sv_2uv> - -=item sv_catpvf_mg_nocontext -X<sv_catpvf_mg_nocontext> - -=item sv_catpvf_nocontext -X<sv_catpvf_nocontext> - -=item sv_compile_2op -X<sv_compile_2op> - -=item sv_dump -X<sv_dump> - -=item sv_dup -X<sv_dup> - -=item sv_dup_inc -X<sv_dup_inc> - -=item sv_peek -X<sv_peek> - -=item sv_pvn_nomg -X<sv_pvn_nomg> - -=item sv_setpvf_mg_nocontext -X<sv_setpvf_mg_nocontext> - -=item sv_setpvf_nocontext -X<sv_setpvf_nocontext> - -=item sv_utf8_upgrade_flags_grow -X<sv_utf8_upgrade_flags_grow> - -=item swash_fetch -X<swash_fetch> - -=item swash_init -X<swash_init> - -=item sys_init -X<sys_init> - -=item sys_init3 -X<sys_init3> - -=item sys_intern_clear -X<sys_intern_clear> - -=item sys_intern_dup -X<sys_intern_dup> - -=item sys_intern_init -X<sys_intern_init> - -=item sys_term -X<sys_term> - -=item taint_env -X<taint_env> - -=item taint_proper -X<taint_proper> - -=item tmps_grow -X<tmps_grow> - -=item to_uni_fold -X<to_uni_fold> - -=item to_uni_lower -X<to_uni_lower> - -=item to_uni_lower_lc -X<to_uni_lower_lc> - -=item to_uni_title -X<to_uni_title> - -=item to_uni_title_lc -X<to_uni_title_lc> - -=item to_uni_upper -X<to_uni_upper> - -=item to_uni_upper_lc -X<to_uni_upper_lc> - -=item unlnk -X<unlnk> - -=item unsharepvn -X<unsharepvn> - -=item utf16_to_utf8 -X<utf16_to_utf8> - -=item utf16_to_utf8_reversed -X<utf16_to_utf8_reversed> - -=item uvchr_to_utf8_flags -X<uvchr_to_utf8_flags> - -=item uvuni_to_utf8 -X<uvuni_to_utf8> - -=item vdeb -X<vdeb> - -=item vform -X<vform> - -=item vload_module -X<vload_module> - -=item vnewSVpvf -X<vnewSVpvf> - -=item vwarner -X<vwarner> - -=item warn_nocontext -X<warn_nocontext> - -=item warner -X<warner> - -=item warner_nocontext -X<warner_nocontext> - -=item whichsig -X<whichsig> - -=item whichsig_pv -X<whichsig_pv> - -=item whichsig_pvn -X<whichsig_pvn> - -=item whichsig_sv -X<whichsig_sv> - -=back - - -=head1 AUTHORS - -Until May 1997, this document was maintained by Jeff Okamoto -<okamoto@corp.hp.com>. It is now maintained as part of Perl itself. - -With lots of help and suggestions from Dean Roehrich, Malcolm Beattie, -Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil -Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, -Stephen McCamant, and Gurusamy Sarathy. - -API Listing originally by Dean Roehrich <roehrich@cray.com>. - -Updated to be autogenerated from comments in the source by Benjamin Stuhl. - -=head1 SEE ALSO - -L<perlguts>, L<perlxs>, L<perlxstut>, L<perlintern> - -=cut - - ex: set ro: |