From: Nicholas Clark Date: Sat, 18 Apr 2009 11:19:57 +0000 (+0100) Subject: Generate perlapi.pod and perlintern.pod at build time, instead of shipping them. X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=344af494c35a9f0f50dab51474b2e7cd806f1b08;p=p5sagit%2Fp5-mst-13.2.git Generate perlapi.pod and perlintern.pod at build time, instead of shipping them. --- diff --git a/MANIFEST b/MANIFEST index 21c6a76..f6d34b1 100644 --- a/MANIFEST +++ b/MANIFEST @@ -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 dd4ea3f..156d275 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 diff --git a/pod.lst b/pod.lst index cf4ec98..3226b38 100644 --- a/pod.lst +++ b/pod.lst @@ -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 2e2f9c9..b9cc759 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 4054fda..5a680b1 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 () { $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 7498939..0000000 --- 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 X X - -This file contains the documentation of the perl public API generated by -embed.pl, specifically a listing of functions, macros, flags, and variables -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 -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) -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 -(and variants of that name, including in function names), -it also (essentially transparently) means C. -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 - -A backward-compatible version of C which can only return -C or C; in a void context, it returns C. -Deprecated. Use C instead. - - U32 GIMME - -=for hackers -Found in file op.h - -=item GIMME_V -X - -The XSUB-writer's equivalent to Perl's C. Returns C, -C or C for void, scalar or list context, -respectively. - - U32 GIMME_V - -=for hackers -Found in file op.h - -=item G_ARRAY -X - -Used to indicate list context. See C, C and -L. - -=for hackers -Found in file cop.h - -=item G_DISCARD -X - -Indicates that arguments returned from a callback should be discarded. See -L. - -=for hackers -Found in file cop.h - -=item G_EVAL -X - -Used to force a Perl C wrapper around a callback. See -L. - -=for hackers -Found in file cop.h - -=item G_NOARGS -X - -Indicates that no arguments are being sent to a callback. See -L. - -=for hackers -Found in file cop.h - -=item G_SCALAR -X - -Used to indicate scalar context. See C, C, and -L. - -=for hackers -Found in file cop.h - -=item G_VOID -X - -Used to indicate void context. See C and L. - -=for hackers -Found in file cop.h - - -=back - -=head1 Array Manipulation Functions - -=over 8 - -=item AvFILL -X - -Same as C. Deprecated, use C instead. - - int AvFILL(AV* av) - -=for hackers -Found in file av.h - -=item av_clear -X - -Clears an array, making it empty. Does not free the memory used by the -array itself. - - void av_clear(AV *av) - -=for hackers -Found in file av.c - -=item av_create_and_push -X - -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 - -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 - -Deletes the element indexed by C from the array. Returns the -deleted element. If C equals C, 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 - -Returns true if the element indexed by C 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 - -Pre-extend an array. The C 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 - -Returns the SV at the specified index in the array. The C is the -index. If C is set then the fetch will be part of a store. Check -that the return value is non-null before dereferencing it to a C. - -See L 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 - -Set the highest index in the array to the given number, equivalent to -Perl's C<$#array = $fill;>. - -The number of elements in the an array will be C after -av_fill() returns. If the array was previously shorter then the -additional elements appended are set to C. If the array -was longer, then the excess elements are freed. C is -the same as C. - - void av_fill(AV *av, I32 fill) - -=for hackers -Found in file av.c - -=item av_len -X - -Returns the highest index in the array. The number of elements in the -array is C. Returns -1 if the array is empty. - - I32 av_len(AV *av) - -=for hackers -Found in file av.c - -=item av_make -X - -Creates a new AV and populates it with a list of SVs. The SVs are copied -into the array, so they may be freed after the call to av_make. The new AV -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 - -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 - -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 - -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 - -Stores an SV in an array. The array index is specified as C. The -return value will be NULL if the operation failed or if the value did not -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. Note -that the caller is responsible for suitably incrementing the reference -count of C before the call, and decrementing it if the function -returned NULL. - -See L 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 - -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 - -Unshift the given number of C values onto the beginning of the -array. The array will grow automatically to accommodate the addition. You -must then use C 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 - -Returns the AV of the specified Perl array. C are passed to -C. If C is set and the -Perl variable does not exist then it will be created. If C 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 - -Creates a new AV. The reference count is set to 1. - - AV* newAV() - -=for hackers -Found in file av.h - -=item sortsv -X - -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 - -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 - -Performs a callback to the specified Perl sub. See L. - -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 - -Performs a callback to the specified Perl method. The blessed object must -be on the stack. See L. - -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 - -Performs a callback to the specified Perl sub. See L. - -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 - -Performs a callback to the Perl sub whose name is in the SV. See -L. - -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 - -Opening bracket on a callback. See C and L. - - ENTER; - -=for hackers -Found in file scope.h - -=item eval_pv -X - -Tells Perl to C 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 - -Tells Perl to C 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 - -Closing bracket for temporaries on a callback. See C and -L. - - FREETMPS; - -=for hackers -Found in file scope.h - -=item LEAVE -X - -Closing bracket on a callback. See C and L. - - LEAVE; - -=for hackers -Found in file scope.h - -=item SAVETMPS -X - -Opening bracket for temporaries on a callback. See C and -L. - - SAVETMPS; - -=for hackers -Found in file scope.h - - -=back - -=head1 Character classes - -=over 8 - -=item isALNUM -X - -Returns a boolean indicating whether the C C 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 - -Returns a boolean indicating whether the C C is a US-ASCII (Basic Latin) -alphabetic character. - - bool isALPHA(char ch) - -=for hackers -Found in file handy.h - -=item isDIGIT -X - -Returns a boolean indicating whether the C C is a US-ASCII (Basic Latin) -digit. - - bool isDIGIT(char ch) - -=for hackers -Found in file handy.h - -=item isLOWER -X - -Returns a boolean indicating whether the C C is a US-ASCII (Basic Latin) -lowercase character. - - bool isLOWER(char ch) - -=for hackers -Found in file handy.h - -=item isSPACE -X - -Returns a boolean indicating whether the C C is a US-ASCII (Basic Latin) -whitespace. - - bool isSPACE(char ch) - -=for hackers -Found in file handy.h - -=item isUPPER -X - -Returns a boolean indicating whether the C C is a US-ASCII (Basic Latin) -uppercase character. - - bool isUPPER(char ch) - -=for hackers -Found in file handy.h - -=item toLOWER -X - -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 - -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 - -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, -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 - -Returns the stash of the CV. - - HV* CvSTASH(CV* cv) - -=for hackers -Found in file cv.h - -=item get_cv -X - -Uses C to get the length of C, then calls C. - -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 - -Returns the CV of the specified Perl subroutine. C are passed to -C. If C is set and the Perl subroutine does not -exist then it will be declared (which has the same effect as saying -C). If C is not set and the subroutine does not exist -then NULL is returned. - -NOTE: the perl_ form of this function is deprecated. - - 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 - -Clear out all the active components of a CV. This can happen either -by an explicit C, or by the reference count going to zero. -In the former case, we keep the CvOUTSIDE pointer, so that any anonymous -children can still follow the full lexical scope chain. - - void cv_undef(CV* cv) - -=for hackers -Found in file op.c - -=item load_module -X - -Loads the module whose name is pointed to by the string part of name. -Note that the actual module name, not its filename, should be given. -Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of -PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS -(or 0 for no flags). ver, if specified, provides version semantics -similar to C. The optional trailing SV* -arguments can be used to specify arguments to the module's import() -method, similar to C. - - void load_module(U32 flags, SV* name, SV* ver, ...) - -=for hackers -Found in file op.c - -=item nothreadhook -X - -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 - -Allocates a new Perl interpreter. See L. - - PerlInterpreter* perl_alloc() - -=for hackers -Found in file perl.c - -=item perl_construct -X - -Initializes a new Perl interpreter. See L. - - void perl_construct(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item perl_destruct -X - -Shuts down a Perl interpreter. See L. - - int perl_destruct(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item perl_free -X - -Releases a Perl interpreter. See L. - - void perl_free(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item perl_parse -X - -Tells a Perl interpreter to parse a Perl script. See L. - - 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 - -Tells a Perl interpreter to run. See L. - - int perl_run(PerlInterpreter *my_perl) - -=for hackers -Found in file perl.c - -=item require_pv -X - -Tells Perl to C the file named by the string argument. It is -analogous to the Perl code C. It's even -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 - -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 - -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 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 - -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 - -See L. - - GV* gv_fetchmethod(HV* stash, const char* name) - -=for hackers -Found in file mathoms.c - -=item pack_cat -X - -The engine implementing pack() Perl function. Note: parameters next_in_list and -flags are not used. This call should not be used; use packlist instead. - - void pack_cat(SV *cat, 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 - -Return a pointer to the byte-encoded representation of the SV. -May cause the SV to be downgraded from UTF-8 as a side-effect. - -Usually accessed via the C macro. - - char* sv_2pvbyte_nolen(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_2pvutf8_nolen -X - -Return a pointer to the UTF-8-encoded representation of the SV. -May cause the SV to be upgraded to UTF-8 as a side-effect. - -Usually accessed via the C macro. - - char* sv_2pvutf8_nolen(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_2pv_nolen -X - -Like C, but doesn't return the length too. You should usually -use the macro wrapper C instead. - char* sv_2pv_nolen(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_catpvn_mg -X - -Like C, but also handles 'set' magic. - - void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len) - -=for hackers -Found in file mathoms.c - -=item sv_catsv_mg -X - -Like C, but also handles 'set' magic. - - void sv_catsv_mg(SV *dsv, SV *ssv) - -=for hackers -Found in file mathoms.c - -=item sv_force_normal -X - -Undo various types of fakery on an SV: if the PV is a shared string, make -a private copy; if we're a ref, stop refing; if we're a glob, downgrade to -an xpvmg. See also C. - - void sv_force_normal(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_iv -X - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - IV sv_iv(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_nolocking -X - -Dummy routine which "locks" an SV when there is no locking module present. -Exists to avoid test for a NULL function pointer and because it could -potentially warn under some level of strict-ness. - -"Superseded" by sv_nosharing(). - - void sv_nolocking(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_nounlocking -X - -Dummy routine which "unlocks" an SV when there is no locking module present. -Exists to avoid test for a NULL function pointer and because it could -potentially warn under some level of strict-ness. - -"Superseded" by sv_nosharing(). - - void sv_nounlocking(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_nv -X - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - NV sv_nv(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_pv -X - -Use the C macro instead - - char* sv_pv(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_pvbyte -X - -Use C instead. - - char* sv_pvbyte(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_pvbyten -X - -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. - - char* sv_pvbyten(SV *sv, STRLEN *lp) - -=for hackers -Found in file mathoms.c - -=item sv_pvn -X - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - char* sv_pvn(SV *sv, STRLEN *lp) - -=for hackers -Found in file mathoms.c - -=item sv_pvutf8 -X - -Use the C macro instead - - char* sv_pvutf8(SV *sv) - -=for hackers -Found in file mathoms.c - -=item sv_pvutf8n -X - -A private implementation of the C macro for compilers -which can't cope with complex macro expressions. Always use the macro -instead. - - char* sv_pvutf8n(SV *sv, STRLEN *lp) - -=for hackers -Found in file mathoms.c - -=item sv_taint -X - -Taint an SV. Use C instead. - void sv_taint(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_unref -X - -Unsets the RV status of the SV, and decrements the reference count of -whatever was being referenced by the RV. This can almost be thought of -as a reversal of C. This is C with the C -being zero. See C. - - void sv_unref(SV* sv) - -=for hackers -Found in file mathoms.c - -=item sv_usepvn -X - -Tells an SV to use C to find its string value. Implemented by -calling C with C of 0, hence does not handle 'set' -magic. See C. - - void sv_usepvn(SV* sv, char* ptr, STRLEN len) - -=for hackers -Found in file mathoms.c - -=item sv_usepvn_mg -X - -Like C, but also handles 'set' magic. - - void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len) - -=for hackers -Found in file mathoms.c - -=item sv_uv -X - -A private implementation of the C macro for compilers which can't -cope with complex macro expressions. Always use the macro instead. - - UV sv_uv(SV* sv) - -=for hackers -Found in file mathoms.c - -=item unpack_str -X - -The engine implementing unpack() Perl function. Note: parameters strbeg, new_s -and ocnt are not used. This call should not be used, use unpackstring instead. - - I32 unpack_str(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 - -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 - -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 - -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 - -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 - -The engine implementing pack() Perl function. - - void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist) - -=for hackers -Found in file pp_pack.c - -=item unpackstring -X - -The engine implementing unpack() Perl function. C puts the -extracted list items on the stack and returns the number of elements. -Issue C before and C after the call to this function. - - I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags) - -=for hackers -Found in file pp_pack.c - - -=back - -=head1 Functions in file pp_sys.c - - -=over 8 - -=item setdefout -X - -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 - -Return the SV from the GV. - - SV* GvSV(GV* gv) - -=for hackers -Found in file gv.h - -=item gv_const_sv -X - -If C is a typeglob whose subroutine entry is a constant sub eligible for -inlining, or C is a placeholder reference that would be promoted to such -a typeglob, then returns the value returned by the sub. Otherwise, returns -NULL. - - SV* gv_const_sv(GV* gv) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth -X - -Returns the glob with the given C and a defined subroutine or -C. The glob lives in the given C, or in the stashes -accessible via @ISA and UNIVERSAL::. - -The argument C should be either 0 or -1. If C, as a -side-effect creates a glob with the given C in the given C -which in the case of success contains an alias for the subroutine, and sets -up caching info for this glob. - -This function grants C<"SUPER"> token as a postfix of the stash name. The -GV returned from C may be a method cache entry, which is not -visible to Perl code. So when calling C, you should not use -the GV directly; instead, you should use the method's CV, which can be -obtained from the GV with the C macro. - - GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level) - -=for hackers -Found in file gv.c - -=item gv_fetchmethod_autoload -X - -Returns the glob which contains the subroutine to call to invoke the method -on the C. In fact in the presence of autoloading this may be the -glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is -already setup. - -The third parameter of C determines whether -AUTOLOAD lookup is performed if the given method is not present: non-zero -means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD. -Calling C is equivalent to calling C -with a non-zero C parameter. - -These functions grant C<"SUPER"> token as a prefix of the method name. Note -that if you want to keep the returned glob for a long time, you need to -check for it being "AUTOLOAD", since at the later time the call may load a -different subroutine due to $AUTOLOAD changing its value. Use the glob -created via a side effect to do this. - -These functions have the same side-effects and as C with -C. C should be writable if contains C<':'> or C<' -''>. The warning against passing the GV returned by C to -C apply equally to these functions. - - GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload) - -=for hackers -Found in file gv.c - -=item gv_fetchmeth_autoload -X - -Same as gv_fetchmeth(), but looks for autoloaded subroutines too. -Returns a glob for the subroutine. - -For an autoloaded subroutine without a GV, will create a GV even -if C. For an autoloaded subroutine without a stub, GvCV() -of the result may be zero. - - GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level) - -=for hackers -Found in file gv.c - -=item gv_stashpv -X - -Returns a pointer to the stash for a specified package. Uses C to -determine the length of C, then calls C. - - HV* gv_stashpv(const char* name, I32 flags) - -=for hackers -Found in file gv.c - -=item gv_stashpvn -X - -Returns a pointer to the stash for a specified package. The C -parameter indicates the length of the C, in bytes. C is passed -to C, so if set to C then the package will be -created if it does not already exist. If the package does not exist and -C 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 - -Like C, but takes a literal string instead of a string/length pair. - - HV* gv_stashpvs(const char* name, I32 create) - -=for hackers -Found in file handy.h - -=item gv_stashsv -X - -Returns a pointer to the stash for a specified package. See C. - - HV* gv_stashsv(SV* sv, I32 flags) - -=for hackers -Found in file gv.c - - -=back - -=head1 Handy Values - -=over 8 - -=item Nullav -X - -Null AV pointer. - -(deprecated - use C<(AV *)NULL> instead) - -=for hackers -Found in file av.h - -=item Nullch -X - -Null character pointer. (No longer available when C is defined.) - -=for hackers -Found in file handy.h - -=item Nullcv -X - -Null CV pointer. - -(deprecated - use C<(CV *)NULL> instead) - -=for hackers -Found in file cv.h - -=item Nullhv -X - -Null HV pointer. - -(deprecated - use C<(HV *)NULL> instead) - -=for hackers -Found in file hv.h - -=item Nullsv -X - -Null SV pointer. (No longer available when C is defined.) - -=for hackers -Found in file handy.h - - -=back - -=head1 Hash Manipulation Functions - -=over 8 - -=item get_hv -X - -Returns the HV of the specified Perl hash. C are passed to -C. If C is set and the -Perl variable does not exist then it will be created. If C 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 - -This flag, used in the length slot of hash entries and magic structures, -specifies the structure contains an C pointer where a C pointer -is to be expected. (For information only--not to be used). - -=for hackers -Found in file hv.h - -=item HeHASH -X - -Returns the computed hash stored in the hash entry. - - U32 HeHASH(HE* he) - -=for hackers -Found in file hv.h - -=item HeKEY -X - -Returns the actual pointer stored in the key slot of the hash entry. The -pointer may be either C or C, depending on the value of -C. Can be assigned to. The C or C 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 - -If this is negative, and amounts to C, it indicates the entry -holds an C key. Otherwise, holds the actual length of the key. Can -be assigned to. The C macro is usually preferable for finding key -lengths. - - STRLEN HeKLEN(HE* he) - -=for hackers -Found in file hv.h - -=item HePV -X - -Returns the key slot of the hash entry as a C value, doing any -necessary dereferencing of possibly C keys. The length of the string -is placed in C (this is a macro, so do I use C<&len>). If you do -not care about what the length of the key is, you may use the global -variable C, 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 or similar is not a good way to find -the length of hash keys. This is very similar to the C macro -described elsewhere in this document. See also C. - -If you are using C to get values to pass to C to create a -new SV, you should consider using C as it is more -efficient. - - char* HePV(HE* he, STRLEN len) - -=for hackers -Found in file hv.h - -=item HeSVKEY -X - -Returns the key as an C, or C if the hash entry does not -contain an C key. - - SV* HeSVKEY(HE* he) - -=for hackers -Found in file hv.h - -=item HeSVKEY_force -X - -Returns the key as an C. Will create and return a temporary mortal -C if the hash entry contains only a C key. - - SV* HeSVKEY_force(HE* he) - -=for hackers -Found in file hv.h - -=item HeSVKEY_set -X - -Sets the key to a given C, taking care to set the appropriate flags to -indicate the presence of an C key, and returns the same -C. - - SV* HeSVKEY_set(HE* he, SV* sv) - -=for hackers -Found in file hv.h - -=item HeUTF8 -X - -Returns whether the C value returned by C is encoded in UTF-8, -doing any necessary dereferencing of possibly C keys. The value returned -will be 0 or non-0, not necessarily 1 (or even a value with any low bits set), -so B blindly assign this to a C variable, as C may be a -typedef for C. - - char* HeUTF8(HE* he, STRLEN len) - -=for hackers -Found in file hv.h - -=item HeVAL -X - -Returns the value slot (type C) stored in the hash entry. - - SV* HeVAL(HE* he) - -=for hackers -Found in file hv.h - -=item HvNAME -X - -Returns the package name of a stash, or NULL if C isn't a stash. -See C, C. - - char* HvNAME(HV* stash) - -=for hackers -Found in file hv.h - -=item hv_assert -X - -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 - -Clears a hash, making it empty. - - void hv_clear(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_clear_placeholders -X - -Clears any placeholders from a hash. If a restricted hash has any of its keys -marked as readonly and the key is subsequently deleted, the key is not actually -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 - -Deletes a key/value pair in the hash. The value SV is removed from the -hash and returned to the caller. The C is the length of the key. -The C 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 - -Deletes a key/value pair in the hash. The value SV is removed from the -hash and returned to the caller. The C value will normally be zero; -if set to G_DISCARD then NULL will be returned. C 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 - -Returns a boolean indicating whether the specified hash key exists. The -C 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 - -Returns a boolean indicating whether the specified hash key exists. C -can be a valid precomputed hash value, or 0 to ask for it to be -computed. - - bool hv_exists_ent(HV *hv, SV *keysv, U32 hash) - -=for hackers -Found in file hv.c - -=item hv_fetch -X - -Returns the SV which corresponds to the specified key in the hash. The -C is the length of the key. If C is set then the fetch will be -part of a store. Check that the return value is non-null before -dereferencing it to an C. - -See L 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 - -Like C, but takes a literal string instead of a string/length pair. - - SV** hv_fetchs(HV* tb, const char* key, I32 lval) - -=for hackers -Found in file handy.h - -=item hv_fetch_ent -X - -Returns the hash entry which corresponds to the specified key in the hash. -C must be a valid precomputed hash number for the given C, or 0 -if you want the function to compute it. IF C 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 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 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 - -Prepares a starting point to traverse a hash table. Returns the number of -keys in the hash (i.e. the same as C). The return value is -currently only meaningful for hashes without tie magic. - -NOTE: Before version 5.004_65, C used to return the number of -hash buckets that happen to be in use. If you still need that esoteric -value, you can get it through the macro C. - - - I32 hv_iterinit(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_iterkey -X - -Returns the key from the current position of the hash iterator. See -C. - - char* hv_iterkey(HE* entry, I32* retlen) - -=for hackers -Found in file hv.c - -=item hv_iterkeysv -X - -Returns the key as an C from the current position of the hash -iterator. The return value will always be a mortal copy of the key. Also -see C. - - SV* hv_iterkeysv(HE* entry) - -=for hackers -Found in file hv.c - -=item hv_iternext -X - -Returns entries from a hash iterator. See C. - -You may call C or C on the hash entry that the -iterator currently points to, without losing your place or invalidating your -iterator. Note that in this case the current entry is deleted from the hash -with your iterator holding the last reference to it. Your iterator is flagged -to free the entry on the next call to C, so you must not discard -your iterator immediately else the entry will leak - call C to -trigger the resource deallocation. - - HE* hv_iternext(HV *hv) - -=for hackers -Found in file hv.c - -=item hv_iternextsv -X - -Performs an C, C, and C in one -operation. - - SV* hv_iternextsv(HV *hv, char **key, I32 *retlen) - -=for hackers -Found in file hv.c - -=item hv_iternext_flags -X - -Returns entries from a hash iterator. See C and C. -The C value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is -set the placeholders keys (for restricted hashes) will be returned in addition -to normal keys. By default placeholders are automatically skipped over. -Currently a placeholder is implemented with a value that is -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 - -Returns the value from the current position of the hash iterator. See -C. - - SV* hv_iterval(HV *hv, HE *entry) - -=for hackers -Found in file hv.c - -=item hv_magic -X - -Adds magic to a hash. See C. - - void hv_magic(HV *hv, GV *gv, int how) - -=for hackers -Found in file hv.c - -=item hv_scalar -X - -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 - -Stores an SV in a hash. The hash key is specified as C and C is -the length of the key. The C parameter is the precomputed hash -value; if it is zero then Perl will compute it. The return value will be -NULL if the operation failed or if the value did not need to be actually -stored within the hash (as in the case of tied hashes). Otherwise it can -be dereferenced to get the original C. Note that the caller is -responsible for suitably incrementing the reference count of C before -the call, and decrementing it if the function returned NULL. Effectively -a successful hv_store takes ownership of one reference to C. This is -usually what you want; a newly created SV has a reference count of one, so -if all your code does is create SVs then store them in a hash, hv_store -will own the only reference to the new SV, and your code doesn't need to do -anything further to tidy up. hv_store is not implemented as a call to -hv_store_ent, and does not create a temporary SV for the key, so if your -key data is not already in SV form then use hv_store in preference to -hv_store_ent. - -See L for more -information on how to use this function on tied hashes. - - SV** hv_store(HV *hv, const char *key, I32 klen, SV *val, U32 hash) - -=for hackers -Found in file hv.c - -=item hv_stores -X - -Like C, but takes a literal string instead of a string/length pair -and omits the hash parameter. - - SV** hv_stores(HV* tb, const char* key, NULLOK SV* val) - -=for hackers -Found in file handy.h - -=item hv_store_ent -X - -Stores C in a hash. The hash key is specified as C. The C -parameter is the precomputed hash value; if it is zero then Perl will -compute it. The return value is the new hash entry so created. It will be -NULL if the operation failed or if the value did not need to be actually -stored within the hash (as in the case of tied hashes). Otherwise the -contents of the return value can be accessed using the C macros -described here. Note that the caller is responsible for suitably -incrementing the reference count of C before the call, and -decrementing it if the function returned NULL. Effectively a successful -hv_store_ent takes ownership of one reference to C. This is -usually what you want; a newly created SV has a reference count of one, so -if all your code does is create SVs then store them in a hash, hv_store -will own the only reference to the new SV, and your code doesn't need to do -anything further to tidy up. Note that hv_store_ent only reads the C; -unlike C it does not take ownership of it, so maintaining the correct -reference count on C is entirely the caller's responsibility. hv_store -is not implemented as a call to hv_store_ent, and does not create a temporary -SV for the key, so if your key data is not already in SV form then use -hv_store in preference to hv_store_ent. - -See L for more -information on how to use this function on tied hashes. - - HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash) - -=for hackers -Found in file hv.c - -=item hv_undef -X - -Undefines the hash. - - void hv_undef(HV *hv) - -=for hackers -Found in file hv.c - -=item newHV -X - -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 - -Clear something magical that the SV represents. See C. - - int mg_clear(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_copy -X - -Copies the magic from one SV to another. See C. - - int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen) - -=for hackers -Found in file mg.c - -=item mg_find -X - -Finds the magic pointer for type matching the SV. See C. - - MAGIC* mg_find(const SV* sv, int type) - -=for hackers -Found in file mg.c - -=item mg_free -X - -Free any magic storage used by the SV. See C. - - int mg_free(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_get -X - -Do magic after a value is retrieved from the SV. See C. - - int mg_get(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_length -X - -Report on the SV's length. See C. - - U32 mg_length(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_magical -X - -Turns on the magical status of an SV. See C. - - void mg_magical(SV* sv) - -=for hackers -Found in file mg.c - -=item mg_set -X - -Do magic after a value is assigned to the SV. See C. - - int mg_set(SV* sv) - -=for hackers -Found in file mg.c - -=item SvGETMAGIC -X - -Invokes C on an SV if it has 'get' magic. This macro evaluates its -argument more than once. - - void SvGETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvLOCK -X - -Arranges for a mutual exclusion lock to be obtained on sv if a suitable module -has been loaded. - - void SvLOCK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSETMAGIC -X - -Invokes C on an SV if it has 'set' magic. This macro evaluates its -argument more than once. - - void SvSETMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSetMagicSV -X - -Like C, but does any set magic required afterwards. - - void SvSetMagicSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetMagicSV_nosteal -X - -Like C, but does any set magic required afterwards. - - void SvSetMagicSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV -X - -Calls C if dsv is not the same as ssv. May evaluate arguments -more than once. - - void SvSetSV(SV* dsb, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSetSV_nosteal -X - -Calls a non-destructive version of C if dsv is not the same as -ssv. May evaluate arguments more than once. - - void SvSetSV_nosteal(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item SvSHARE -X - -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 - -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 - -The XSUB-writer's interface to the C C function. The C is the -source, C is the destination, C is the number of items, and C is -the type. May fail on overlapping copies. See also C. - - void Copy(void* src, void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item CopyD -X - -Like C 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 - -The XSUB-writer's interface to the C C function. The C is the -source, C is the destination, C is the number of items, and C is -the type. Can do overlapping moves. See also C. - - void Move(void* src, void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item MoveD -X - -Like C 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 - -The XSUB-writer's interface to the C C function. - -In 5.9.3, Newx() and friends replace the older New() API, and drops -the first parameter, I, a debug aid which allowed callers to identify -themselves. This aid has been superseded by a new build option, -PERL_MEM_LOG (see L). The older API is still -there for use in XS modules supporting older perls. - - void Newx(void* ptr, int nitems, type) - -=for hackers -Found in file handy.h - -=item Newxc -X - -The XSUB-writer's interface to the C C function, with -cast. See also C. - - void Newxc(void* ptr, int nitems, type, cast) - -=for hackers -Found in file handy.h - -=item Newxz -X - -The XSUB-writer's interface to the C C function. The allocated -memory is zeroed with C. See also C. - - void Newxz(void* ptr, int nitems, type) - -=for hackers -Found in file handy.h - -=item Poison -X - -PoisonWith(0xEF) for catching access to freed memory. - - void Poison(void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item PoisonFree -X - -PoisonWith(0xEF) for catching access to freed memory. - - void PoisonFree(void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item PoisonNew -X - -PoisonWith(0xAB) for catching access to allocated but uninitialized memory. - - void PoisonNew(void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item PoisonWith -X - -Fill up memory with a byte pattern (a byte repeated over and over -again) that hopefully catches attempts to access uninitialized memory. - - void PoisonWith(void* dest, int nitems, type, U8 byte) - -=for hackers -Found in file handy.h - -=item Renew -X - -The XSUB-writer's interface to the C C function. - - void Renew(void* ptr, int nitems, type) - -=for hackers -Found in file handy.h - -=item Renewc -X - -The XSUB-writer's interface to the C C function, with -cast. - - void Renewc(void* ptr, int nitems, type, cast) - -=for hackers -Found in file handy.h - -=item Safefree -X - -The XSUB-writer's interface to the C C function. - - void Safefree(void* ptr) - -=for hackers -Found in file handy.h - -=item savepv -X - -Perl's version of C. Returns a pointer to a newly allocated -string which is a duplicate of C. The size of the string is -determined by C. The memory allocated for the new string can -be freed with the C function. - - char* savepv(const char* pv) - -=for hackers -Found in file util.c - -=item savepvn -X - -Perl's version of what C would be if it existed. Returns a -pointer to a newly allocated string which is a duplicate of the first -C bytes from C, plus a trailing NUL byte. The memory allocated for -the new string can be freed with the C function. - - char* savepvn(const char* pv, I32 len) - -=for hackers -Found in file util.c - -=item savepvs -X - -Like C, but takes a literal string instead of a string/length pair. - - char* savepvs(const char* s) - -=for hackers -Found in file handy.h - -=item savesharedpv -X - -A version of C which allocates the duplicate string in memory -which is shared between threads. - - char* savesharedpv(const char* pv) - -=for hackers -Found in file util.c - -=item savesharedpvn -X - -A version of C 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 - -A version of C/C which gets the string to duplicate from -the passed in SV using C - - char* savesvpv(SV* sv) - -=for hackers -Found in file util.c - -=item StructCopy -X - -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 - -The XSUB-writer's interface to the C C function. The C is the -destination, C is the number of items, and C is the type. - - void Zero(void* dest, int nitems, type) - -=for hackers -Found in file handy.h - -=item ZeroD -X - -Like C 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 - -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 - -Returns the location of the SV in the string delimited by C and -C. It returns C if the string can't be found. The C -does not have to be fbm_compiled, but the search will not be as fast -then. - - char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlestr, U32 flags) - -=for hackers -Found in file util.c - -=item form -X
- -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 - -Fill the sv with current working directory - - int getcwd_sv(SV* sv) - -=for hackers -Found in file util.c - -=item my_snprintf -X - -The C library C functionality, if available and -standards-compliant (uses C, actually). However, if the -C is not available, will unfortunately use the unsafe -C which can overrun the buffer (there is an overrun check, -but that may be too late). Consider using C instead, or -getting C. - - int my_snprintf(char *buffer, const Size_t len, const char *format, ...) - -=for hackers -Found in file util.c - -=item my_sprintf -X - -The C library C, wrapped if necessary, to ensure that it will return -the length of the string written to the buffer. Only rare pre-ANSI systems -need the wrapper function - usually this is a direct call to C. - - int my_sprintf(char *buffer, const char *pat, ...) - -=for hackers -Found in file util.c - -=item my_vsnprintf -X - -The C library C if available and standards-compliant. -However, if if the C is not available, will unfortunately -use the unsafe C which can overrun the buffer (there is an -overrun check, but that may be too late). Consider using -C instead, or getting C. - - int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap) - -=for hackers -Found in file util.c - -=item new_version -X - -Returns a new version object based on the passed in SV: - - 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 - -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 - -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 - -Test two strings to see if the first, C, is greater than or equal to -the second, C. Returns true or false. - - bool strGE(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strGT -X - -Test two strings to see if the first, C, is greater than the second, -C. Returns true or false. - - bool strGT(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strLE -X - -Test two strings to see if the first, C, is less than or equal to the -second, C. Returns true or false. - - bool strLE(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strLT -X - -Test two strings to see if the first, C, is less than the second, -C. Returns true or false. - - bool strLT(char* s1, char* s2) - -=for hackers -Found in file handy.h - -=item strNE -X - -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 - -Test two strings to see if they are equal. The C parameter indicates -the number of bytes to compare. Returns true or false. (A wrapper for -C). - - bool strnEQ(char* s1, char* s2, STRLEN len) - -=for hackers -Found in file handy.h - -=item strnNE -X - -Test two strings to see if they are different. The C parameter -indicates the number of bytes to compare. Returns true or false. (A -wrapper for C). - - bool strnNE(char* s1, char* s2, STRLEN len) - -=for hackers -Found in file handy.h - -=item sv_destroyable -X - -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 - -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 - -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 - -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 - -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 - -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 - -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 - -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 - -Returns either C or -C 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 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 - -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 in -perl source outside of 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. - - void mro_method_changed_in(HV* stash) - -=for hackers -Found in file mro.c - - -=back - -=head1 Multicall Functions - -=over 8 - -=item dMULTICALL -X - -Declare local variables for a multicall. See L. - - dMULTICALL; - -=for hackers -Found in file cop.h - -=item MULTICALL -X - -Make a lightweight callback. See L. - - MULTICALL; - -=for hackers -Found in file cop.h - -=item POP_MULTICALL -X - -Closing bracket for a lightweight callback. -See L. - - POP_MULTICALL; - -=for hackers -Found in file cop.h - -=item PUSH_MULTICALL -X - -Opening bracket for a lightweight callback. -See L. - - PUSH_MULTICALL; - -=for hackers -Found in file cop.h - - -=back - -=head1 Numeric functions - -=over 8 - -=item grok_bin -X - -converts a string representing a binary number to numeric form. - -On entry I and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first invalid character. -Unless C 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 it is returned as a UV, the output flags are clear, -and nothing is written to I<*result>. If the value is > UV_MAX C -returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I -is NULL). - -The binary number may optionally be prefixed with "0b" or "b" unless -C is set in I<*flags> on entry. If -C is set in I<*flags> then the binary -number may use '_' characters to separate digits. - - UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result) - -=for hackers -Found in file numeric.c - -=item grok_hex -X - -converts a string representing a hex number to numeric form. - -On entry I and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first invalid character. -Unless C 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 -returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I -is NULL). - -The hex number may optionally be prefixed with "0x" or "x" unless -C is set in I<*flags> on entry. If -C is set in I<*flags> then the hex -number may use '_' characters to separate digits. - - UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result) - -=for hackers -Found in file numeric.c - -=item grok_number -X - -Recognise (or not) a number. The type of the number is returned -(0 if unrecognised), otherwise it is a bit-ORed combination of -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 - -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 - -converts a string representing an octal number to numeric form. - -On entry I and I<*len> give the string to scan, I<*flags> gives -conversion flags, and I should be NULL or a pointer to an NV. -The scan stops at the end of the string, or the first invalid character. -Unless C 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 -returns UV_MAX, sets C in the output flags, -and writes the value to I<*result> (or the value is discarded if I -is NULL). - -If C is set in I<*flags> then the octal -number may use '_' characters to separate digits. - - UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result) - -=for hackers -Found in file numeric.c - -=item Perl_signbit -X - -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 - -For backwards compatibility. Use C instead. - - NV scan_bin(const char* start, STRLEN len, STRLEN* retlen) - -=for hackers -Found in file numeric.c - -=item scan_hex -X - -For backwards compatibility. Use C instead. - - NV scan_hex(const char* start, STRLEN len, STRLEN* retlen) - -=for hackers -Found in file numeric.c - -=item scan_oct -X - -For backwards compatibility. Use C instead. - - NV scan_oct(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 - -If C is a constant sub eligible for inlining. returns the constant -value returned by the sub. Otherwise, returns NULL. - -Constant subs can be created with C or as described in -L. - - SV* cv_const_sv(const CV *const cv) - -=for hackers -Found in file op.c - -=item newCONSTSUB -X - -Creates a constant sub equivalent to Perl C which is -eligible for inlining at compile-time. - -Passing NULL for SV creates a constant sub equivalent to C, -which won't be called if used as a destructor, but will suppress the overhead -of a call to C. (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 - -Used by C to hook up XSUBs as Perl subs. I needs to be -static storage, as it is used directly as CvFILE(), without a copy being made. - -=for hackers -Found in file op.c - - -=back - -=head1 Pad Data Structures - -=over 8 - -=item pad_sv -X - -Get the value at offset po in the current pad. -Use macro PAD_SV instead of calling this function directly. - - SV* pad_sv(PADOFFSET po) - -=for hackers -Found in file pad.c - - -=back - -=head1 Per-Interpreter Variables - -=over 8 - -=item PL_modglobal -X - -C is a general purpose, interpreter global HV for use by -extensions that need to keep information on a per-interpreter basis. -In a pinch, it can also be used as a symbol table for extensions -to share data among each other. It is a good idea to use keys -prefixed by the package name of the extension that owns the data. - - HV* PL_modglobal - -=for hackers -Found in file intrpvar.h - -=item PL_na -X - -A convenience variable which is typically used with C when one -doesn't care about the length of the string. It is usually more efficient -to either declare a local variable and use that instead or to use the -C macro. - - STRLEN PL_na - -=for hackers -Found in file intrpvar.h - -=item PL_sv_no -X - -This is the C SV. See C. Always refer to this as -C<&PL_sv_no>. - - SV PL_sv_no - -=for hackers -Found in file intrpvar.h - -=item PL_sv_undef -X - -This is the C SV. Always refer to this as C<&PL_sv_undef>. - - SV PL_sv_undef - -=for hackers -Found in file intrpvar.h - -=item PL_sv_yes -X - -This is the C SV. See C. Always refer to this as -C<&PL_sv_yes>. - - SV PL_sv_yes - -=for hackers -Found in file intrpvar.h - - -=back - -=head1 REGEXP Functions - -=over 8 - -=item SvRX -X - -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 - -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 - -Set up necessary local variables for exception handling. -See L. - - dXCPT; - -=for hackers -Found in file XSUB.h - -=item XCPT_CATCH -X - -Introduces a catch block. See L. - -=for hackers -Found in file XSUB.h - -=item XCPT_RETHROW -X - -Rethrows a previously caught exception. See L. - - XCPT_RETHROW; - -=for hackers -Found in file XSUB.h - -=item XCPT_TRY_END -X - -Ends a try block. See L. - -=for hackers -Found in file XSUB.h - -=item XCPT_TRY_START -X - -Starts a try block. See L. - -=for hackers -Found in file XSUB.h - - -=back - -=head1 Stack Manipulation Macros - -=over 8 - -=item dMARK -X - -Declare a stack marker variable, C, for the XSUB. See C and -C. - - dMARK; - -=for hackers -Found in file pp.h - -=item dORIGMARK -X - -Saves the original stack mark for the XSUB. See C. - - dORIGMARK; - -=for hackers -Found in file pp.h - -=item dSP -X - -Declares a local copy of perl's stack pointer for the XSUB, available via -the C macro. See C. - - dSP; - -=for hackers -Found in file pp.h - -=item EXTEND -X - -Used to extend the argument stack for an XSUB's return values. Once -used, guarantees that there is room for at least C to be pushed -onto the stack. - - void EXTEND(SP, int nitems) - -=for hackers -Found in file pp.h - -=item MARK -X - -Stack marker variable for the XSUB. See C. - -=for hackers -Found in file pp.h - -=item mPUSHi -X - -Push an integer onto the stack. The stack must have room for this element. -Does not use C. See also C, C and C. - - void mPUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item mPUSHn -X - -Push a double onto the stack. The stack must have room for this element. -Does not use C. See also C, C and C. - - void mPUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item mPUSHp -X - -Push a string onto the stack. The stack must have room for this element. -The C indicates the length of the string. Does not use C. -See also C, C and C. - - void mPUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item mPUSHs -X - -Push an SV onto the stack and mortalizes the SV. The stack must have room -for this element. Does not use C. See also C and C. - - void mPUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item mPUSHu -X - -Push an unsigned integer onto the stack. The stack must have room for this -element. Does not use C. See also C, C and C. - - void mPUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item mXPUSHi -X - -Push an integer onto the stack, extending the stack if necessary. -Does not use C. See also C, C and C. - - void mXPUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item mXPUSHn -X - -Push a double onto the stack, extending the stack if necessary. -Does not use C. See also C, C and C. - - void mXPUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item mXPUSHp -X - -Push a string onto the stack, extending the stack if necessary. The C -indicates the length of the string. Does not use C. See also C, -C and C. - - void mXPUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item mXPUSHs -X - -Push an SV onto the stack, extending the stack if necessary and mortalizes -the SV. Does not use C. See also C and C. - - void mXPUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item mXPUSHu -X - -Push an unsigned integer onto the stack, extending the stack if necessary. -Does not use C. See also C, C and C. - - void mXPUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item ORIGMARK -X - -The original stack mark for the XSUB. See C. - -=for hackers -Found in file pp.h - -=item POPi -X - -Pops an integer off the stack. - - IV POPi - -=for hackers -Found in file pp.h - -=item POPl -X - -Pops a long off the stack. - - long POPl - -=for hackers -Found in file pp.h - -=item POPn -X - -Pops a double off the stack. - - NV POPn - -=for hackers -Found in file pp.h - -=item POPp -X - -Pops a string off the stack. Deprecated. New code should use POPpx. - - char* POPp - -=for hackers -Found in file pp.h - -=item POPpbytex -X - -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 - -Pops a string off the stack. - - char* POPpx - -=for hackers -Found in file pp.h - -=item POPs -X - -Pops an SV off the stack. - - SV* POPs - -=for hackers -Found in file pp.h - -=item PUSHi -X - -Push an integer onto the stack. The stack must have room for this element. -Handles 'set' magic. Uses C, so C or C should be -called to declare it. Do not call multiple C-oriented macros to -return lists from XSUB's - see C instead. See also C and -C. - - void PUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item PUSHMARK -X - -Opening bracket for arguments on a callback. See C and -L. - - void PUSHMARK(SP) - -=for hackers -Found in file pp.h - -=item PUSHmortal -X - -Push a new mortal SV onto the stack. The stack must have room for this -element. Does not use C. See also C, C and C. - - void PUSHmortal() - -=for hackers -Found in file pp.h - -=item PUSHn -X - -Push a double onto the stack. The stack must have room for this element. -Handles 'set' magic. Uses C, so C or C should be -called to declare it. Do not call multiple C-oriented macros to -return lists from XSUB's - see C instead. See also C and -C. - - void PUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item PUSHp -X - -Push a string onto the stack. The stack must have room for this element. -The C indicates the length of the string. Handles 'set' magic. Uses -C, so C or C should be called to declare it. Do not -call multiple C-oriented macros to return lists from XSUB's - see -C instead. See also C and C. - - void PUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item PUSHs -X - -Push an SV onto the stack. The stack must have room for this element. -Does not handle 'set' magic. Does not use C. See also C, -C and C. - - void PUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item PUSHu -X - -Push an unsigned integer onto the stack. The stack must have room for this -element. Handles 'set' magic. Uses C, so C or C -should be called to declare it. Do not call multiple C-oriented -macros to return lists from XSUB's - see C instead. See also -C and C. - - void PUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item PUTBACK -X - -Closing bracket for XSUB arguments. This is usually handled by C. -See C and L for other uses. - - PUTBACK; - -=for hackers -Found in file pp.h - -=item SP -X - -Stack pointer. This is usually handled by C. See C and -C. - -=for hackers -Found in file pp.h - -=item SPAGAIN -X - -Refetch the stack pointer. Used after a callback. See L. - - SPAGAIN; - -=for hackers -Found in file pp.h - -=item XPUSHi -X - -Push an integer onto the stack, extending the stack if necessary. Handles -'set' magic. Uses C, so C or C should be called to -declare it. Do not call multiple C-oriented macros to return lists -from XSUB's - see C instead. See also C and C. - - void XPUSHi(IV iv) - -=for hackers -Found in file pp.h - -=item XPUSHmortal -X - -Push a new mortal SV onto the stack, extending the stack if necessary. -Does not use C. See also C, C and C. - - void XPUSHmortal() - -=for hackers -Found in file pp.h - -=item XPUSHn -X - -Push a double onto the stack, extending the stack if necessary. Handles -'set' magic. Uses C, so C or C should be called to -declare it. Do not call multiple C-oriented macros to return lists -from XSUB's - see C instead. See also C and C. - - void XPUSHn(NV nv) - -=for hackers -Found in file pp.h - -=item XPUSHp -X - -Push a string onto the stack, extending the stack if necessary. The C -indicates the length of the string. Handles 'set' magic. Uses C, so -C or C should be called to declare it. Do not call -multiple C-oriented macros to return lists from XSUB's - see -C instead. See also C and C. - - void XPUSHp(char* str, STRLEN len) - -=for hackers -Found in file pp.h - -=item XPUSHs -X - -Push an SV onto the stack, extending the stack if necessary. Does not -handle 'set' magic. Does not use C. See also C, -C and C. - - void XPUSHs(SV* sv) - -=for hackers -Found in file pp.h - -=item XPUSHu -X - -Push an unsigned integer onto the stack, extending the stack if necessary. -Handles 'set' magic. Uses C, so C or C should be -called to declare it. Do not call multiple C-oriented macros to -return lists from XSUB's - see C instead. See also C and -C. - - void XPUSHu(UV uv) - -=for hackers -Found in file pp.h - -=item XSRETURN -X - -Return from XSUB, indicating number of items on the stack. This is usually -handled by C. - - void XSRETURN(int nitems) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_EMPTY -X - -Return an empty list from an XSUB immediately. - - XSRETURN_EMPTY; - -=for hackers -Found in file XSUB.h - -=item XSRETURN_IV -X - -Return an integer from an XSUB immediately. Uses C. - - void XSRETURN_IV(IV iv) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_NO -X - -Return C<&PL_sv_no> from an XSUB immediately. Uses C. - - XSRETURN_NO; - -=for hackers -Found in file XSUB.h - -=item XSRETURN_NV -X - -Return a double from an XSUB immediately. Uses C. - - void XSRETURN_NV(NV nv) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_PV -X - -Return a copy of a string from an XSUB immediately. Uses C. - - void XSRETURN_PV(char* str) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_UNDEF -X - -Return C<&PL_sv_undef> from an XSUB immediately. Uses C. - - XSRETURN_UNDEF; - -=for hackers -Found in file XSUB.h - -=item XSRETURN_UV -X - -Return an integer from an XSUB immediately. Uses C. - - void XSRETURN_UV(IV uv) - -=for hackers -Found in file XSUB.h - -=item XSRETURN_YES -X - -Return C<&PL_sv_yes> from an XSUB immediately. Uses C. - - XSRETURN_YES; - -=for hackers -Found in file XSUB.h - -=item XST_mIV -X - -Place an integer into the specified position C on the stack. The -value is stored in a new mortal SV. - - void XST_mIV(int pos, IV iv) - -=for hackers -Found in file XSUB.h - -=item XST_mNO -X - -Place C<&PL_sv_no> into the specified position C on the -stack. - - void XST_mNO(int pos) - -=for hackers -Found in file XSUB.h - -=item XST_mNV -X - -Place a double into the specified position C on the stack. The value -is stored in a new mortal SV. - - void XST_mNV(int pos, NV nv) - -=for hackers -Found in file XSUB.h - -=item XST_mPV -X - -Place a copy of a string into the specified position C on the stack. -The value is stored in a new mortal SV. - - void XST_mPV(int pos, char* str) - -=for hackers -Found in file XSUB.h - -=item XST_mUNDEF -X - -Place C<&PL_sv_undef> into the specified position C on the -stack. - - void XST_mUNDEF(int pos) - -=for hackers -Found in file XSUB.h - -=item XST_mYES -X - -Place C<&PL_sv_yes> into the specified position C on the -stack. - - void XST_mYES(int pos) - -=for hackers -Found in file XSUB.h - - -=back - -=head1 SV Flags - -=over 8 - -=item svtype -X - -An enum of flags for Perl types. These are found in the file B -in the C enum. Test these flags with the C macro. - -=for hackers -Found in file sv.h - -=item SVt_IV -X - -Integer type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_NV -X - -Double type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_PV -X - -Pointer type flag for scalars. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVAV -X - -Type flag for arrays. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVCV -X - -Type flag for code refs. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVHV -X - -Type flag for hashes. See C. - -=for hackers -Found in file sv.h - -=item SVt_PVMG -X - -Type flag for blessed scalars. See C. - -=for hackers -Found in file sv.h - - -=back - -=head1 SV Manipulation Functions - -=over 8 - -=item croak_xs_usage -X - -A specialised variant of C for emitting the usage message for xsubs - - croak_xs_usage(cv, "eee_yow"); - -works out the package name and subroutine name from C, and then calls -C. Hence if C is C<&ouch::awk>, it would call C 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 - -Returns the SV of the specified Perl scalar. C are passed to -C. If C is set and the -Perl variable does not exist then it will be created. If C 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 - -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 - -Creates a new SV and copies a string into it. If utf8 is true, calls -C on the new SV. Implemented as a wrapper around C. - - SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8) - -=for hackers -Found in file sv.h - -=item SvCUR -X - -Returns the length of the string which is in the SV. See C. - - STRLEN SvCUR(SV* sv) - -=for hackers -Found in file sv.h - -=item SvCUR_set -X - -Set the current length of the string which is in the SV. See C -and C. - - void SvCUR_set(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvEND -X - -Returns a pointer to the last character in the string which is in the SV. -See C. Access the character as *(SvEND(sv)). - - char* SvEND(SV* sv) - -=for hackers -Found in file sv.h - -=item SvGAMAGIC -X - -Returns true if the SV has get magic or overloading. If either is true then -the scalar is active data, and has the potential to return a new value every -time it is accessed. Hence you must be careful to only read it once per user -logical operation and work with that returned value. If neither is true then -the scalar's value cannot change unless written to. - - char* SvGAMAGIC(SV* sv) - -=for hackers -Found in file sv.h - -=item SvGROW -X - -Expands the character buffer in the SV so that it has room for the -indicated number of bytes (remember to reserve space for an extra trailing -NUL character). Calls C 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 - -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 - -Returns a U32 value indicating whether the SV contains an integer. Checks -the B setting. Use C instead. - - U32 SvIOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_notUV -X - -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 - -Unsets the IV status of an SV. - - void SvIOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_on -X - -Tells an SV that it is an integer. - - void SvIOK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIOK_only -X - -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 - -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 - -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 - -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 - -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 - -Coerces the given SV to an integer and returns it. See C for a -version which guarantees to evaluate sv only once. - - IV SvIV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIVX -X - -Returns the raw value in the SV's IV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. - - IV SvIVX(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIVx -X - -Coerces the given SV to an integer and returns it. Guarantees to evaluate -C only once. Only use this if C is an expression with side effects, -otherwise use the more efficient C. - - IV SvIVx(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIV_nomg -X - -Like C but doesn't process magic. - - IV SvIV_nomg(SV* sv) - -=for hackers -Found in file sv.h - -=item SvIV_set -X - -Set the value of the IV pointer in sv to val. It is possible to perform -the same function of this macro with an lvalue assignment to C. -With future Perls, however, it will be more efficient to use -C instead of the lvalue assignment to C. - - void SvIV_set(SV* sv, IV val) - -=for hackers -Found in file sv.h - -=item SvLEN -X - -Returns the size of the string buffer in the SV, not including any part -attributable to C. See C. - - STRLEN SvLEN(SV* sv) - -=for hackers -Found in file sv.h - -=item SvLEN_set -X - -Set the actual length of the string which is in the SV. See C. - - void SvLEN_set(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvMAGIC_set -X - -Set the value of the MAGIC pointer in sv to val. See C. - - void SvMAGIC_set(SV* sv, MAGIC* val) - -=for hackers -Found in file sv.h - -=item SvNIOK -X - -Returns a 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 - -Returns a U32 value indicating whether the SV contains a number, integer or -double. Checks the B setting. Use C instead. - - U32 SvNIOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNIOK_off -X - -Unsets the NV/IV status of an SV. - - void SvNIOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK -X - -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 - -Returns a U32 value indicating whether the SV contains a double. Checks the -B setting. Use C instead. - - U32 SvNOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK_off -X - -Unsets the NV status of an SV. - - void SvNOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK_on -X - -Tells an SV that it is a double. - - void SvNOK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNOK_only -X - -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 - -Coerce the given SV to a double and return it. See C for a version -which guarantees to evaluate sv only once. - - NV SvNV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNVX -X - -Returns the raw value in the SV's NV slot, without checks or conversions. -Only use when you are sure SvNOK is true. See also C. - - NV SvNVX(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNVx -X - -Coerces the given SV to a double and returns it. Guarantees to evaluate -C only once. Only use this if C is an expression with side effects, -otherwise use the more efficient C. - - NV SvNVx(SV* sv) - -=for hackers -Found in file sv.h - -=item SvNV_set -X - -Set the value of the NV pointer in sv to val. See C. - - void SvNV_set(SV* sv, NV val) - -=for hackers -Found in file sv.h - -=item SvOK -X - -Returns a 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 - -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 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 - -Reads into I the offset from SvPVX back to the true start of the -allocated buffer, which will be non-zero if C has been used to -efficiently remove characters from start of the buffer. Implemented as a -macro, which takes the address of I, which must be of type C. -Evaluates I more than once. Sets I to 0 if C is false. - - void SvOOK_offset(NN SV*sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPOK -X - -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 - -Returns a U32 value indicating whether the SV contains a character string. -Checks the B setting. Use C instead. - - U32 SvPOKp(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_off -X - -Unsets the PV status of an SV. - - void SvPOK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_on -X - -Tells an SV that it is a string. - - void SvPOK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_only -X - -Tells an SV that it is a string and disables all other OK bits. -Will also turn off the UTF-8 status. - - void SvPOK_only(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPOK_only_UTF8 -X - -Tells an SV that it is a string and disables all other OK bits, -and leaves the UTF-8 status as it was. - - void SvPOK_only_UTF8(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPV -X - -Returns a pointer to the string in the SV, or a stringified form of -the SV if the SV does not contain a string. The SV may cache the -stringified version becoming C. Handles 'get' magic. See also -C for a version which guarantees to evaluate sv only once. - - char* SvPV(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbyte -X - -Like C, 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 - -Like C, but converts sv to byte representation first if necessary. -Guarantees to evaluate sv only once; use the more efficient C -otherwise. - - char* SvPVbytex(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbytex_force -X - -Like C, but converts sv to byte representation first if necessary. -Guarantees to evaluate sv only once; use the more efficient C -otherwise. - - char* SvPVbytex_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVbyte_force -X - -Like C, 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 - -Like C, but converts sv to byte representation first if necessary. - - char* SvPVbyte_nolen(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPVutf8 -X - -Like C, but converts sv to utf8 first if necessary. - - char* SvPVutf8(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVutf8x -X - -Like C, but converts sv to utf8 first if necessary. -Guarantees to evaluate sv only once; use the more efficient C -otherwise. - - char* SvPVutf8x(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVutf8x_force -X - -Like C, but converts sv to utf8 first if necessary. -Guarantees to evaluate sv only once; use the more efficient C -otherwise. - - char* SvPVutf8x_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPVutf8_force -X - -Like C, 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 - -Like C, but converts sv to utf8 first if necessary. - - char* SvPVutf8_nolen(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPVX -X - -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 - -A version of C which guarantees to evaluate C only once. -Only use this if C is an expression with side effects, otherwise use the -more efficient C. - - char* SvPVx(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_force -X - -Like C but will force the SV into containing just a string -(C). You want force if you are going to update the C -directly. - - char* SvPV_force(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_force_nomg -X - -Like C but will force the SV into containing just a string -(C). You want force if you are going to update the C -directly. Doesn't process magic. - - char* SvPV_force_nomg(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_nolen -X - -Returns a pointer to the string in the SV, or a stringified form of -the SV if the SV does not contain a string. The SV may cache the -stringified form becoming C. Handles 'get' magic. - - char* SvPV_nolen(SV* sv) - -=for hackers -Found in file sv.h - -=item SvPV_nomg -X - -Like C but doesn't process magic. - - char* SvPV_nomg(SV* sv, STRLEN len) - -=for hackers -Found in file sv.h - -=item SvPV_set -X - -Set the value of the PV pointer in sv to val. See C. - - void SvPV_set(SV* sv, char* val) - -=for hackers -Found in file sv.h - -=item SvREFCNT -X - -Returns the value of the object's reference count. - - U32 SvREFCNT(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_dec -X - -Decrements the reference count of the given SV. - - void SvREFCNT_dec(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc -X - -Increments the reference count of the given SV. - -All of the following SvREFCNT_inc* macros are optimized versions of -SvREFCNT_inc, and can be replaced with SvREFCNT_inc. - - SV* SvREFCNT_inc(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc_NN -X - -Same as SvREFCNT_inc, but can only be used if you know I -is not NULL. Since we don't have to check the NULLness, it's faster -and smaller. - - SV* SvREFCNT_inc_NN(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc_simple -X - -Same as SvREFCNT_inc, but can only be used with 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 - -Same as SvREFCNT_inc_simple, but can only be used if you know I -is not NULL. Since we don't have to check the NULLness, it's faster -and smaller. - - SV* SvREFCNT_inc_simple_NN(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc_simple_void -X - -Same as SvREFCNT_inc_simple, but can only be used if you don't need the -return value. The macro doesn't need to return a meaningful value. - - void SvREFCNT_inc_simple_void(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc_simple_void_NN -X - -Same as SvREFCNT_inc, but can only be used if you don't need the return -value, and you know that I is not NULL. The macro doesn't need -to return a meaningful value, or check for NULLness, so it's smaller -and faster. - - void SvREFCNT_inc_simple_void_NN(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc_void -X - -Same as SvREFCNT_inc, but can only be used if you don't need the -return value. The macro doesn't need to return a meaningful value. - - void SvREFCNT_inc_void(SV* sv) - -=for hackers -Found in file sv.h - -=item SvREFCNT_inc_void_NN -X - -Same as SvREFCNT_inc, but can only be used if you don't need the return -value, and you know that I is not NULL. The macro doesn't need -to return a meaningful value, or check for NULLness, so it's smaller -and faster. - - void SvREFCNT_inc_void_NN(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK -X - -Tests if the SV is an RV. - - U32 SvROK(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK_off -X - -Unsets the RV status of an SV. - - void SvROK_off(SV* sv) - -=for hackers -Found in file sv.h - -=item SvROK_on -X - -Tells an SV that it is an RV. - - void SvROK_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvRV -X - -Dereferences an RV to return the SV. - - SV* SvRV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvRV_set -X - -Set the value of the RV pointer in sv to val. See C. - - void SvRV_set(SV* sv, SV* val) - -=for hackers -Found in file sv.h - -=item SvSTASH -X - -Returns the stash of the SV. - - HV* SvSTASH(SV* sv) - -=for hackers -Found in file sv.h - -=item SvSTASH_set -X - -Set the value of the STASH pointer in sv to val. See C. - - void SvSTASH_set(SV* sv, HV* val) - -=for hackers -Found in file sv.h - -=item SvTAINT -X - -Taints an SV if tainting is enabled. - - void SvTAINT(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTAINTED -X - -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 - -Untaints an SV. Be I careful with this routine, as it short-circuits -some of Perl's fundamental security features. XS module authors should not -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 - -Marks an SV as tainted if tainting is enabled. - - void SvTAINTED_on(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTRUE -X - -Returns a boolean indicating whether Perl would evaluate the SV as true or -false, defined or undefined. Does not handle 'get' magic. - - bool SvTRUE(SV* sv) - -=for hackers -Found in file sv.h - -=item SvTYPE -X - -Returns the type of the SV. See C. - - svtype SvTYPE(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUOK -X - -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 - -Used to upgrade an SV to a more complex form. Uses C to -perform the upgrade if necessary. See C. - - void SvUPGRADE(SV* sv, svtype type) - -=for hackers -Found in file sv.h - -=item SvUTF8 -X - -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 - -Unsets the UTF-8 status of an SV. - - void SvUTF8_off(SV *sv) - -=for hackers -Found in file sv.h - -=item SvUTF8_on -X - -Turn on the UTF-8 status of an SV (the data is not changed, just the flag). -Do not use frivolously. - - void SvUTF8_on(SV *sv) - -=for hackers -Found in file sv.h - -=item SvUV -X - -Coerces the given SV to an unsigned integer and returns it. See C -for a version which guarantees to evaluate sv only once. - - UV SvUV(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUVX -X - -Returns the raw value in the SV's UV slot, without checks or conversions. -Only use when you are sure SvIOK is true. See also C. - - UV SvUVX(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUVx -X - -Coerces the given SV to an unsigned integer and returns it. Guarantees to -C only once. Only use this if C is an expression with side effects, -otherwise use the more efficient C. - - UV SvUVx(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUV_nomg -X - -Like C but doesn't process magic. - - UV SvUV_nomg(SV* sv) - -=for hackers -Found in file sv.h - -=item SvUV_set -X - -Set the value of the UV pointer in sv to val. See C. - - void SvUV_set(SV* sv, UV val) - -=for hackers -Found in file sv.h - -=item SvVOK -X - -Returns a boolean indicating whether the SV contains a v-string. - - bool SvVOK(SV* sv) - -=for hackers -Found in file sv.h - -=item sv_catpvn_nomg -X - -Like C but doesn't process magic. - - void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len) - -=for hackers -Found in file sv.h - -=item sv_catsv_nomg -X - -Like C but doesn't process magic. - - void sv_catsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item sv_derived_from -X - -Returns a boolean indicating whether the SV is derived from the specified class -I. To check derivation at the Perl level, call C as a -normal Perl method. - - bool sv_derived_from(SV* sv, const char *const name) - -=for hackers -Found in file universal.c - -=item sv_does -X - -Returns a boolean indicating whether the SV performs a specific, named role. -The SV can be a Perl object or the name of a Perl class. - - bool sv_does(SV* sv, const char *const name) - -=for hackers -Found in file universal.c - -=item sv_report_used -X - -Dump the contents of all SVs not yet freed. (Debugging aid). - - void sv_report_used() - -=for hackers -Found in file sv.c - -=item sv_setsv_nomg -X - -Like C but doesn't process magic. - - void sv_setsv_nomg(SV* dsv, SV* ssv) - -=for hackers -Found in file sv.h - -=item sv_utf8_upgrade_nomg -X - -Like sv_utf8_upgrade, but doesn't do magic on C - - 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 - -Test if the content of an SV looks like a number (or is a number). -C and C are treated as numbers (so will not issue a -non-numeric warning), even if your atof() doesn't grok them. - - I32 looks_like_number(SV *const sv) - -=for hackers -Found in file sv.c - -=item newRV_noinc -X - -Creates an RV wrapper for an SV. The reference count for the original -SV is B incremented. - - SV* newRV_noinc(SV *const sv) - -=for hackers -Found in file sv.c - -=item newSV -X - -Creates a new SV. A non-zero C parameter indicates the number of -bytes of preallocated string space the SV should have. An extra byte for a -trailing NUL is also reserved. (SvPOK is not set for the SV even if string -space is allocated.) The reference count for the new SV is set to 1. - -In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first -parameter, I, a debug aid which allowed callers to identify themselves. -This aid has been superseded by a new build option, PERL_MEM_LOG (see -L). The older API is still there for use in XS -modules supporting older perls. - - SV* newSV(const STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVhek -X - -Creates a new SV from the hash key structure. It will generate scalars that -point to the shared string table where possible. Returns a new (undefined) -SV if the hek is NULL. - - SV* newSVhek(const HEK *const hek) - -=for hackers -Found in file sv.c - -=item newSViv -X - -Creates a new SV and copies an integer into it. The reference count for the -SV is set to 1. - - SV* newSViv(const IV i) - -=for hackers -Found in file sv.c - -=item newSVnv -X - -Creates a new SV and copies a floating point value into it. -The reference count for the SV is set to 1. - - SV* newSVnv(const NV n) - -=for hackers -Found in file sv.c - -=item newSVpv -X - -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. If C is zero, Perl will compute the length using -strlen(). For efficiency, consider using C instead. - - SV* newSVpv(const char *const s, const STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvf -X - -Creates a new SV and initializes it with the string formatted like -C. - - SV* newSVpvf(const char *const pat, ...) - -=for hackers -Found in file sv.c - -=item newSVpvn -X - -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. Note that if C is zero, Perl will create a zero length -string. You are responsible for ensuring that the source string is at least -C bytes long. If the C argument is NULL the new SV will be undefined. - - SV* newSVpvn(const char *const s, const STRLEN len) - -=for hackers -Found in file sv.c - -=item newSVpvn_flags -X - -Creates a new SV and copies a string into it. The reference count for the -SV is set to 1. Note that if C is zero, Perl will create a zero length -string. You are responsible for ensuring that the source string is at least -C bytes long. If the C argument is NULL the new SV will be undefined. -Currently the only flag bits accepted are C and C. -If C is set, then C is called on the result before -returning. If C is set, then it will be set on the new SV. -C 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 - -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 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 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 - -Like C, but takes a literal string instead of a string/length pair. - - SV* newSVpvs(const char* s) - -=for hackers -Found in file handy.h - -=item newSVpvs_flags -X - -Like C, 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 - -Like C, but takes a literal string instead of a string/length -pair and omits the hash parameter. - - SV* newSVpvs_share(const char* s) - -=for hackers -Found in file handy.h - -=item newSVrv -X - -Creates a new SV for the RV, C, to point to. If C is not an RV then -it will be upgraded to one. If C is non-null then the new SV will -be blessed in the specified package. The new SV is returned and its -reference count is 1. - - SV* newSVrv(SV *const rv, const char *const classname) - -=for hackers -Found in file sv.c - -=item newSVsv -X - -Creates a new SV which is an exact duplicate of the original SV. -(Uses C). - - SV* newSVsv(SV *const old) - -=for hackers -Found in file sv.c - -=item newSVuv -X - -Creates a new SV and copies an unsigned integer into it. -The reference count for the SV is set to 1. - - SV* newSVuv(const UV u) - -=for hackers -Found in file sv.c - -=item newSV_type -X - -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 - -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 - -Using various gambits, try to get a CV from an SV; in addition, try if -possible to set C<*st> and C<*gvp> to the stash and GV associated with it. -The flags in C are passed to sv_fetchsv. - - CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref) - -=for hackers -Found in file sv.c - -=item sv_2io -X - -Using various gambits, try to get an IO from an SV: the IO slot if its a -GV; or the recursive result if we're an RV; or the IO slot of the symbol -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 - -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 and C macros. - - IV sv_2iv_flags(SV *const sv, const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_2mortal -X - -Marks an existing SV as mortal. The SV will be destroyed "soon", either -by an explicit call to FREETMPS, or by an implicit call at places such as -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 -and C. - - SV* sv_2mortal(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_2nv -X - -Return the num value of an SV, doing any necessary string or integer -conversion, magic etc. Normally used via the C and C -macros. - - NV sv_2nv(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_2pvbyte -X - -Return a pointer to the byte-encoded representation of the SV, and set *lp -to its length. May cause the SV to be downgraded from UTF-8 as a -side-effect. - -Usually accessed via the C macro. - - char* sv_2pvbyte(SV *const sv, STRLEN *const lp) - -=for hackers -Found in file sv.c - -=item sv_2pvutf8 -X - -Return a pointer to the UTF-8-encoded representation of the SV, and set *lp -to its length. May cause the SV to be upgraded to UTF-8 as a side-effect. - -Usually accessed via the C macro. - - char* sv_2pvutf8(SV *const sv, STRLEN *const lp) - -=for hackers -Found in file sv.c - -=item sv_2pv_flags -X - -Returns a pointer to the string value of an SV, and sets *lp to its length. -If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string -if necessary. -Normally invoked via the C macro. C and C -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 - -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 and C macros. - - UV sv_2uv_flags(SV *const sv, const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_backoff -X - -Remove any string offset. You should normally use the C macro -wrapper instead. - - int sv_backoff(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_bless -X - -Blesses an SV into a specified package. The SV must be an RV. The package -must be designated by its stash (see C). The reference count -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 - -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. - - void sv_catpv(SV *const sv, const char* ptr) - -=for hackers -Found in file sv.c - -=item sv_catpvf -X - -Processes its arguments like C and appends the formatted -output to an SV. If the appended data contains "wide" characters -(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. 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 - -Like C, 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 - -Concatenates the string onto the end of the string which is in the SV. The -C indicates number of bytes to copy. If the SV has the UTF-8 -status set, then the bytes appended should be valid UTF-8. -Handles 'get' magic, but not 'set' magic. See C. - - void sv_catpvn(SV *dsv, const char *sstr, STRLEN len) - -=for hackers -Found in file sv.c - -=item sv_catpvn_flags -X - -Concatenates the string onto the end of the string which is in the SV. The -C indicates number of bytes to copy. If the SV has the UTF-8 -status set, then the bytes appended should be valid UTF-8. -If C has C bit set, will C on C if -appropriate, else not. C and C 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 - -Like C, 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 - -Like C, 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 - -Concatenates the string from SV C onto the end of the string in -SV C. Modifies C but not C. Handles 'get' magic, but -not 'set' magic. See C. - - void sv_catsv(SV *dstr, SV *sstr) - -=for hackers -Found in file sv.c - -=item sv_catsv_flags -X - -Concatenates the string from SV C onto the end of the string in -SV C. Modifies C but not C. If C has C -bit set, will C on the SVs if appropriate, else not. C -and C 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 - -Efficient removal of characters from the beginning of the string buffer. -SvPOK(sv) must be true and the C must be a pointer to somewhere inside -the string buffer. The C becomes the first character of the adjusted -string. Uses the "OOK hack". -Beware: after this function returns, C and SvPVX_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 - -Clear an SV: call any destructors, free up any memory used by the body, -and free the body itself. The SV's head is I freed, although -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 (or its macro wrapper C) -instead. - - void sv_clear(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_cmp -X - -Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the -string in C is less than, equal to, or greater than the string in -C. Is UTF-8 and 'use bytes' aware, handles get magic, and will -coerce its args to strings if necessary. See also C. - - I32 sv_cmp(SV *const sv1, SV *const sv2) - -=for hackers -Found in file sv.c - -=item sv_cmp_locale -X - -Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and -'use bytes' aware, handles get magic, and will coerce its args to strings -if necessary. See also C. - - I32 sv_cmp_locale(SV *const sv1, SV *const sv2) - -=for hackers -Found in file sv.c - -=item sv_collxfrm -X - -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 - -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 - -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 - -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 - -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 is set -then a copy-on-write scalar drops its PV buffer (if any) and becomes -SvPOK_off rather than making a copy. (Used where this scalar is about to be -set to some other value.) In addition, the C parameter gets passed to -C when unrefing. C calls this function -with flags set to 0. - - void sv_force_normal_flags(SV *const sv, const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_free -X - -Decrement an SV's reference count, and if it drops to zero, call -C to invoke destructors and free up any memory used by -the body; finally, deallocate the SV's head itself. -Normally called via a wrapper macro C. - - void sv_free(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_gets -X - -Get a line from the filehandle and store it into the SV, optionally -appending to the currently-stored string. - - char* sv_gets(SV *const sv, PerlIO *const fp, I32 append) - -=for hackers -Found in file sv.c - -=item sv_grow -X - -Expands the character buffer in the SV. If necessary, uses C and -upgrades the SV to C. Returns a pointer to the character buffer. -Use the C wrapper instead. - - char* sv_grow(SV *const sv, STRLEN newlen) - -=for hackers -Found in file sv.c - -=item sv_inc -X - -Auto-increment of the value in the SV, doing string to numeric conversion -if necessary. Handles 'get' magic. - - void sv_inc(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_insert -X - -Inserts a string at the specified offset/length within the SV. Similar to -the Perl substr() function. 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 - -Same as C, but the extra C are passed the C that applies to C. - - 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 - -Returns a boolean indicating whether the SV is blessed into the specified -class. This does not check for subtypes; use C 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 - -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 - -Returns the length of the string in the SV. Handles magic and type -coercion. See also C, which gives raw access to the xpv_cur slot. - - STRLEN sv_len(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_len_utf8 -X - -Returns the number of characters in the string in an SV, counting wide -UTF-8 bytes as a single character. Handles magic and type coercion. - - STRLEN sv_len_utf8(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_magic -X - -Adds magic to an SV. First upgrades C to type C if necessary, -then adds a new magic item of type C to the head of the magic list. - -See C (which C now calls) for a description of the -handling of the C and C arguments. - -You need to use C 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 - -Adds magic to an SV, upgrading it if necessary. Applies the -supplied vtable and returns a pointer to the magic added. - -Note that C will allow things that C will not. -In particular, you can add magic to SvREADONLY SVs, and add more than -one instance of the same 'how'. - -If C is greater than zero then a C I of C is -stored, if C is zero then C is stored as-is and - as another -special case - if C<(name && namlen == HEf_SVKEY)> then C is assumed -to contain an C and is stored as-is with its REFCNT incremented. - -(This is now used as a subroutine by C.) - - MAGIC * sv_magicext(SV *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 - -Creates a new SV which is a copy of the original SV (using C). -The new SV is marked as mortal. It will be destroyed "soon", either by an -explicit call to FREETMPS, or by an implicit call at places such as -statement boundaries. See also C and C. - - SV* sv_mortalcopy(SV *const oldsv) - -=for hackers -Found in file sv.c - -=item sv_newmortal -X - -Creates a new null SV which is mortal. The reference count of the SV is -set to 1. It will be destroyed "soon", either by an explicit call to -FREETMPS, or by an implicit call at places such as statement boundaries. -See also C and C. - - SV* sv_newmortal() - -=for hackers -Found in file sv.c - -=item sv_newref -X - -Increment an SV's reference count. Use the C wrapper -instead. - - SV* sv_newref(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_pos_b2u -X - -Converts the value pointed to by offsetp from a count of bytes from the -start of the string, to a count of the equivalent number of UTF-8 chars. -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 - -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 - -The backend for the C 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 - -Get a sensible string out of the SV somehow. -A private implementation of the C macro for compilers which -can't cope with complex macro expressions. Always use the macro instead. - - char* sv_pvn_force(SV* sv, STRLEN* lp) - -=for hackers -Found in file sv.c - -=item sv_pvn_force_flags -X - -Get a sensible string out of the SV somehow. -If C has C bit set, will C on C if -appropriate, else not. C and C are -implemented in terms of this function. -You normally want to use the various wrapper macros instead: see -C and C - - 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 - -The backend for the C 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 - -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 - -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 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 - -Underlying implementation for the C 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 - -Weaken a reference: set the C flag on this RV; give the -referred-to SV C magic if it hasn't already; and -push a back-reference to this RV onto the array of backreferences -associated with that magic. 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 - -Copies an integer into the given SV, upgrading first if necessary. -Does not handle 'set' magic. See also C. - - void sv_setiv(SV *const sv, const IV num) - -=for hackers -Found in file sv.c - -=item sv_setiv_mg -X - -Like C, 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 - -Copies a double into the given SV, upgrading first if necessary. -Does not handle 'set' magic. See also C. - - void sv_setnv(SV *const sv, const NV num) - -=for hackers -Found in file sv.c - -=item sv_setnv_mg -X - -Like C, 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 - -Copies a string into an SV. The string must be null-terminated. Does not -handle 'set' magic. See C. - - void sv_setpv(SV *const sv, const char *const ptr) - -=for hackers -Found in file sv.c - -=item sv_setpvf -X - -Works like C but copies the text into the SV instead of -appending it. Does not handle 'set' magic. See C. - - void sv_setpvf(SV *const sv, const char *const pat, ...) - -=for hackers -Found in file sv.c - -=item sv_setpvf_mg -X - -Like C, 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 - -Copies an integer into the given SV, also updating its string value. -Does not handle 'set' magic. See C. - - void sv_setpviv(SV *const sv, const IV num) - -=for hackers -Found in file sv.c - -=item sv_setpviv_mg -X - -Like C, 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 - -Copies a string into an SV. The C parameter indicates the number of -bytes to be copied. If the C argument is NULL the SV will become -undefined. Does not handle 'set' magic. See C. - - 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 - -Like C, 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 - -Like C, but takes a literal string instead of a string/length pair. - - void sv_setpvs(SV* sv, const char* s) - -=for hackers -Found in file handy.h - -=item sv_setpv_mg -X - -Like C, but also handles 'set' magic. - - void sv_setpv_mg(SV *const sv, const char *const ptr) - -=for hackers -Found in file sv.c - -=item sv_setref_iv -X - -Copies an integer into a new SV, optionally blessing the SV. The C -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV -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 - -Copies a double into a new SV, optionally blessing the SV. The C -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV -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 - -Copies a pointer into a new SV, optionally blessing the SV. The C -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. If the C argument is NULL then C will be placed -into the SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV -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 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 - -Copies a string into a new SV, optionally blessing the SV. The length of the -string must be specified with C. The C argument will be upgraded to -an RV. That RV will be modified to point to the new SV. The C -argument indicates the package for the blessing. Set C to -C to avoid the blessing. The new SV will have a reference count -of 1, and the RV will be returned. - -Note that C 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 - -Copies an unsigned integer into a new SV, optionally blessing the SV. The C -argument will be upgraded to an RV. That RV will be modified to point to -the new SV. The C argument indicates the package for the -blessing. Set C to C to avoid the blessing. The new SV -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 - -Copies the contents of the source SV C into the destination SV -C. The source SV may be destroyed if it is mortal, so don't use this -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, C, C and -C. - - void sv_setsv(SV *dstr, SV *sstr) - -=for hackers -Found in file sv.c - -=item sv_setsv_flags -X - -Copies the contents of the source SV C into the destination SV -C. The source SV may be destroyed if it is mortal, so don't use this -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 parameter has the C bit set, will C on -C if appropriate, else not. If the C parameter has the -C bit set then the buffers of temps will not be stolen. -and C are implemented in terms of this function. - -You probably want to use one of the assortment of wrappers, such as -C, C, C and -C. - -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 - -Like C, 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 - -Copies an unsigned integer into the given SV, upgrading first if necessary. -Does not handle 'set' magic. See also C. - - void sv_setuv(SV *const sv, const UV num) - -=for hackers -Found in file sv.c - -=item sv_setuv_mg -X - -Like C, 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 - -Test an SV for taintedness. Use C instead. - bool sv_tainted(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_true -X - -Returns true if the SV has a true value by Perl's rules. -Use the C macro instead, which may call C or may -instead use an in-line version. - - I32 sv_true(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_unmagic -X - -Removes all magic of type C from an SV. - - int sv_unmagic(SV *const sv, const int type) - -=for hackers -Found in file sv.c - -=item sv_unref_flags -X - -Unsets the RV status of the SV, and decrements the reference count of -whatever was being referenced by the RV. This can almost be thought of -as a reversal of C. The C argument can contain -C 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. - - void sv_unref_flags(SV *const ref, const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_untaint -X - -Untaint an SV. Use C instead. - void sv_untaint(SV *const sv) - -=for hackers -Found in file sv.c - -=item sv_upgrade -X - -Upgrade an SV to a more complex form. Generally adds a new body type to the -SV, then copies across as much information as possible from the old body. -You generally want to use the C macro wrapper. See also C. - - void sv_upgrade(SV *const sv, svtype new_type) - -=for hackers -Found in file sv.c - -=item sv_usepvn_flags -X - -Tells an SV to use C to find its string value. Normally the -string is stored inside the SV but sv_usepvn allows the SV to use an -outside string. The C should point to memory that was allocated -by C. The string length, C, must be supplied. By default -this function will realloc (i.e. move) the memory pointed to by C, -so that pointer should not be freed or used by the programmer after -giving it to sv_usepvn, and neither should any pointers from "behind" -that pointer (e.g. ptr + 1) be used. - -If C & SV_SMAGIC is true, will call SvSETMAGIC. If C & -SV_HAS_TRAILING_NUL is true, then C must be NUL, and the realloc -will be skipped. (i.e. the buffer is actually at least 1 byte longer than -C, and already meets the requirements for storing in C) - - void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len, const U32 flags) - -=for hackers -Found in file sv.c - -=item sv_utf8_decode -X - -If the PV of the SV is an octet sequence in UTF-8 -and contains a multiple-byte character, the C flag is turned on -so that it looks like a character. If the PV contains only single-byte -characters, the C 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 - -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 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 - -Converts the PV of an SV to UTF-8, but then turns the C -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 - -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 on C 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 - -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 has C bit set, -will C on C if appropriate, else not. -Returns the number of bytes in the converted string -C and -C are implemented in terms of this function. - -This is not as a general purpose byte encoding to Unicode interface: -use the Encode extension for that. - - STRLEN sv_utf8_upgrade_flags(SV *const sv, const I32 flags) - -=for hackers -Found in file sv.c - -=item sv_utf8_upgrade_nomg -X - -Like sv_utf8_upgrade, but doesn't do magic on C - - STRLEN sv_utf8_upgrade_nomg(SV *sv) - -=for hackers -Found in file sv.c - -=item sv_vcatpvf -X - -Processes its arguments like C and appends the formatted output -to an SV. Does not handle 'set' magic. See C. - -Usually used via its frontend C. - - 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 - -Processes its arguments like C and appends the formatted output -to an SV. Uses an array of SVs if the C style variable argument list is -missing (NULL). When running with taint checks enabled, indicates via -C if results are untrustworthy (often due to the use of -locales). - -Usually used via one of its frontends C and C. - - 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 - -Like C, but also handles 'set' magic. - -Usually used via its frontend C. - - 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 - -Works like C but copies the text into the SV instead of -appending it. Does not handle 'set' magic. See C. - -Usually used via its frontend C. - - 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 - -Works like C but copies the text into the SV instead of -appending it. - -Usually used via one of its frontends C and C. - - void sv_vsetpvfn(SV *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 - -Like C, but also handles 'set' magic. - -Usually used via its frontend C. - - 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 - -Converts a string C of length C from UTF-8 into native byte encoding. -Unlike C but like C, returns a pointer to -the newly-created string, and updates C to contain the new -length. Returns the original string if no conversion occurs, C -is unchanged. Do nothing if C points to 0. Sets C to -0 if C is converted or 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 - -Converts a string C of length C from the native encoding into UTF-8. -Returns a pointer to the newly-created string, and sets C 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 - -Return true if the strings s1 and s2 differ case-insensitively, false -if not (if they are equal case-insensitively). If u1 is true, the -string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true, -the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2 -are false, the respective string is assumed to be in native 8-bit -encoding. - -If the pe1 and pe2 are non-NULL, the scanning pointers will be copied -in there (they will point at the beginning of the I character). -If the pointers behind pe1 or pe2 are non-NULL, they are the end -pointers beyond which scanning will not continue under any -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 - -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 - -Returns true if first C bytes of the given string form a valid -UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does -not mean 'a string that contains code points above 0x7F encoded in UTF-8' -because a valid ASCII string is a valid UTF-8 string. - -See also is_utf8_string_loclen() and is_utf8_string_loc(). - - bool is_utf8_string(const U8 *s, STRLEN len) - -=for hackers -Found in file utf8.c - -=item is_utf8_string_loc -X - -Like is_utf8_string() but stores the location of the failure (in the -case of "utf8ness failure") or the location s+len (in the case of -"utf8ness success") in the C. - -See also is_utf8_string_loclen() and is_utf8_string(). - - bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p) - -=for hackers -Found in file utf8.c - -=item is_utf8_string_loclen -X - -Like is_utf8_string() but stores the location of the failure (in the -case of "utf8ness failure") or the location s+len (in the case of -"utf8ness success") in the C, and the number of UTF-8 -encoded characters in the C. - -See also is_utf8_string_loc() and is_utf8_string(). - - bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el) - -=for hackers -Found in file utf8.c - -=item pv_uni_display -X - -Build to the scalar dsv a displayable version of the string spv, -length len, the displayable version being at most pvlim bytes long -(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 - -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 - -The encoding is assumed to be an Encode object, on entry the PV -of the sv is assumed to be octets in that encoding, and the sv -will be converted into Unicode (and UTF-8). - -If the sv already is UTF-8 (or if it is not POK), or if the encoding -is not a reference, nothing is done to the sv. If the encoding is not -an C Encoding object, bad things will happen. -(See F and L). - -The PV of the sv is returned. - - char* sv_recode_to_utf8(SV* sv, SV *encoding) - -=for hackers -Found in file sv.c - -=item sv_uni_display -X - -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 - -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 - -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 - -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 - -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 - -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 - -flags - -Returns the native character value of the first character in the string -C -which is assumed to be in UTF-8 encoding; C will be set to the -length, in bytes, of that character. - -Allows length and flags to be passed to low level routine. - - UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) - -=for hackers -Found in file utf8.c - -=item utf8n_to_uvuni -X - -Bottom level UTF-8 decode routine. -Returns the Unicode code point value of the first character in the string C -which is assumed to be in UTF-8 encoding and no longer than C; -C will be set to the length, in bytes, of that character. - -If C does not point to a well-formed UTF-8 character, the behaviour -is dependent on the value of C: if it contains UTF8_CHECK_ONLY, -it is assumed that the caller will raise a warning, and this function -will silently just set C to C<-1> and return zero. If the -C does not contain UTF8_CHECK_ONLY, warnings about -malformations will be given, C will be set to the expected -length of the UTF-8 character in bytes, and zero will be returned. - -The C can also contain various flags to allow deviations from -the strict UTF-8 encoding (see F). - -Most code should use utf8_to_uvchr() rather than call this directly. - - UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags) - -=for hackers -Found in file utf8.c - -=item utf8_distance -X - -Returns the number of UTF-8 characters between the UTF-8 pointers C -and C. - -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 - -Return the UTF-8 pointer C displaced by C characters, either -forward or backward. - -WARNING: do not use the following unless you *know* C is within -the UTF-8 data pointed to by C *and* that on entry C is aligned -on the first byte of character or just after the last byte of a character. - - U8* utf8_hop(const U8 *s, I32 off) - -=for hackers -Found in file utf8.c - -=item utf8_length -X - -Return the length of the UTF-8 char encoded string C in characters. -Stops at C (inclusive). If C s> or if the scan would end -up past C, croaks. - - STRLEN utf8_length(const U8* s, const U8 *e) - -=for hackers -Found in file utf8.c - -=item utf8_to_bytes -X - -Converts a string C of length C from UTF-8 into native byte encoding. -Unlike C, this over-writes the original string, and -updates len to contain the new length. -Returns zero on failure, setting C to -1. - -If you need a copy of the string, see C. - -NOTE: this function is experimental and may change or be -removed without notice. - - U8* utf8_to_bytes(U8 *s, STRLEN *len) - -=for hackers -Found in file utf8.c - -=item utf8_to_uvchr -X - -Returns the native character value of the first character in the string C -which is assumed to be in UTF-8 encoding; C will be set to the -length, in bytes, of that character. - -If C does not point to a well-formed UTF-8 character, zero is -returned and retlen is set, if possible, to -1. - - UV utf8_to_uvchr(const U8 *s, STRLEN *retlen) - -=for hackers -Found in file utf8.c - -=item utf8_to_uvuni -X - -Returns the Unicode code point of the first character in the string C -which is assumed to be in UTF-8 encoding; C will be set to the -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 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 - -Adds the UTF-8 representation of the Native codepoint C to the end -of the string C; C should be have at least C free -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 - -Adds the UTF-8 representation of the Unicode codepoint C to the end -of the string C; C should be have at least C free -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 and C internal functions - -=over 8 - -=item ax -X - -Variable which is setup by C to indicate the stack base offset, -used by the C, C and C macros. The C macro -must be called prior to setup the C variable. - - I32 ax - -=for hackers -Found in file XSUB.h - -=item CLASS -X - -Variable which is setup by C to indicate the -class name for a C++ XS constructor. This is always a C. See C. - - char* CLASS - -=for hackers -Found in file XSUB.h - -=item dAX -X - -Sets up the C variable. -This is usually handled automatically by C by calling C. - - dAX; - -=for hackers -Found in file XSUB.h - -=item dAXMARK -X - -Sets up the C variable and stack marker variable C. -This is usually handled automatically by C by calling C. - - dAXMARK; - -=for hackers -Found in file XSUB.h - -=item dITEMS -X - -Sets up the C variable. -This is usually handled automatically by C by calling C. - - dITEMS; - -=for hackers -Found in file XSUB.h - -=item dUNDERBAR -X - -Sets up the C variable for an XSUB that wishes to use -C. - - dUNDERBAR; - -=for hackers -Found in file XSUB.h - -=item dXSARGS -X - -Sets up stack and mark pointers for an XSUB, calling dSP and dMARK. -Sets up the C and C variables by calling C and C. -This is usually handled automatically by C. - - dXSARGS; - -=for hackers -Found in file XSUB.h - -=item dXSI32 -X - -Sets up the C variable for an XSUB which has aliases. This is usually -handled automatically by C. - - dXSI32; - -=for hackers -Found in file XSUB.h - -=item items -X - -Variable which is setup by C to indicate the number of -items on the stack. See L. - - I32 items - -=for hackers -Found in file XSUB.h - -=item ix -X - -Variable which is setup by C to indicate which of an -XSUB's aliases was used to invoke it. See L. - - I32 ix - -=for hackers -Found in file XSUB.h - -=item newXSproto -X - -Used by C to hook up XSUBs as Perl subs. Adds Perl prototypes to -the subs. - -=for hackers -Found in file XSUB.h - -=item RETVAL -X - -Variable which is setup by C to hold the return value for an -XSUB. This is always the proper type for the XSUB. See -L. - - (whatever) RETVAL - -=for hackers -Found in file XSUB.h - -=item ST -X - -Used to access elements on the XSUB's stack. - - SV* ST(int ix) - -=for hackers -Found in file XSUB.h - -=item THIS -X - -Variable which is setup by C to designate the object in a C++ -XSUB. This is always the proper type for the C++ object. See C and -L. - - (whatever) THIS - -=for hackers -Found in file XSUB.h - -=item UNDERBAR -X - -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 - -Macro to declare an XSUB and its C parameter list. This is handled by -C. - -=for hackers -Found in file XSUB.h - -=item XS_VERSION -X - -The version identifier for an XS module. This is usually -handled automatically by C. See C. - -=for hackers -Found in file XSUB.h - -=item XS_VERSION_BOOTCHECK -X - -Macro to verify that a PM module's $VERSION variable matches the XS -module's C variable. This is usually handled automatically by -C. See L. - - XS_VERSION_BOOTCHECK; - -=for hackers -Found in file XSUB.h - - -=back - -=head1 Warning and Dieing - -=over 8 - -=item croak -X - -This is the XSUB-writer's interface to Perl's C function. -Normally call this function the same way you call the C C -function. Calling C returns control directly to Perl, -sidestepping the normal C order of execution. See C. - -If you want to throw an exception object, assign the object to -C<$@> and then pass C to croak(): - - 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 - -This is the XSUB-writer's interface to Perl's C function. Call this -function the same way you call the C C function. See C. - - 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 -. 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 . - -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 4107d5e..0000000 --- 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 - Perl functions - -=head1 DESCRIPTION -X X - -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! - - -=head1 CV reference counts and CvOUTSIDE - -=over 8 - -=item CvWEAKOUTSIDE -X - -Each CV has a pointer, C, 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 in the I that the parent -has a C<&> pad slot pointing back to us. In this case, we set the -C 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 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 causes the chain of Cs 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 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. In this case, its refcount may -not have reached zero, but we still delete its pad and its C etc. -Since various children may still have their C pointing at this -undefined CV, we keep its own C 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 - -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 - -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 - -Get the value from slot C 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 - -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 - -Return the flags for the current compiling pad name -at offset C. Assumes a valid slot entry. - - U32 PAD_COMPNAME_FLAGS(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_GEN -X - -The generation number of the name at offset C in the current -compiling pad (lvalue). Note that C is hijacked for this purpose. - - STRLEN PAD_COMPNAME_GEN(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_GEN_set -X - -Sets the generation number of the name at offset C in the current -ling pad (lvalue) to C. Note that C 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 - -Return the stash associated with an C variable. -Assumes the slot entry is a valid C lexical. - - HV * PAD_COMPNAME_OURSTASH(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_PV -X - -Return the name of the current compiling pad name -at offset C. Assumes a valid slot entry. - - char * PAD_COMPNAME_PV(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_COMPNAME_TYPE -X - -Return the type (stash) of the current compiling pad name at offset -C. 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 - -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 - -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 - -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 - -Save the current pad then set it to null. - - void PAD_SAVE_SETNULLPAD() - -=for hackers -Found in file pad.h - -=item PAD_SETSV -X - -Set the slot at offset C in the current pad to C - - SV * PAD_SETSV(PADOFFSET po, SV* sv) - -=for hackers -Found in file pad.h - -=item PAD_SET_CUR -X - -Set the current pad to be pad C 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 - -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 - -Get the value at offset C in the current pad - - void PAD_SV(PADOFFSET po) - -=for hackers -Found in file pad.h - -=item PAD_SVl -X - -Lightweight and lvalue version of C. -Get or set the value at offset C in the current pad. -Unlike C, 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 - -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 - -save PL_comppad and PL_curpad - - - - - - void SAVECOMPPAD() - -=for hackers -Found in file pad.h - -=item SAVEPADSV -X - -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 - -Returns C 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 is not used at present but available for future extension to -allow selecting particular classes of magical variable. - -Currently assumes that C 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 - -Generates and returns a C by walking up the tree starting at the passed -in C. - - HV * refcounted_he_chain_2hv(const struct refcounted_he *c) - -=for hackers -Found in file hv.c - -=item refcounted_he_free -X - -Decrements the reference count of the passed in C -by one. If the reference count reaches zero the structure's memory is freed, -and C 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 - -Creates a new C. As S is copied, and value is -stored in a compact form, all references remain the property of the caller. -The C 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 - -Function called by C to spawn a glob (or do the glob inside -perl on VMS). This code used to be inline, but now perl uses C -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 - -Triggered by a delete from %^H, records the key to -C. - - int magic_clearhint(SV* sv, MAGIC* mg) - -=for hackers -Found in file mg.c - -=item magic_sethint -X - -Triggered by a store to %^H, records the key/value pair to -C. 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 - -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 - -Returns the Depth-First Search linearization of @ISA -the given stash. The return value is a read-only AV*. -C should be 0 (it is used internally in this -function's recursion). - -You are responsible for C 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 - -Takes the necessary steps (cache invalidations, mostly) -when the @ISA of the given package has changed. Invoked -by the C 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 - -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 is set to the names AV. -C is set to the frame AV for the frame CvDEPTH == 1. -C is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)). - -During execution, C and C 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 lexicals, the type is also SVt_PVMG, with the -SvOURSTASH slot pointing at the stash of the associated global (so that -duplicate C 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 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 - -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 - -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 - -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 - -"Introduce" my variables to visible status. - - U32 intro_my() - -=for hackers -Found in file pad.c - -=item pad_add_anon -X - -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 - -Create a new name and associated PADMY SV in the current pad; return the -offset. -If C is valid, the name is for a typed lexical; set the -name's stash to that value. -If C 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 - -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 - -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 - -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 -C 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 - -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 - -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 - -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 - -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 - -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 - -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 - -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 - -Mark all the current temporaries for reuse - - void pad_reset() - -=for hackers -Found in file pad.c - -=item pad_setsv -X - -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 - -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 - -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 - -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 - -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. - - SV * PL_DBsingle - -=for hackers -Found in file intrpvar.h - -=item PL_DBsub -X - -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. - - GV * PL_DBsub - -=for hackers -Found in file intrpvar.h - -=item PL_DBtrace -X - -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. - - SV * PL_DBtrace - -=for hackers -Found in file intrpvar.h - -=item PL_dowarn -X - -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 - -The GV which was last used for a filehandle input operation. (C<< >>) - - GV* PL_last_in_gv - -=for hackers -Found in file intrpvar.h - -=item PL_ofsgv -X - -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 - -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 - -Declare Just C. This is actually identical to C, and declares -a local copy of perl's stack pointer, available via the C macro. -See C. (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 - -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 - -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 - -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 - -Attempt to destroy all objects not yet freed - - void sv_clean_objs() - -=for hackers -Found in file sv.c - -=item sv_free_arenas -X - -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 - -Return an SV with the numeric value of the source SV, doing any necessary -reference or overload conversion. You must use the C 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 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 - -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 b8ea2c1..6730bcc 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 3de30cb..dde2a36 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 915d8b9..6f2f5d8 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 \