diff options
| -rw-r--r-- | MANIFEST | 2 | ||||
| -rw-r--r-- | Makefile.SH | 9 | ||||
| -rw-r--r-- | pod.lst | 5 | ||||
| -rw-r--r-- | pod/.gitignore | 6 | ||||
| -rw-r--r-- | pod/buildtoc | 9 | ||||
| -rw-r--r-- | pod/perlapi.pod | 7431 | ||||
| -rw-r--r-- | pod/perlintern.pod | 1100 | ||||
| -rw-r--r-- | vms/descrip_mms.template | 5 | ||||
| -rw-r--r-- | win32/Makefile | 4 | ||||
| -rw-r--r-- | win32/makefile.mk | 2 |
10 files changed, 32 insertions, 8541 deletions
@@ -3539,7 +3539,6 @@ pod/perl593delta.pod Perl changes in version 5.9.3 pod/perl594delta.pod Perl changes in version 5.9.4 pod/perl595delta.pod Perl changes in version 5.9.5 pod/perlapio.pod Perl internal IO abstraction interface -pod/perlapi.pod Perl API listing (autogenerated) pod/perlartistic.pod Perl Artistic License pod/perlbook.pod Perl book information pod/perlboot.pod Perl OO tutorial for beginners @@ -3578,7 +3577,6 @@ pod/perlgpl.pod GNU General Public License pod/perlguts.pod Perl internal functions for those doing extensions pod/perlhack.pod Perl hackers guide pod/perlhist.pod Perl history records -pod/perlintern.pod Perl internal functions (autogenerated) pod/perlintro.pod Perl introduction for beginners pod/perliol.pod C API for Perl's implementation of IO in Layers pod/perlipc.pod Perl interprocess communication diff --git a/Makefile.SH b/Makefile.SH index dd4ea3f6f0..156d27593c 100644 --- a/Makefile.SH +++ b/Makefile.SH @@ -454,6 +454,8 @@ mini_obj = $(obj1) $(obj2) $(obj3) $(ARCHOBJS) ndt_obj = $(obj0) $(obj1) $(obj2) $(obj3) $(ARCHOBJS) obj = $(ndt_obj) $(DTRACE_O) +generated_pods = extra.pods pod/perlapi.pod pod/perlintern.pod + lintflags = \ -b \ -n \ @@ -521,7 +523,7 @@ splintfiles = $(c1) .c.s: $(CCCMDSRC) -S $*.c -all: $(FIRSTMAKEFILE) miniperl$(EXE_EXT) miniperl extra.pods $(private) $(unidatafiles) $(public) $(dynamic_ext) $(nonxs_ext) extras.make +all: $(FIRSTMAKEFILE) miniperl$(EXE_EXT) miniperl $(generated_pods) $(private) $(unidatafiles) $(public) $(dynamic_ext) $(nonxs_ext) extras.make @echo " "; @echo " Everything is up to date. Type '$(MAKE) test' to run test suite." @@ -969,6 +971,9 @@ uni.data: miniperl$(EXE_EXT) $(CONFIGPM) lib/unicore/mktables cd lib/unicore && $(LDLIBPTH) $(RUN) ../../miniperl$(EXE_EXT) -I../../lib mktables -w touch uni.data +pod/perlapi.pod pod/perlintern.pod: miniperl$(EXE_EXT) autodoc.pl embed.fnc + $(RUN) ./miniperl$(EXE_EXT) autodoc.pl + extra.pods: miniperl$(EXE_EXT) -@test ! -f extra.pods || rm -f `cat extra.pods` -@rm -f extra.pods @@ -1174,7 +1179,7 @@ _mopup: -rmdir .depending -@test -f extra.pods && rm -f `cat extra.pods` -@test -f vms/README_vms.pod && rm -f vms/README_vms.pod - -rm -f perl.exp ext.libs extra.pods uni.data opmini.o perlmini.o + -rm -f perl.exp ext.libs $(generated_pods) uni.data opmini.o perlmini.o -rm -f perl.export perl.dll perl.libexp perl.map perl.def -rm -f perl.loadmap miniperl.loadmap perl.prelmap miniperl.prelmap -rm -f perl.third lib*.so.perl.third perl.3log t/perl.third t/perl.3log @@ -1,6 +1,7 @@ # h - Header # o - Omit from toc # r - top level READMEs to be copied/symlinked +# g - other autogenerated pods # a - for auxiliary documentation # number - indent by # D - this version's perldelta @@ -114,8 +115,8 @@ h Internals and C Language Interface perlreapi Perl regular expression plugin interface perlreguts Perl regular expression engine internals - perlapi Perl API listing (autogenerated) - perlintern Perl internal functions (autogenerated) +g perlapi Perl API listing (autogenerated) +g perlintern Perl internal functions (autogenerated) perliol C API for Perl's implementation of IO in Layers perlapio Perl internal IO abstraction interface diff --git a/pod/.gitignore b/pod/.gitignore index 2e2f9c931a..b9cc759a0c 100644 --- a/pod/.gitignore +++ b/pod/.gitignore @@ -7,7 +7,6 @@ /perlce.pod /perlcn.pod /perlcygwin.pod -/perldelta.pod /perldgux.pod /perldos.pod /perlepoc.pod @@ -57,3 +56,8 @@ /podchecker.bat /podselect /podselect.bat + +# generated +/perldelta.pod +/perlapi.pod +/perlintern.pod diff --git a/pod/buildtoc b/pod/buildtoc index 4054fdac43..5a680b1591 100644 --- a/pod/buildtoc +++ b/pod/buildtoc @@ -3,7 +3,7 @@ use strict; use vars qw($masterpodfile %Build %Targets $Verbose $Up %Ignore @Master %Readmes %Pods %Aux %Readmepods %Pragmata %Modules - %Copies); + %Copies %Generated); use File::Spec; use File::Find; use FindBin; @@ -115,6 +115,7 @@ foreach (<MASTER>) { $flags{manifest_omit} = 1; $delta_target = "$filename.pod"; } + $Generated{"$filename.pod"}++ if $flags =~ tr/g//d; if ($flags =~ tr/r//d) { my $readme = $filename; @@ -202,7 +203,7 @@ close MASTER; warn "$0: $i exists but is unknown by buildtoc\n" unless $our_pods{$i}; warn "$0: $i exists but is unknown by ../MANIFEST\n" - if !$manipods{$i} && !$manireadmes{$i} && !$Copies{$i}; + if !$manipods{$i} && !$manireadmes{$i} && !$Copies{$i} && !$Generated{$i}; warn "$0: $i exists but is unknown by perl.pod\n" if !$perlpods{$i} && !exists $sources{$i}; } @@ -213,6 +214,8 @@ close MASTER; foreach my $i (sort keys %manipods) { warn "$0: $i is known by ../MANIFEST but does not exist\n" unless $disk_pods{$i}; + warn "$0: $i is known by ../MANIFEST but is marked as generated\n" + if $Generated{$i}; } foreach my $i (sort keys %perlpods) { warn "$0: $i is known by perl.pod but does not exist\n" @@ -522,7 +525,7 @@ sub generate_manifest { } sub generate_manifest_pod { generate_manifest map {["pod/$_.pod", $Pods{$_}]} - grep {!$Copies{"$_.pod"}} sort keys %Pods; + grep {!$Copies{"$_.pod"}} grep {!$Generated{"$_.pod"}} sort keys %Pods; } sub generate_manifest_readme { generate_manifest map {["README.$_", $Readmes{$_}]} sort keys %Readmes; diff --git a/pod/perlapi.pod b/pod/perlapi.pod deleted file mode 100644 index 7498939e8d..0000000000 --- a/pod/perlapi.pod +++ /dev/null @@ -1,7431 +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 -embed.pl, specifically a listing of functions, macros, flags, and variables -that may be used by extension writers. The interfaces of any functions that -are not listed here are subject to change without notice. For this reason, -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. - - 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 used by the -array itself. - - 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. Returns the -deleted element. If C<flags> equals C<G_DISCARD>, the element is freed -and null is returned. - - 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>. - - 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 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 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. - - 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. - - 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. - - 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. - - 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. - - 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. - - 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 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. - -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 array itself. - - 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. - - 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 array. 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. - - 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. - - 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 Perl sub. See L<perlcall>. - -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. - -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 classes - -=over 8 - -=item isALNUM -X<isALNUM> - -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -alphanumeric character (including underscore) or digit. - - bool isALNUM(char ch) - -=for hackers -Found in file handy.h - -=item isALPHA -X<isALPHA> - -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -alphabetic character. - - bool isALPHA(char ch) - -=for hackers -Found in file handy.h - -=item isDIGIT -X<isDIGIT> - -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -digit. - - bool isDIGIT(char ch) - -=for hackers -Found in file handy.h - -=item isLOWER -X<isLOWER> - -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -lowercase character. - - bool isLOWER(char ch) - -=for hackers -Found in file handy.h - -=item isSPACE -X<isSPACE> - -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -whitespace. - - bool isSPACE(char ch) - -=for hackers -Found in file handy.h - -=item isUPPER -X<isUPPER> - -Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) -uppercase character. - - bool isUPPER(char ch) - -=for hackers -Found in file handy.h - -=item toLOWER -X<toLOWER> - -Converts the specified character to lowercase. Characters outside the -US-ASCII (Basic Latin) range are viewed as not having any case. - - char toLOWER(char ch) - -=for hackers -Found in file handy.h - -=item toUPPER -X<toUPPER> - -Converts the specified character to uppercase. Characters outside the -US-ASCII (Basic Latin) range are viewed as not having any case. - - char toUPPER(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 CV Manipulation Functions - -=over 8 - -=item CvSTASH -X<CvSTASH> - -Returns the stash of the CV. - - 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_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 op.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, 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>. - - 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 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 only chars above 255 will be -escaped using this style, other non printable chars will use octal or -common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH -then all chars below 255 will be treated as printable and -will be output as literals. - -If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the -string will be escaped, regardles of max. If the string is utf8 and -the chars value is >255 then it will be returned as a plain hex -sequence. Thus the output will either be a single char, -an octal escape sequence, a special escape like C<\n> or a 3 or -more digit hex value. - -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 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 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 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 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> - -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. - -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(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> - -Same as gv_fetchmeth(), but looks for autoloaded subroutines too. -Returns a glob for the subroutine. - -For an autoloaded subroutine without a GV, will create a GV even -if C<level < 0>. For an autoloaded subroutine without a stub, GvCV() -of the result may be zero. - - GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) - -=for hackers -Found in file gv.c - -=item gv_stashpv -X<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 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, STRLEN len) - -=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 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 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> - -Clears a hash, making it empty. - - 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_delete -X<hv_delete> - -Deletes a key/value pair in the hash. The value SV is removed from the -hash and returned to the caller. The C<klen> is the length of the key. -The C<flags> value will normally be zero; if set to G_DISCARD then NULL -will be returned. - - 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 and returned to the caller. The C<flags> value will normally be zero; -if set to G_DISCARD then NULL will be returned. 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 -C<klen> is the length of the key. - - 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 -C<klen> is the length of the key. 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<tb> 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_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<HvKEYS(tb)>). 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(tb)>. - - - 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<&Perl_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 C<klen> is -the length of the key. 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. - - 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 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_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_get -X<mg_get> - -Do magic after 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<perlhack/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 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 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 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 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 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. - - 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. - - 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 - - SV* vstringify(SV *vs) - -=for hackers -Found in file util.c - -=item vverify -X<vverify> - -Validates that the SV contains a valid version object. - - bool vverify(SV *vobj); - -Note that it only confirms the bare minimum structure (so as not to get -confused by derived classes which may contain additional hash entries): - - bool vverify(SV *vs) - -=for hackers -Found in file util.c - - -=back - -=head1 MRO Functions - -=over 8 - -=item mro_get_linear_isa -X<mro_get_linear_isa> - -Returns either C<mro_get_linear_isa_c3> or -C<mro_get_linear_isa_dfs> for the given stash, -dependant upon which MRO is in effect -for that 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 C<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 - - -=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 -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_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 Manipulation Functions - -=over 8 - -=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 newCONSTSUB -X<newCONSTSUB> - -Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is -eligible for inlining at compile-time. - -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(HV* stash, const char* name, 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 - - -=back - -=head1 Pad Data Structures - -=over 8 - -=item pad_sv -X<pad_sv> - -Get the value at offset po in the current pad. -Use macro PAD_SV instead of calling this function directly. - - SV* pad_sv(PADOFFSET po) - -=for hackers -Found in file 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_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) && - (tmpsv = (SV*)SvRV(sv)) && - SvTYPE(tmpsv) == SVt_PVMG && - (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr))) - { - return (REGEXP *)tmpmg->mg_obj; - } - -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 contains qr magic -(PERL_MAGIC_qr). - -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 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 %s::%s(%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 last character in the string which is in the SV. -See C<SvCUR>. Access the character as *(SvEND(sv)). - - 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. - - char* 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_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 an SV. It also tells -whether the value is defined or not. - - 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. - - 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<SvPVX>. - - 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_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. - - 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, defined or undefined. Does not handle 'get' magic. - - bool SvTRUE(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 whether 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. - - 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_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> - -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. - - bool sv_derived_from(SV* sv, const char *const name) - -=for hackers -Found in file universal.c - -=item sv_does -X<sv_does> - -Returns a boolean indicating whether the SV performs a specific, named role. -The SV can be a Perl object or the name of a Perl class. - - bool sv_does(SV* sv, const char *const name) - -=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. - - 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<perlhack/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 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. - - 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<sv2mortal()> is called on the result before -returning. If C<SVf_UTF8> is set, then it 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 be 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 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 function is only called on magical items, and is only used by -sv_true() or its macro equivalent. - - bool sv_2bool(SV *const sv) - -=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 sv_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. - - 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 -X<sv_2nv> - -Return the num value of an SV, doing any necessary string or integer -conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)> -macros. - - NV sv_2nv(SV *const sv) - -=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 *const 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 *const 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 C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if -appropriate, else not. 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_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 SVs if appropriate, else not. 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. - - 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 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_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_collxfrm -X<sv_collxfrm> - -Add Collate Transform magic to an SV if it doesn't already have it. - -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(SV *const sv, STRLEN *const nxp) - -=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. - - void sv_dec(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_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 unrefing. 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. - - void sv_inc(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 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. - - void sv_pos_u2b(SV *const sv, I32 *const offsetp, I32 *const lenp) - -=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_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_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_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. -You generally want to use the C<SvUPGRADE> macro wrapper. 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>. 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 being 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_from_utf8 -X<bytes_from_utf8> - -Converts a string C<s> of length C<len> from UTF-8 into native byte encoding. -Unlike C<utf8_to_bytes> but like C<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> from the native encoding into UTF-8. -Returns a pointer to the newly-created string, and sets C<len> to -reflect the new length. - -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 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 ibcmp_utf8 -X<ibcmp_utf8> - -Return true if the strings s1 and s2 differ case-insensitively, false -if not (if they are equal case-insensitively). If u1 is true, the -string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, -the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2 -are false, the respective string is assumed to be in native 8-bit -encoding. - -If the pe1 and pe2 are non-NULL, the scanning pointers will be copied -in there (they will point at the beginning of the I<next> character). -If the pointers behind pe1 or pe2 are non-NULL, they are the end -pointers beyond which scanning will not continue under any -circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and -s2+l2 will be used as goal end pointers that will also stop the scan, -and which qualify towards defining a successful match: all the scans -that define an explicit length must reach their goal pointers for -a match to succeed). - -For case-insensitiveness, the "casefolding" of Unicode is used -instead of upper/lowercasing both the characters, see -http://www.unicode.org/unicode/reports/tr21/ (Case Mappings). - - I32 ibcmp_utf8(const char *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_utf8_char -X<is_utf8_char> - -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. - - STRLEN is_utf8_char(const U8 *s) - -=for hackers -Found in file utf8.c - -=item is_utf8_string -X<is_utf8_string> - -Returns true if first C<len> bytes of the given string form a valid -UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does -not mean 'a string that contains code points above 0x7F encoded in UTF-8' -because a valid ASCII string is a valid UTF-8 string. - -See also is_utf8_string_loclen() and is_utf8_string_loc(). - - bool is_utf8_string(const U8 *s, STRLEN len) - -=for hackers -Found in file utf8.c - -=item is_utf8_string_loc -X<is_utf8_string_loc> - -Like is_utf8_string() but stores the location of the failure (in the -case of "utf8ness failure") or the location s+len (in the case of -"utf8ness success") in the C<ep>. - -See also is_utf8_string_loclen() and is_utf8_string(). - - bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p) - -=for hackers -Found in file utf8.c - -=item is_utf8_string_loclen -X<is_utf8_string_loclen> - -Like is_utf8_string() but stores the location of the failure (in the -case of "utf8ness failure") or the location s+len (in the case of -"utf8ness success") in the C<ep>, and the number of UTF-8 -encoded characters in the C<el>. - -See also is_utf8_string_loc() and is_utf8_string(). - - bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el) - -=for hackers -Found in file utf8.c - -=item pv_uni_display -X<pv_uni_display> - -Build to the scalar dsv a displayable version of the string spv, -length len, the displayable version being at most pvlim bytes long -(if longer, the rest is truncated and "..." will be appended). - -The flags argument can have UNI_DISPLAY_ISPRINT set to display -isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH -to display the \\[nrfta\\] as the backslashed versions (like '\n') -(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\). -UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both -UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on. - -The pointer to the PV of the dsv is returned. - - char* pv_uni_display(SV *dsv, 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 dsv a displayable version of the scalar sv, -the displayable version being at most pvlim bytes long -(if longer, the rest is truncated and "..." will be appended). - -The flags argument is as in pv_uni_display(). - -The pointer to the PV of the dsv is returned. - - char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags) - -=for hackers -Found in file utf8.c - -=item to_utf8_case -X<to_utf8_case> - -The "p" contains the pointer to the UTF-8 string encoding -the character that is being converted. - -The "ustrp" is a pointer to the character buffer to put the -conversion result to. The "lenp" is a pointer to the length -of the result. - -The "swashp" is a pointer to the swash to use. - -Both the special and normal mappings are stored lib/unicore/To/Foo.pl, -and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually, -but not always, a multicharacter mapping), is tried first. - -The "special" is a string like "utf8::ToSpecLower", which means the -hash %utf8::ToSpecLower. The access to the hash is through -Perl_to_utf8_case(). - -The "normal" is a string like "ToLower" which means the swash -%utf8::ToLower. - - UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **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 p to its foldcase version and -store that in UTF-8 in ustrp and its length in bytes in lenp. Note -that the ustrp needs to be at least UTF8_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.) - - 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 p to its lowercase version and -store that in UTF-8 in ustrp and its length in bytes in lenp. Note -that the ustrp needs to be at least UTF8_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.) - - 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 p to its titlecase version and -store that in UTF-8 in ustrp and its length in bytes in lenp. Note -that the ustrp needs to be at least UTF8_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.) - - 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 p to its uppercase version and -store that in UTF-8 in ustrp and its length in bytes in lenp. Note -that the ustrp needs to be at least UTF8_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.) - - 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> - -flags - -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. - -Allows length and flags to be passed to low level routine. - - 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 Unicode code point value of the first character in the string C<s> -which is assumed to be in UTF-8 encoding and no longer than C<curlen>; -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, the behaviour -is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY, -it is assumed that the caller will raise a warning, and this function -will silently just set C<retlen> to C<-1> and return zero. If the -C<flags> does not contain UTF8_CHECK_ONLY, warnings about -malformations will be given, C<retlen> will be set to the expected -length of the UTF-8 character in bytes, and zero will be returned. - -The C<flags> can also contain various flags to allow deviations from -the strict UTF-8 encoding (see F<utf8.h>). - -Most code should use utf8_to_uvchr() rather than call this directly. - - UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) - -=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 C<bytes_to_utf8>, this over-writes the original string, and -updates len to contain the new length. -Returns zero on failure, setting C<len> to -1. - -If you need a copy of the string, see C<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> - -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. - -If C<s> does not point to a well-formed UTF-8 character, zero is -returned and retlen is set, if possible, to -1. - - UV utf8_to_uvchr(const U8 *s, STRLEN *retlen) - -=for hackers -Found in file utf8.c - -=item utf8_to_uvuni -X<utf8_to_uvuni> - -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). - -If C<s> does not point to a well-formed UTF-8 character, zero is -returned and retlen is set, if possible, to -1. - - UV utf8_to_uvuni(const U8 *s, STRLEN *retlen) - -=for hackers -Found in file utf8.c - -=item uvchr_to_utf8 -X<uvchr_to_utf8> - -Adds the UTF-8 representation of the Native codepoint C<uv> to the end -of the string C<d>; C<d> should be 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 Unicode codepoint C<uv> to the end -of the string C<d>; C<d> should be 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); - -is the recommended Unicode-aware way of saying - - *(d++) = uv; - - 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 the C<padoff_du> variable for an XSUB that wishes to use -C<UNDERBAR>. - - 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>. - -=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 the XSUB-writer's interface to Perl's C<die> function. -Normally call this function the same way you call the C C<printf> -function. Calling C<croak> returns control directly to Perl, -sidestepping the normal C order of execution. See C<warn>. - -If you want to throw an exception object, assign the object to -C<$@> and then pass C<NULL> to croak(): - - errsv = get_sv("@", GV_ADD); - sv_setsv(errsv, exception_object); - croak(NULL); - - void croak(const char* pat, ...) - -=for hackers -Found in file util.c - -=item warn -X<warn> - -This is the XSUB-writer's interface to Perl's C<warn> function. Call this -function the same way you call the C C<printf> function. See C<croak>. - - void warn(const char* pat, ...) - -=for hackers -Found in file util.c - - -=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 - -perlguts(1), perlxs(1), perlxstut(1), perlintern(1) - -=cut - - ex: set ro: diff --git a/pod/perlintern.pod b/pod/perlintern.pod deleted file mode 100644 index 4107d5e63f..0000000000 --- a/pod/perlintern.pod +++ /dev/null @@ -1,1100 +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 - -perlintern - autogenerated documentation of purely B<internal> - Perl functions - -=head1 DESCRIPTION -X<internal Perl functions> X<interpreter functions> - -This file is the autogenerated documentation of functions in the -Perl interpreter that are documented using Perl's internal documentation -format but are not marked as part of the Perl API. In other words, -B<they are not for use in extensions>! - - -=head1 CV reference counts and CvOUTSIDE - -=over 8 - -=item CvWEAKOUTSIDE -X<CvWEAKOUTSIDE> - -Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing -CV (if any). Because pointers to anonymous sub prototypes are -stored in C<&> pad slots, it is a possible to get a circular reference, -with the parent pointing to the child and vice-versa. To avoid the -ensuing memory leak, we do not increment the reference count of the CV -pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent -has a C<&> pad slot pointing back to us. In this case, we set the -C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what -circumstances we should decrement the refcount of the parent when freeing -the child. - -There is a further complication with non-closure anonymous subs (i.e. those -that do not refer to any lexicals outside that sub). In this case, the -anonymous prototype is shared rather than being cloned. This has the -consequence that the parent may be freed while there are still active -children, eg - - BEGIN { $a = sub { eval '$x' } } - -In this case, the BEGIN is freed immediately after execution since there -are no active references to it: the anon sub prototype has -C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same -CV, so it doesn't contribute to BEGIN's refcount either. When $a is -executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed, -and the freed BEGIN is accessed. - -To avoid this, whenever a CV and its associated pad is freed, any -C<&> entries in the pad are explicitly removed from the pad, and if the -refcount of the pointed-to anon sub is still positive, then that -child's C<CvOUTSIDE> is set to point to its grandparent. This will only -occur in the single specific case of a non-closure anon prototype -having one or more active references (such as C<$a> above). - -One other thing to consider is that a CV may be merely undefined -rather than freed, eg C<undef &foo>. In this case, its refcount may -not have reached zero, but we still delete its pad and its C<CvROOT> etc. -Since various children may still have their C<CvOUTSIDE> pointing at this -undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that -the chain of lexical scopes is unbroken. For example, the following -should print 123: - - my $x = 123; - sub tmp { sub { eval '$x' } } - my $a = tmp(); - undef &tmp; - print $a->(); - - bool CvWEAKOUTSIDE(CV *cv) - -=for hackers -Found in file cv.h - - -=back - -=head1 Functions in file pad.h - - -=over 8 - -=item CX_CURPAD_SAVE -X<CX_CURPAD_SAVE> - -Save the current pad in the given context block structure. - - void CX_CURPAD_SAVE(struct context) - -=for hackers -Found in file pad.h - -=item CX_CURPAD_SV -X<CX_CURPAD_SV> - -Access the SV at offset po in the saved current pad in the given -context block structure (can be used as an lvalue). - - SV * CX_CURPAD_SV(struct context, PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_BASE_SV -X<PAD_BASE_SV> - -Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist - - SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_CLONE_VARS -X<PAD_CLONE_VARS> - -Clone the state variables associated with running and compiling pads. - - void PAD_CLONE_VARS(PerlInterpreter *proto_perl, CLONE_PARAMS* param) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_FLAGS -X<PAD_COMPNAME_FLAGS> - -Return the flags for the current compiling pad name -at offset C<po>. Assumes a valid slot entry. - - U32 PAD_COMPNAME_FLAGS(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_GEN -X<PAD_COMPNAME_GEN> - -The generation number of the name at offset C<po> in the current -compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose. - - STRLEN PAD_COMPNAME_GEN(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_GEN_set -X<PAD_COMPNAME_GEN_set> - -Sets the generation number of the name at offset C<po> in the current -ling pad (lvalue) to C<gen>. Note that C<SvUV_set> is hijacked for this purpose. - - STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_OURSTASH -X<PAD_COMPNAME_OURSTASH> - -Return the stash associated with an C<our> variable. -Assumes the slot entry is a valid C<our> lexical. - - HV * PAD_COMPNAME_OURSTASH(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_PV -X<PAD_COMPNAME_PV> - -Return the name of the current compiling pad name -at offset C<po>. Assumes a valid slot entry. - - char * PAD_COMPNAME_PV(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_TYPE -X<PAD_COMPNAME_TYPE> - -Return the type (stash) of the current compiling pad name at offset -C<po>. Must be a valid name. Returns null if not typed. - - HV * PAD_COMPNAME_TYPE(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_DUP -X<PAD_DUP> - -Clone a padlist. - - void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param) - -=for hackers -Found in file pad.h - -=item PAD_RESTORE_LOCAL -X<PAD_RESTORE_LOCAL> - -Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL() - - void PAD_RESTORE_LOCAL(PAD *opad) - -=for hackers -Found in file pad.h - -=item PAD_SAVE_LOCAL -X<PAD_SAVE_LOCAL> - -Save the current pad to the local variable opad, then make the -current pad equal to npad - - void PAD_SAVE_LOCAL(PAD *opad, PAD *npad) - -=for hackers -Found in file pad.h - -=item PAD_SAVE_SETNULLPAD -X<PAD_SAVE_SETNULLPAD> - -Save the current pad then set it to null. - - void PAD_SAVE_SETNULLPAD() - -=for hackers -Found in file pad.h - -=item PAD_SETSV -X<PAD_SETSV> - -Set the slot at offset C<po> in the current pad to C<sv> - - SV * PAD_SETSV(PADOFFSET po, SV* sv) - -=for hackers -Found in file pad.h - -=item PAD_SET_CUR -X<PAD_SET_CUR> - -Set the current pad to be pad C<n> in the padlist, saving -the previous current pad. NB currently this macro expands to a string too -long for some compilers, so it's best to replace it with - - SAVECOMPPAD(); - PAD_SET_CUR_NOSAVE(padlist,n); - - - void PAD_SET_CUR(PADLIST padlist, I32 n) - -=for hackers -Found in file pad.h - -=item PAD_SET_CUR_NOSAVE -X<PAD_SET_CUR_NOSAVE> - -like PAD_SET_CUR, but without the save - - void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n) - -=for hackers -Found in file pad.h - -=item PAD_SV -X<PAD_SV> - -Get the value at offset C<po> in the current pad - - void PAD_SV(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_SVl -X<PAD_SVl> - -Lightweight and lvalue version of C<PAD_SV>. -Get or set the value at offset C<po> in the current pad. -Unlike C<PAD_SV>, does not print diagnostics with -DX. -For internal use only. - - SV * PAD_SVl(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item SAVECLEARSV -X<SAVECLEARSV> - -Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my') - - void SAVECLEARSV(SV **svp) - -=for hackers -Found in file pad.h - -=item SAVECOMPPAD -X<SAVECOMPPAD> - -save PL_comppad and PL_curpad - - - - - - void SAVECOMPPAD() - -=for hackers -Found in file pad.h - -=item SAVEPADSV -X<SAVEPADSV> - -Save a pad slot (used to restore after an iteration) - -XXX DAPM it would make more sense to make the arg a PADOFFSET - void SAVEPADSV(PADOFFSET po) - -=for hackers -Found in file pad.h - - -=back - -=head1 GV Functions - -=over 8 - -=item is_gv_magical_sv -X<is_gv_magical_sv> - -Returns C<TRUE> if given the name of a magical GV. - -Currently only useful internally when determining if a GV should be -created even in rvalue contexts. - -C<flags> is not used at present but available for future extension to -allow selecting particular classes of magical variable. - -Currently assumes that C<name> is NUL terminated (as well as len being valid). -This assumption is met by all callers within the perl core, which all pass -pointers returned by SvPV. - - bool is_gv_magical_sv(SV *const name_sv, U32 flags) - -=for hackers -Found in file gv.c - - -=back - -=head1 Hash Manipulation Functions - -=over 8 - -=item refcounted_he_chain_2hv -X<refcounted_he_chain_2hv> - -Generates and returns a C<HV *> by walking up the tree starting at the passed -in C<struct refcounted_he *>. - - HV * refcounted_he_chain_2hv(const struct refcounted_he *c) - -=for hackers -Found in file hv.c - -=item refcounted_he_free -X<refcounted_he_free> - -Decrements the reference count of the passed in C<struct refcounted_he *> -by one. If the reference count reaches zero the structure's memory is freed, -and C<refcounted_he_free> iterates onto the parent node. - - void refcounted_he_free(struct refcounted_he *he) - -=for hackers -Found in file hv.c - -=item refcounted_he_new -X<refcounted_he_new> - -Creates a new C<struct refcounted_he>. As S<key> is copied, and value is -stored in a compact form, all references remain the property of the caller. -The C<struct refcounted_he> is returned with a reference count of 1. - - struct refcounted_he * refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value) - -=for hackers -Found in file hv.c - - -=back - -=head1 IO Functions - -=over 8 - -=item start_glob -X<start_glob> - -Function called by C<do_readline> to spawn a glob (or do the glob inside -perl on VMS). This code used to be inline, but now perl uses C<File::Glob> -this glob starter is only used by miniperl during the build process. -Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up. - - PerlIO* start_glob(SV *tmpglob, IO *io) - -=for hackers -Found in file doio.c - - -=back - -=head1 Magical Functions - -=over 8 - -=item magic_clearhint -X<magic_clearhint> - -Triggered by a delete from %^H, records the key to -C<PL_compiling.cop_hints_hash>. - - int magic_clearhint(SV* sv, MAGIC* mg) - -=for hackers -Found in file mg.c - -=item magic_sethint -X<magic_sethint> - -Triggered by a store to %^H, records the key/value pair to -C<PL_compiling.cop_hints_hash>. It is assumed that hints aren't storing -anything that would need a deep copy. Maybe we should warn if we find a -reference. - - int magic_sethint(SV* sv, MAGIC* mg) - -=for hackers -Found in file mg.c - -=item mg_localize -X<mg_localize> - -Copy some of the magic from an existing SV to new localized version of that -SV. Container magic (eg %ENV, $1, tie) gets copied, value magic doesn't (eg -taint, pos). - -If setmagic is false then no set magic will be called on the new (empty) SV. -This typically means that assignment will soon follow (e.g. 'local $x = $y'), -and that will handle the magic. - - void mg_localize(SV* sv, SV* nsv, bool setmagic) - -=for hackers -Found in file mg.c - - -=back - -=head1 MRO Functions - -=over 8 - -=item mro_get_linear_isa_dfs -X<mro_get_linear_isa_dfs> - -Returns the Depth-First Search linearization of @ISA -the given stash. The return value is a read-only AV*. -C<level> should be 0 (it is used internally in this -function's recursion). - -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_dfs(HV* stash, U32 level) - -=for hackers -Found in file mro.c - -=item mro_isa_changed_in -X<mro_isa_changed_in> - -Takes the necessary steps (cache invalidations, mostly) -when the @ISA of the given package has changed. Invoked -by the C<setisa> magic, should not need to invoke directly. - - void mro_isa_changed_in(HV* stash) - -=for hackers -Found in file mro.c - - -=back - -=head1 Pad Data Structures - -=over 8 - -=item CvPADLIST -X<CvPADLIST> - -CV's can have CvPADLIST(cv) set to point to an AV. - -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 does not have AvREAL set, so REFCNT of component items -is managed "manual" (mostly in pad.c) rather than normal av.c rules. -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. - -During compilation: -C<PL_comppad_name> is set to the names AV. -C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1. -C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)). - -During execution, C<PL_comppad> and C<PL_curpad> refer to the live -frame of the currently executing sub. - -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. 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 SVf_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, SVf_PADSTALE is overloaded to mean 'not yet initialised' - - AV * CvPADLIST(CV *cv) - -=for hackers -Found in file pad.c - -=item cv_clone -X<cv_clone> - -Clone a CV: make a new CV which points to the same code etc, but which -has a newly-created pad built by copying the prototype pad and capturing -any outer lexicals. - - CV* cv_clone(CV* proto) - -=for hackers -Found in file pad.c - -=item cv_dump -X<cv_dump> - -dump the contents of a CV - - void cv_dump(const CV *cv, const char *title) - -=for hackers -Found in file pad.c - -=item do_dump_pad -X<do_dump_pad> - -Dump the contents of a padlist - - void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full) - -=for hackers -Found in file pad.c - -=item intro_my -X<intro_my> - -"Introduce" my variables to visible status. - - U32 intro_my() - -=for hackers -Found in file pad.c - -=item pad_add_anon -X<pad_add_anon> - -Add an anon code entry to the current compiling pad - - PADOFFSET pad_add_anon(SV* sv, OPCODE op_type) - -=for hackers -Found in file pad.c - -=item pad_add_name -X<pad_add_name> - -Create a new name and associated PADMY SV in the current pad; return the -offset. -If C<typestash> is valid, the name is for a typed lexical; set the -name's stash to that value. -If C<ourstash> is valid, it's an our lexical, set the name's -SvOURSTASH to that value - -If fake, it means we're cloning an existing entry - - PADOFFSET pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state) - -=for hackers -Found in file pad.c - -=item pad_alloc -X<pad_alloc> - -Allocate a new my or tmp pad entry. For a my, simply push a null SV onto -the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards -for a slot which has no name and no active value. - - PADOFFSET pad_alloc(I32 optype, U32 tmptype) - -=for hackers -Found in file pad.c - -=item pad_block_start -X<pad_block_start> - -Update the pad compilation state variables on entry to a new block - - void pad_block_start(int full) - -=for hackers -Found in file pad.c - -=item pad_check_dup -X<pad_check_dup> - -Check for duplicate declarations: report any of: - * a my in the current scope with the same name; - * an our (anywhere in the pad) with the same name and the same stash - as C<ourstash> -C<is_our> indicates that the name to check is an 'our' declaration - - void pad_check_dup(const char* name, bool is_our, const HV* ourstash) - -=for hackers -Found in file pad.c - -=item pad_findlex -X<pad_findlex> - -Find a named lexical anywhere in a chain of nested pads. Add fake entries -in the inner pads if it's found in an outer one. - -Returns the offset in the bottom pad of the lex or the fake lex. -cv is the CV in which to start the search, and seq is the current cop_seq -to match against. If warn is true, print appropriate warnings. The out_* -vars return values, and so are pointers to where the returned values -should be stored. out_capture, if non-null, requests that the innermost -instance of the lexical is captured; out_name_sv is set to the innermost -matched namesv or fake namesv; out_flags returns the flags normally -associated with the IVX field of a fake namesv. - -Note that pad_findlex() is recursive; it recurses up the chain of CVs, -then comes back down, adding fake entries as it goes. It has to be this way -because fake namesvs in anon protoypes have to store in xlow the index into -the parent pad. - - PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags) - -=for hackers -Found in file pad.c - -=item pad_findmy -X<pad_findmy> - -Given a lexical name, try to find its offset, first in the current pad, -or failing that, in the pads of any lexically enclosing subs (including -the complications introduced by eval). If the name is found in an outer pad, -then a fake entry is added to the current pad. -Returns the offset in the current pad, or NOT_IN_PAD on failure. - - PADOFFSET pad_findmy(const char* name) - -=for hackers -Found in file pad.c - -=item pad_fixup_inner_anons -X<pad_fixup_inner_anons> - -For any anon CVs in the pad, change CvOUTSIDE of that CV from -old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be -moved to a pre-existing CV struct. - - void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv) - -=for hackers -Found in file pad.c - -=item pad_free -X<pad_free> - -Free the SV at offset po in the current pad. - - void pad_free(PADOFFSET po) - -=for hackers -Found in file pad.c - -=item pad_leavemy -X<pad_leavemy> - -Cleanup at end of scope during compilation: set the max seq number for -lexicals in this scope and warn of any lexicals that never got introduced. - - void pad_leavemy() - -=for hackers -Found in file pad.c - -=item pad_new -X<pad_new> - -Create a new compiling padlist, saving and updating the various global -vars at the same time as creating the pad itself. The following flags -can be OR'ed together: - - padnew_CLONE this pad is for a cloned CV - padnew_SAVE save old globals - padnew_SAVESUB also save extra stuff for start of sub - - PADLIST* pad_new(int flags) - -=for hackers -Found in file pad.c - -=item pad_push -X<pad_push> - -Push a new pad frame onto the padlist, unless there's already a pad at -this depth, in which case don't bother creating a new one. Then give -the new pad an @_ in slot zero. - - void pad_push(PADLIST *padlist, int depth) - -=for hackers -Found in file pad.c - -=item pad_reset -X<pad_reset> - -Mark all the current temporaries for reuse - - void pad_reset() - -=for hackers -Found in file pad.c - -=item pad_setsv -X<pad_setsv> - -Set the entry at offset po in the current pad to sv. -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_swipe -X<pad_swipe> - -Abandon the tmp in the current pad at offset po and replace with a -new one. - - void pad_swipe(PADOFFSET po, bool refadjust) - -=for hackers -Found in file pad.c - -=item pad_tidy -X<pad_tidy> - -Tidy up a pad after we've finished compiling it: - * remove most stuff from the pads of anonsub prototypes; - * give it a @_; - * mark tmps as such. - - void pad_tidy(padtidy_type type) - -=for hackers -Found in file pad.c - -=item pad_undef -X<pad_undef> - -Free the padlist associated with a CV. -If parts of it happen to be current, we null the relevant -PL_*pad* global vars so that we don't have any dangling references left. -We also repoint the CvOUTSIDE of any about-to-be-orphaned -inner subs to the outer of this cv. - -(This function should really be called pad_free, but the name was already -taken) - - void pad_undef(CV* cv) - -=for hackers -Found in file pad.c - - -=back - -=head1 Per-Interpreter Variables - -=over 8 - -=item PL_DBsingle -X<PL_DBsingle> - -When Perl is run in debugging mode, with the B<-d> switch, this SV is a -boolean which indicates whether subs are being single-stepped. -Single-stepping is automatically turned on after every step. This is the C -variable which corresponds to Perl's $DB::single variable. See -C<PL_DBsub>. - - SV * PL_DBsingle - -=for hackers -Found in file intrpvar.h - -=item PL_DBsub -X<PL_DBsub> - -When Perl is run in debugging mode, with the B<-d> switch, this GV contains -the SV which holds the name of the sub being debugged. This is the C -variable which corresponds to Perl's $DB::sub variable. See -C<PL_DBsingle>. - - GV * PL_DBsub - -=for hackers -Found in file intrpvar.h - -=item PL_DBtrace -X<PL_DBtrace> - -Trace variable used when Perl is run in debugging mode, with the B<-d> -switch. This is the C variable which corresponds to Perl's $DB::trace -variable. See C<PL_DBsingle>. - - SV * PL_DBtrace - -=for hackers -Found in file intrpvar.h - -=item PL_dowarn -X<PL_dowarn> - -The C variable which corresponds to Perl's $^W warning variable. - - bool PL_dowarn - -=for hackers -Found in file intrpvar.h - -=item PL_last_in_gv -X<PL_last_in_gv> - -The GV which was last used for a filehandle input operation. (C<< <FH> >>) - - GV* PL_last_in_gv - -=for hackers -Found in file intrpvar.h - -=item PL_ofsgv -X<PL_ofsgv> - -The glob containing the output field separator - C<*,> in Perl space. - - GV* PL_ofsgv - -=for hackers -Found in file intrpvar.h - -=item PL_rs -X<PL_rs> - -The input record separator - C<$/> in Perl space. - - SV* PL_rs - -=for hackers -Found in file intrpvar.h - - -=back - -=head1 Stack Manipulation Macros - -=over 8 - -=item djSP -X<djSP> - -Declare Just C<SP>. This is actually identical to C<dSP>, and declares -a local copy of perl's stack pointer, available via the C<SP> macro. -See C<SP>. (Available for backward source code compatibility with the -old (Perl 5.005) thread model.) - - djSP; - -=for hackers -Found in file pp.h - -=item LVRET -X<LVRET> - -True if this op will be the return value of an lvalue subroutine - -=for hackers -Found in file pp.h - - -=back - -=head1 SV Manipulation Functions - -=over 8 - -=item sv_add_arena -X<sv_add_arena> - -Given a chunk of memory, link it to the head of the list of arenas, -and split it into a list of free SVs. - - void sv_add_arena(char *const ptr, const U32 size, const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_clean_all -X<sv_clean_all> - -Decrement the refcnt of each remaining SV, possibly triggering a -cleanup. This function may have to be called multiple times to free -SVs which are in complex self-referential hierarchies. - - I32 sv_clean_all() - -=for hackers -Found in file sv.c - -=item sv_clean_objs -X<sv_clean_objs> - -Attempt to destroy all objects not yet freed - - void sv_clean_objs() - -=for hackers -Found in file sv.c - -=item sv_free_arenas -X<sv_free_arenas> - -Deallocate the memory used by all arenas. Note that all the individual SV -heads and bodies within the arenas must already have been freed. - - void sv_free_arenas() - -=for hackers -Found in file sv.c - - -=back - -=head1 SV-Body Allocation - -=over 8 - -=item sv_2num -X<sv_2num> - -Return an SV with the numeric value of the source SV, doing any necessary -reference or overload conversion. You must use the C<SvNUM(sv)> macro to -access this function. - - SV* sv_2num(SV *const sv) - -=for hackers -Found in file sv.c - - -=back - -=head1 Unicode Support - -=over 8 - -=item find_uninit_var -X<find_uninit_var> - -Find the name of the undefined variable (if any) that caused the operator o -to issue a "Use of uninitialized value" warning. -If match is true, only return a name if it's value matches uninit_sv. -So roughly speaking, if a unary operator (such as OP_COS) generates a -warning, then following the direct child of the op may yield an -OP_PADSV or OP_GV that gives the name of the undefined variable. On the -other hand, with OP_ADD there are two branches to follow, so we only print -the variable name if we get an exact match. - -The name is returned as a mortal SV. - -Assumes that PL_op is the op that originally triggered the error, and that -PL_comppad/PL_curpad points to the currently executing pad. - - SV* find_uninit_var(const OP *const obase, const SV *const uninit_sv, bool top) - -=for hackers -Found in file sv.c - -=item report_uninit -X<report_uninit> - -Print appropriate "Use of uninitialized variable" warning - - void report_uninit(const SV *uninit_sv) - -=for hackers -Found in file sv.c - - -=back - -=head1 AUTHORS - -The autodocumentation system was originally added to the Perl core by -Benjamin Stuhl. Documentation is by whoever was kind enough to -document their functions. - -=head1 SEE ALSO - -perlguts(1), perlapi(1) - -=cut - - ex: set ro: diff --git a/vms/descrip_mms.template b/vms/descrip_mms.template index b8ea2c11b0..6730bccc17 100644 --- a/vms/descrip_mms.template +++ b/vms/descrip_mms.template @@ -428,6 +428,9 @@ pod = $(pod0) $(pod1) $(pod2) $(pod3) $(pod4) $(pod5) $(pod6) $(pod7) $(pod8) $( [.pod]perldelta.pod : [.pod]perl5100delta.pod Copy/NoConfirm/Log $(MMS$SOURCE) $(MMS$TARGET) +[.pod]perlapi.pod [.pod]perlintern.pod : miniperl embed.fnc autodoc.pl + $(MINIPERL) autodoc.pl + perlpods : $(pod) @ $(NOOP) @@ -1850,6 +1853,8 @@ clean : tidy cleantest cleanup_unpacked_files - If F$Search("[.vms.ext...]*$(O)").nes."" Then Delete/NoConfirm/Log [.vms.ext...]*$(O);* - If F$Search("[.pod]*.com").nes."" Then Delete/NoConfirm/Log [.pod]*.com;* - If F$Search("[.pod]perldelta.pod").nes."" Then Delete/NoConfirm/Log [.pod]perldelta.pod;* + - If F$Search("[.pod]perlintern.pod").nes."" Then Delete/NoConfirm/Log [.pod]perlintern.pod;* + - If F$Search("[.pod]perlapi.pod").nes."" Then Delete/NoConfirm/Log [.pod]perlapi.pod;* - @extra_pods CLEAN - If F$Search("unpushed.h").nes."" Then Delete/NoConfirm/Log unpushed.h;* - If F$Search("[.lib]Config_git.pl").nes."" Then Delete/NoConfirm/Log [.lib]Config_git.pl;* diff --git a/win32/Makefile b/win32/Makefile index 3de30cb2ea..dde2a36e8c 100644 --- a/win32/Makefile +++ b/win32/Makefile @@ -1138,6 +1138,9 @@ utils: $(PERLEXE) $(X2P) $(PERLEXE) lib_pm.PL cd ..\win32 $(PERLEXE) $(PL2BAT) $(UTILS) + cd .. + $(PERLEXE) autodoc.pl + cd win32 # Note that the pod cleanup in this next section is parsed (and regenerated # by pod/buildtoc so please check that script before making changes here @@ -1211,6 +1214,7 @@ distclean: realclean perltw.pod perluts.pod perlvmesa.pod perlvms.pod perlvms.pod \ perlvos.pod perlwin32.pod \ pod2html pod2latex pod2man pod2text pod2usage \ + perlapi.pod perlintern.pod \ podchecker podselect -cd ..\utils && del /f h2ph splain perlbug pl2pm c2ph pstruct h2xs \ perldoc perlivp dprofpp libnetcfg enc2xs piconv cpan *.bat \ diff --git a/win32/makefile.mk b/win32/makefile.mk index 915d8b9e9e..6f2f5d88ae 100644 --- a/win32/makefile.mk +++ b/win32/makefile.mk @@ -1460,6 +1460,7 @@ utils: $(PERLEXE) $(X2P) cd ..\pod && $(MAKE) -f ..\win32\pod.mak converters cd ..\lib && $(PERLEXE) lib_pm.PL $(PERLEXE) $(PL2BAT) $(UTILS) + cd .. && $(PERLEXE) autodoc.pl # Note that the pod cleanup in this next section is parsed (and regenerated # by pod/buildtoc so please check that script before making changes here @@ -1533,6 +1534,7 @@ distclean: realclean perltw.pod perluts.pod perlvmesa.pod perlvms.pod perlvms.pod \ perlvos.pod perlwin32.pod \ pod2html pod2latex pod2man pod2text pod2usage \ + perlapi.pod perlintern.pod \ podselect -cd ..\utils && del /f h2ph splain perlbug pl2pm c2ph pstruct h2xs \ perldoc perlivp dprofpp libnetcfg enc2xs piconv cpan *.bat \ |