1 -*- buffer-read-only: t -*-
3 !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
4 This file is built by autodoc.pl extracting documentation from the C source
9 perlapi - autogenerated documentation for the perl public API
12 X<Perl API> X<API> X<api>
14 This file contains the documentation of the perl public API generated by
15 embed.pl, specifically a listing of functions, macros, flags, and variables
16 that may be used by extension writers. The interfaces of any functions that
17 are not listed here are subject to change without notice. For this reason,
18 blindly using functions listed in proto.h is to be avoided when writing
21 Note that all Perl API global variables must be referenced with the C<PL_>
22 prefix. Some macros are provided for compatibility with the older,
23 unadorned names, but this support may be disabled in a future release.
25 Perl was originally written to handle US-ASCII only (that is characters
26 whose ordinal numbers are in the range 0 - 127).
27 And documentation and comments may still use the term ASCII, when
28 sometimes in fact the entire range from 0 - 255 is meant.
30 Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>)
31 or ASCII. Most of the documentation (and even comments in the code)
32 ignore the EBCDIC possibility.
33 For almost all purposes the differences are transparent.
34 As an example, under EBCDIC,
35 instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so
36 whenever this documentation refers to C<utf8>
37 (and variants of that name, including in function names),
38 it also (essentially transparently) means C<UTF-EBCDIC>.
39 But the ordinals of characters differ between ASCII, EBCDIC, and
40 the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes
43 Also, on some EBCDIC machines, functions that are documented as operating on
44 US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all
45 256 characters in the EBCDIC range, not just the subset corresponding to
48 The listing below is alphabetical, case insensitive.
58 A backward-compatible version of C<GIMME_V> which can only return
59 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
60 Deprecated. Use C<GIMME_V> instead.
70 The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
71 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
82 Used to indicate list context. See C<GIMME_V>, C<GIMME> and
91 Indicates that arguments returned from a callback should be discarded. See
100 Used to force a Perl C<eval> wrapper around a callback. See
109 Indicates that no arguments are being sent to a callback. See
118 Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
127 Used to indicate void context. See C<GIMME_V> and L<perlcall>.
135 =head1 Array Manipulation Functions
142 Same as C<av_len()>. Deprecated, use C<av_len()> instead.
152 Clears an array, making it empty. Does not free the memory used by the
155 void av_clear(AV *av)
160 =item av_create_and_push
161 X<av_create_and_push>
163 Push an SV onto the end of the array, creating the array if necessary.
164 A small internal helper function to remove a commonly duplicated idiom.
166 NOTE: this function is experimental and may change or be
167 removed without notice.
169 void av_create_and_push(AV **const avp, SV *const val)
174 =item av_create_and_unshift_one
175 X<av_create_and_unshift_one>
177 Unshifts an SV onto the beginning of the array, creating the array if
179 A small internal helper function to remove a commonly duplicated idiom.
181 NOTE: this function is experimental and may change or be
182 removed without notice.
184 SV** av_create_and_unshift_one(AV **const avp, SV *const val)
192 Deletes the element indexed by C<key> from the array. Returns the
193 deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
194 and null is returned.
196 SV* av_delete(AV *av, I32 key, I32 flags)
204 Returns true if the element indexed by C<key> has been initialized.
206 This relies on the fact that uninitialized array elements are set to
209 bool av_exists(AV *av, I32 key)
217 Pre-extend an array. The C<key> is the index to which the array should be
220 void av_extend(AV *av, I32 key)
228 Returns the SV at the specified index in the array. The C<key> is the
229 index. If C<lval> is set then the fetch will be part of a store. Check
230 that the return value is non-null before dereferencing it to a C<SV*>.
232 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
233 more information on how to use this function on tied arrays.
235 SV** av_fetch(AV *av, I32 key, I32 lval)
243 Set the highest index in the array to the given number, equivalent to
244 Perl's C<$#array = $fill;>.
246 The number of elements in the an array will be C<fill + 1> after
247 av_fill() returns. If the array was previously shorter then the
248 additional elements appended are set to C<PL_sv_undef>. If the array
249 was longer, then the excess elements are freed. C<av_fill(av, -1)> is
250 the same as C<av_clear(av)>.
252 void av_fill(AV *av, I32 fill)
260 Returns the highest index in the array. The number of elements in the
261 array is C<av_len(av) + 1>. Returns -1 if the array is empty.
271 Creates a new AV and populates it with a list of SVs. The SVs are copied
272 into the array, so they may be freed after the call to av_make. The new AV
273 will have a reference count of 1.
275 AV* av_make(I32 size, SV **strp)
283 Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
294 Pushes an SV onto the end of the array. The array will grow automatically
295 to accommodate the addition.
297 void av_push(AV *av, SV *val)
305 Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the
316 Stores an SV in an array. The array index is specified as C<key>. The
317 return value will be NULL if the operation failed or if the value did not
318 need to be actually stored within the array (as in the case of tied
319 arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
320 that the caller is responsible for suitably incrementing the reference
321 count of C<val> before the call, and decrementing it if the function
324 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
325 more information on how to use this function on tied arrays.
327 SV** av_store(AV *av, I32 key, SV *val)
335 Undefines the array. Frees the memory used by the array itself.
337 void av_undef(AV *av)
345 Unshift the given number of C<undef> values onto the beginning of the
346 array. The array will grow automatically to accommodate the addition. You
347 must then use C<av_store> to assign values to these new elements.
349 void av_unshift(AV *av, I32 num)
357 Returns the AV of the specified Perl array. C<flags> are passed to
358 C<gv_fetchpv>. If C<GV_ADD> is set and the
359 Perl variable does not exist then it will be created. If C<flags> is zero
360 and the variable does not exist then NULL is returned.
362 NOTE: the perl_ form of this function is deprecated.
364 AV* get_av(const char *name, I32 flags)
372 Creates a new AV. The reference count is set to 1.
382 Sort an array. Here is an example:
384 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
386 Currently this always uses mergesort. See sortsv_flags for a more
389 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
392 Found in file pp_sort.c
397 Sort an array, with various options.
399 void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
402 Found in file pp_sort.c
407 =head1 Callback Functions
414 Performs a callback to the specified Perl sub. See L<perlcall>.
416 NOTE: the perl_ form of this function is deprecated.
418 I32 call_argv(const char* sub_name, I32 flags, char** argv)
426 Performs a callback to the specified Perl method. The blessed object must
427 be on the stack. See L<perlcall>.
429 NOTE: the perl_ form of this function is deprecated.
431 I32 call_method(const char* methname, I32 flags)
439 Performs a callback to the specified Perl sub. See L<perlcall>.
441 NOTE: the perl_ form of this function is deprecated.
443 I32 call_pv(const char* sub_name, I32 flags)
451 Performs a callback to the Perl sub whose name is in the SV. See
454 NOTE: the perl_ form of this function is deprecated.
456 I32 call_sv(SV* sv, VOL I32 flags)
464 Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
469 Found in file scope.h
474 Tells Perl to C<eval> the given string and return an SV* result.
476 NOTE: the perl_ form of this function is deprecated.
478 SV* eval_pv(const char* p, I32 croak_on_error)
486 Tells Perl to C<eval> the string in the SV.
488 NOTE: the perl_ form of this function is deprecated.
490 I32 eval_sv(SV* sv, I32 flags)
498 Closing bracket for temporaries on a callback. See C<SAVETMPS> and
504 Found in file scope.h
509 Closing bracket on a callback. See C<ENTER> and L<perlcall>.
514 Found in file scope.h
519 Opening bracket for temporaries on a callback. See C<FREETMPS> and
525 Found in file scope.h
530 =head1 Character classes
537 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
538 alphanumeric character (including underscore) or digit.
540 bool isALNUM(char ch)
543 Found in file handy.h
548 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
549 alphabetic character.
551 bool isALPHA(char ch)
554 Found in file handy.h
559 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
562 bool isDIGIT(char ch)
565 Found in file handy.h
570 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
573 bool isLOWER(char ch)
576 Found in file handy.h
581 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
584 bool isSPACE(char ch)
587 Found in file handy.h
592 Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin)
595 bool isUPPER(char ch)
598 Found in file handy.h
603 Converts the specified character to lowercase. Characters outside the
604 US-ASCII (Basic Latin) range are viewed as not having any case.
606 char toLOWER(char ch)
609 Found in file handy.h
614 Converts the specified character to uppercase. Characters outside the
615 US-ASCII (Basic Latin) range are viewed as not having any case.
617 char toUPPER(char ch)
620 Found in file handy.h
625 =head1 Cloning an interpreter
632 Create and return a new interpreter by cloning the current one.
634 perl_clone takes these flags as parameters:
636 CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
637 without it we only clone the data and zero the stacks,
638 with it we copy the stacks and the new perl interpreter is
639 ready to run at the exact same point as the previous one.
640 The pseudo-fork code uses COPY_STACKS while the
641 threads->create doesn't.
643 CLONEf_KEEP_PTR_TABLE
644 perl_clone keeps a ptr_table with the pointer of the old
645 variable as a key and the new variable as a value,
646 this allows it to check if something has been cloned and not
647 clone it again but rather just use the value and increase the
648 refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
649 the ptr_table using the function
650 C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
651 reason to keep it around is if you want to dup some of your own
652 variable who are outside the graph perl scans, example of this
653 code is in threads.xs create
656 This is a win32 thing, it is ignored on unix, it tells perls
657 win32host code (which is c++) to clone itself, this is needed on
658 win32 if you want to run two threads at the same time,
659 if you just want to do some stuff in a separate perl interpreter
660 and then throw it away and return to the original one,
661 you don't need to do anything.
663 PerlInterpreter* perl_clone(PerlInterpreter *proto_perl, UV flags)
671 =head1 CV Manipulation Functions
678 Returns the stash of the CV.
688 Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
690 NOTE: the perl_ form of this function is deprecated.
692 CV* get_cv(const char* name, I32 flags)
700 Returns the CV of the specified Perl subroutine. C<flags> are passed to
701 C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
702 exist then it will be declared (which has the same effect as saying
703 C<sub name;>). If C<GV_ADD> is not set and the subroutine does not exist
704 then NULL is returned.
706 NOTE: the perl_ form of this function is deprecated.
708 CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
716 =head1 Embedding Functions
723 Clear out all the active components of a CV. This can happen either
724 by an explicit C<undef &foo>, or by the reference count going to zero.
725 In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
726 children can still follow the full lexical scope chain.
728 void cv_undef(CV* cv)
736 Loads the module whose name is pointed to by the string part of name.
737 Note that the actual module name, not its filename, should be given.
738 Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
739 PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
740 (or 0 for no flags). ver, if specified, provides version semantics
741 similar to C<use Foo::Bar VERSION>. The optional trailing SV*
742 arguments can be used to specify arguments to the module's import()
743 method, similar to C<use Foo::Bar VERSION LIST>.
745 void load_module(U32 flags, SV* name, SV* ver, ...)
753 Stub that provides thread hook for perl_destruct when there are
764 Allocates a new Perl interpreter. See L<perlembed>.
766 PerlInterpreter* perl_alloc()
774 Initializes a new Perl interpreter. See L<perlembed>.
776 void perl_construct(PerlInterpreter *my_perl)
784 Shuts down a Perl interpreter. See L<perlembed>.
786 int perl_destruct(PerlInterpreter *my_perl)
794 Releases a Perl interpreter. See L<perlembed>.
796 void perl_free(PerlInterpreter *my_perl)
804 Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
806 int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit, int argc, char** argv, char** env)
814 Tells a Perl interpreter to run. See L<perlembed>.
816 int perl_run(PerlInterpreter *my_perl)
824 Tells Perl to C<require> the file named by the string argument. It is
825 analogous to the Perl code C<eval "require '$file'">. It's even
826 implemented that way; consider using load_module instead.
828 NOTE: the perl_ form of this function is deprecated.
830 void require_pv(const char* pv)
838 =head1 Functions in file dump.c
848 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
850 except that an additional "\0" will be appended to the string when
851 len > cur and pv[cur] is "\0".
853 Note that the final string may be up to 7 chars longer than pvlim.
855 char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
863 Escapes at most the first "count" chars of pv and puts the results into
864 dsv such that the size of the escaped string will not exceed "max" chars
865 and will not contain any incomplete escape sequences.
867 If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
868 will also be escaped.
870 Normally the SV will be cleared before the escaped string is prepared,
871 but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
873 If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
874 if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
875 using C<is_utf8_string()> to determine if it is Unicode.
877 If PERL_PV_ESCAPE_ALL is set then all input chars will be output
878 using C<\x01F1> style escapes, otherwise only chars above 255 will be
879 escaped using this style, other non printable chars will use octal or
880 common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
881 then all chars below 255 will be treated as printable and
882 will be output as literals.
884 If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
885 string will be escaped, regardles of max. If the string is utf8 and
886 the chars value is >255 then it will be returned as a plain hex
887 sequence. Thus the output will either be a single char,
888 an octal escape sequence, a special escape like C<\n> or a 3 or
889 more digit hex value.
891 If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
892 not a '\\'. This is because regexes very often contain backslashed
893 sequences, whereas '%' is not a particularly common character in patterns.
895 Returns a pointer to the escaped text as held by dsv.
897 char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
905 Converts a string into something presentable, handling escaping via
906 pv_escape() and supporting quoting and ellipses.
908 If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
909 double quoted with any double quotes in the string escaped. Otherwise
910 if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
913 If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
914 string were output then an ellipsis C<...> will be appended to the
915 string. Note that this happens AFTER it has been quoted.
917 If start_color is non-null then it will be inserted after the opening
918 quote (if there is one) but before the escaped text. If end_color
919 is non-null then it will be inserted after the escaped text but before
920 any quotes or ellipses.
922 Returns a pointer to the prettified text as held by dsv.
924 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)
932 =head1 Functions in file mathoms.c
940 See L<gv_fetchmethod_autoload>.
942 GV* gv_fetchmethod(HV* stash, const char* name)
945 Found in file mathoms.c
950 The engine implementing pack() Perl function. Note: parameters next_in_list and
951 flags are not used. This call should not be used; use packlist instead.
953 void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
956 Found in file mathoms.c
958 =item sv_2pvbyte_nolen
961 Return a pointer to the byte-encoded representation of the SV.
962 May cause the SV to be downgraded from UTF-8 as a side-effect.
964 Usually accessed via the C<SvPVbyte_nolen> macro.
966 char* sv_2pvbyte_nolen(SV* sv)
969 Found in file mathoms.c
971 =item sv_2pvutf8_nolen
974 Return a pointer to the UTF-8-encoded representation of the SV.
975 May cause the SV to be upgraded to UTF-8 as a side-effect.
977 Usually accessed via the C<SvPVutf8_nolen> macro.
979 char* sv_2pvutf8_nolen(SV* sv)
982 Found in file mathoms.c
987 Like C<sv_2pv()>, but doesn't return the length too. You should usually
988 use the macro wrapper C<SvPV_nolen(sv)> instead.
989 char* sv_2pv_nolen(SV* sv)
992 Found in file mathoms.c
997 Like C<sv_catpvn>, but also handles 'set' magic.
999 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
1002 Found in file mathoms.c
1007 Like C<sv_catsv>, but also handles 'set' magic.
1009 void sv_catsv_mg(SV *dsv, SV *ssv)
1012 Found in file mathoms.c
1014 =item sv_force_normal
1017 Undo various types of fakery on an SV: if the PV is a shared string, make
1018 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
1019 an xpvmg. See also C<sv_force_normal_flags>.
1021 void sv_force_normal(SV *sv)
1024 Found in file mathoms.c
1029 A private implementation of the C<SvIVx> macro for compilers which can't
1030 cope with complex macro expressions. Always use the macro instead.
1035 Found in file mathoms.c
1040 Dummy routine which "locks" an SV when there is no locking module present.
1041 Exists to avoid test for a NULL function pointer and because it could
1042 potentially warn under some level of strict-ness.
1044 "Superseded" by sv_nosharing().
1046 void sv_nolocking(SV *sv)
1049 Found in file mathoms.c
1051 =item sv_nounlocking
1054 Dummy routine which "unlocks" an SV when there is no locking module present.
1055 Exists to avoid test for a NULL function pointer and because it could
1056 potentially warn under some level of strict-ness.
1058 "Superseded" by sv_nosharing().
1060 void sv_nounlocking(SV *sv)
1063 Found in file mathoms.c
1068 A private implementation of the C<SvNVx> macro for compilers which can't
1069 cope with complex macro expressions. Always use the macro instead.
1074 Found in file mathoms.c
1079 Use the C<SvPV_nolen> macro instead
1084 Found in file mathoms.c
1089 Use C<SvPVbyte_nolen> instead.
1091 char* sv_pvbyte(SV *sv)
1094 Found in file mathoms.c
1099 A private implementation of the C<SvPVbyte> macro for compilers
1100 which can't cope with complex macro expressions. Always use the macro
1103 char* sv_pvbyten(SV *sv, STRLEN *lp)
1106 Found in file mathoms.c
1111 A private implementation of the C<SvPV> macro for compilers which can't
1112 cope with complex macro expressions. Always use the macro instead.
1114 char* sv_pvn(SV *sv, STRLEN *lp)
1117 Found in file mathoms.c
1122 Use the C<SvPVutf8_nolen> macro instead
1124 char* sv_pvutf8(SV *sv)
1127 Found in file mathoms.c
1132 A private implementation of the C<SvPVutf8> macro for compilers
1133 which can't cope with complex macro expressions. Always use the macro
1136 char* sv_pvutf8n(SV *sv, STRLEN *lp)
1139 Found in file mathoms.c
1144 Taint an SV. Use C<SvTAINTED_on> instead.
1145 void sv_taint(SV* sv)
1148 Found in file mathoms.c
1153 Unsets the RV status of the SV, and decrements the reference count of
1154 whatever was being referenced by the RV. This can almost be thought of
1155 as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
1156 being zero. See C<SvROK_off>.
1158 void sv_unref(SV* sv)
1161 Found in file mathoms.c
1166 Tells an SV to use C<ptr> to find its string value. Implemented by
1167 calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
1168 magic. See C<sv_usepvn_flags>.
1170 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
1173 Found in file mathoms.c
1178 Like C<sv_usepvn>, but also handles 'set' magic.
1180 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
1183 Found in file mathoms.c
1188 A private implementation of the C<SvUVx> macro for compilers which can't
1189 cope with complex macro expressions. Always use the macro instead.
1194 Found in file mathoms.c
1199 The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
1200 and ocnt are not used. This call should not be used, use unpackstring instead.
1202 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)
1205 Found in file mathoms.c
1210 =head1 Functions in file perl.h
1218 Provides system-specific tune up of the C runtime environment necessary to
1219 run Perl interpreters. This should be called only once, before creating
1220 any Perl interpreters.
1222 void PERL_SYS_INIT(int argc, char** argv)
1225 Found in file perl.h
1227 =item PERL_SYS_INIT3
1230 Provides system-specific tune up of the C runtime environment necessary to
1231 run Perl interpreters. This should be called only once, before creating
1232 any Perl interpreters.
1234 void PERL_SYS_INIT3(int argc, char** argv, char** env)
1237 Found in file perl.h
1242 Provides system-specific clean up of the C runtime environment after
1243 running Perl interpreters. This should be called only once, after
1244 freeing any remaining Perl interpreters.
1246 void PERL_SYS_TERM()
1249 Found in file perl.h
1254 =head1 Functions in file pp_ctl.c
1262 Locate the CV corresponding to the currently executing sub or eval.
1263 If db_seqp is non_null, skip CVs that are in the DB package and populate
1264 *db_seqp with the cop sequence number at the point that the DB:: code was
1265 entered. (allows debuggers to eval in the scope of the breakpoint rather
1266 than in the scope of the debugger itself).
1268 CV* find_runcv(U32 *db_seqp)
1271 Found in file pp_ctl.c
1276 =head1 Functions in file pp_pack.c
1284 The engine implementing pack() Perl function.
1286 void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
1289 Found in file pp_pack.c
1294 The engine implementing unpack() Perl function. C<unpackstring> puts the
1295 extracted list items on the stack and returns the number of elements.
1296 Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
1298 I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
1301 Found in file pp_pack.c
1306 =head1 Functions in file pp_sys.c
1314 Sets PL_defoutgv, the default file handle for output, to the passed in
1315 typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference
1316 count of the passed in typeglob is increased by one, and the reference count
1317 of the typeglob that PL_defoutgv points to is decreased by one.
1319 void setdefout(GV* gv)
1322 Found in file pp_sys.c
1334 Return the SV from the GV.
1344 If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
1345 inlining, or C<gv> is a placeholder reference that would be promoted to such
1346 a typeglob, then returns the value returned by the sub. Otherwise, returns
1349 SV* gv_const_sv(GV* gv)
1357 Returns the glob with the given C<name> and a defined subroutine or
1358 C<NULL>. The glob lives in the given C<stash>, or in the stashes
1359 accessible via @ISA and UNIVERSAL::.
1361 The argument C<level> should be either 0 or -1. If C<level==0>, as a
1362 side-effect creates a glob with the given C<name> in the given C<stash>
1363 which in the case of success contains an alias for the subroutine, and sets
1364 up caching info for this glob.
1366 This function grants C<"SUPER"> token as a postfix of the stash name. The
1367 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
1368 visible to Perl code. So when calling C<call_sv>, you should not use
1369 the GV directly; instead, you should use the method's CV, which can be
1370 obtained from the GV with the C<GvCV> macro.
1372 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
1377 =item gv_fetchmethod_autoload
1378 X<gv_fetchmethod_autoload>
1380 Returns the glob which contains the subroutine to call to invoke the method
1381 on the C<stash>. In fact in the presence of autoloading this may be the
1382 glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
1385 The third parameter of C<gv_fetchmethod_autoload> determines whether
1386 AUTOLOAD lookup is performed if the given method is not present: non-zero
1387 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
1388 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1389 with a non-zero C<autoload> parameter.
1391 These functions grant C<"SUPER"> token as a prefix of the method name. Note
1392 that if you want to keep the returned glob for a long time, you need to
1393 check for it being "AUTOLOAD", since at the later time the call may load a
1394 different subroutine due to $AUTOLOAD changing its value. Use the glob
1395 created via a side effect to do this.
1397 These functions have the same side-effects and as C<gv_fetchmeth> with
1398 C<level==0>. C<name> should be writable if contains C<':'> or C<'
1399 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1400 C<call_sv> apply equally to these functions.
1402 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
1407 =item gv_fetchmeth_autoload
1408 X<gv_fetchmeth_autoload>
1410 Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
1411 Returns a glob for the subroutine.
1413 For an autoloaded subroutine without a GV, will create a GV even
1414 if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
1415 of the result may be zero.
1417 GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
1425 Returns a pointer to the stash for a specified package. Uses C<strlen> to
1426 determine the length of C<name>, then calls C<gv_stashpvn()>.
1428 HV* gv_stashpv(const char* name, I32 flags)
1436 Returns a pointer to the stash for a specified package. The C<namelen>
1437 parameter indicates the length of the C<name>, in bytes. C<flags> is passed
1438 to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
1439 created if it does not already exist. If the package does not exist and
1440 C<flags> is 0 (or any other setting that does not create packages) then NULL
1444 HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
1452 Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
1454 HV* gv_stashpvs(const char* name, I32 create)
1457 Found in file handy.h
1462 Returns a pointer to the stash for a specified package. See C<gv_stashpvn>.
1464 HV* gv_stashsv(SV* sv, I32 flags)
1481 (deprecated - use C<(AV *)NULL> instead)
1489 Null character pointer. (No longer available when C<PERL_CORE> is defined.)
1492 Found in file handy.h
1499 (deprecated - use C<(CV *)NULL> instead)
1509 (deprecated - use C<(HV *)NULL> instead)
1517 Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
1520 Found in file handy.h
1525 =head1 Hash Manipulation Functions
1532 Returns the HV of the specified Perl hash. C<flags> are passed to
1533 C<gv_fetchpv>. If C<GV_ADD> is set and the
1534 Perl variable does not exist then it will be created. If C<flags> is zero
1535 and the variable does not exist then NULL is returned.
1537 NOTE: the perl_ form of this function is deprecated.
1539 HV* get_hv(const char *name, I32 flags)
1542 Found in file perl.c
1547 This flag, used in the length slot of hash entries and magic structures,
1548 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
1549 is to be expected. (For information only--not to be used).
1557 Returns the computed hash stored in the hash entry.
1567 Returns the actual pointer stored in the key slot of the hash entry. The
1568 pointer may be either C<char*> or C<SV*>, depending on the value of
1569 C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
1570 usually preferable for finding the value of a key.
1580 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1581 holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
1582 be assigned to. The C<HePV()> macro is usually preferable for finding key
1585 STRLEN HeKLEN(HE* he)
1593 Returns the key slot of the hash entry as a C<char*> value, doing any
1594 necessary dereferencing of possibly C<SV*> keys. The length of the string
1595 is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
1596 not care about what the length of the key is, you may use the global
1597 variable C<PL_na>, though this is rather less efficient than using a local
1598 variable. Remember though, that hash keys in perl are free to contain
1599 embedded nulls, so using C<strlen()> or similar is not a good way to find
1600 the length of hash keys. This is very similar to the C<SvPV()> macro
1601 described elsewhere in this document. See also C<HeUTF8>.
1603 If you are using C<HePV> to get values to pass to C<newSVpvn()> to create a
1604 new SV, you should consider using C<newSVhek(HeKEY_hek(he))> as it is more
1607 char* HePV(HE* he, STRLEN len)
1615 Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
1616 contain an C<SV*> key.
1626 Returns the key as an C<SV*>. Will create and return a temporary mortal
1627 C<SV*> if the hash entry contains only a C<char*> key.
1629 SV* HeSVKEY_force(HE* he)
1637 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
1638 indicate the presence of an C<SV*> key, and returns the same
1641 SV* HeSVKEY_set(HE* he, SV* sv)
1649 Returns whether the C<char *> value returned by C<HePV> is encoded in UTF-8,
1650 doing any necessary dereferencing of possibly C<SV*> keys. The value returned
1651 will be 0 or non-0, not necessarily 1 (or even a value with any low bits set),
1652 so B<do not> blindly assign this to a C<bool> variable, as C<bool> may be a
1653 typedef for C<char>.
1655 char* HeUTF8(HE* he, STRLEN len)
1663 Returns the value slot (type C<SV*>) stored in the hash entry.
1673 Returns the package name of a stash, or NULL if C<stash> isn't a stash.
1674 See C<SvSTASH>, C<CvSTASH>.
1676 char* HvNAME(HV* stash)
1684 Check that a hash is in an internally consistent state.
1686 void hv_assert(HV *hv)
1694 Clears a hash, making it empty.
1696 void hv_clear(HV *hv)
1701 =item hv_clear_placeholders
1702 X<hv_clear_placeholders>
1704 Clears any placeholders from a hash. If a restricted hash has any of its keys
1705 marked as readonly and the key is subsequently deleted, the key is not actually
1706 deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
1707 it so it will be ignored by future operations such as iterating over the hash,
1708 but will still allow the hash to have a value reassigned to the key at some
1709 future point. This function clears any such placeholder keys from the hash.
1710 See Hash::Util::lock_keys() for an example of its use.
1712 void hv_clear_placeholders(HV *hv)
1720 Deletes a key/value pair in the hash. The value SV is removed from the
1721 hash and returned to the caller. The C<klen> is the length of the key.
1722 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1725 SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
1733 Deletes a key/value pair in the hash. The value SV is removed from the
1734 hash and returned to the caller. The C<flags> value will normally be zero;
1735 if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
1736 precomputed hash value, or 0 to ask for it to be computed.
1738 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
1746 Returns a boolean indicating whether the specified hash key exists. The
1747 C<klen> is the length of the key.
1749 bool hv_exists(HV *hv, const char *key, I32 klen)
1757 Returns a boolean indicating whether the specified hash key exists. C<hash>
1758 can be a valid precomputed hash value, or 0 to ask for it to be
1761 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
1769 Returns the SV which corresponds to the specified key in the hash. The
1770 C<klen> is the length of the key. If C<lval> is set then the fetch will be
1771 part of a store. Check that the return value is non-null before
1772 dereferencing it to an C<SV*>.
1774 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1775 information on how to use this function on tied hashes.
1777 SV** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
1785 Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
1787 SV** hv_fetchs(HV* tb, const char* key, I32 lval)
1790 Found in file handy.h
1795 Returns the hash entry which corresponds to the specified key in the hash.
1796 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1797 if you want the function to compute it. IF C<lval> is set then the fetch
1798 will be part of a store. Make sure the return value is non-null before
1799 accessing it. The return value when C<tb> is a tied hash is a pointer to a
1800 static location, so be sure to make a copy of the structure if you need to
1803 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1804 information on how to use this function on tied hashes.
1806 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
1814 Prepares a starting point to traverse a hash table. Returns the number of
1815 keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
1816 currently only meaningful for hashes without tie magic.
1818 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1819 hash buckets that happen to be in use. If you still need that esoteric
1820 value, you can get it through the macro C<HvFILL(tb)>.
1823 I32 hv_iterinit(HV *hv)
1831 Returns the key from the current position of the hash iterator. See
1834 char* hv_iterkey(HE* entry, I32* retlen)
1842 Returns the key as an C<SV*> from the current position of the hash
1843 iterator. The return value will always be a mortal copy of the key. Also
1846 SV* hv_iterkeysv(HE* entry)
1854 Returns entries from a hash iterator. See C<hv_iterinit>.
1856 You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1857 iterator currently points to, without losing your place or invalidating your
1858 iterator. Note that in this case the current entry is deleted from the hash
1859 with your iterator holding the last reference to it. Your iterator is flagged
1860 to free the entry on the next call to C<hv_iternext>, so you must not discard
1861 your iterator immediately else the entry will leak - call C<hv_iternext> to
1862 trigger the resource deallocation.
1864 HE* hv_iternext(HV *hv)
1872 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1875 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
1880 =item hv_iternext_flags
1881 X<hv_iternext_flags>
1883 Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
1884 The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1885 set the placeholders keys (for restricted hashes) will be returned in addition
1886 to normal keys. By default placeholders are automatically skipped over.
1887 Currently a placeholder is implemented with a value that is
1888 C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
1889 restricted hashes may change, and the implementation currently is
1890 insufficiently abstracted for any change to be tidy.
1892 NOTE: this function is experimental and may change or be
1893 removed without notice.
1895 HE* hv_iternext_flags(HV *hv, I32 flags)
1903 Returns the value from the current position of the hash iterator. See
1906 SV* hv_iterval(HV *hv, HE *entry)
1914 Adds magic to a hash. See C<sv_magic>.
1916 void hv_magic(HV *hv, GV *gv, int how)
1924 Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
1926 SV* hv_scalar(HV *hv)
1934 Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1935 the length of the key. The C<hash> parameter is the precomputed hash
1936 value; if it is zero then Perl will compute it. The return value will be
1937 NULL if the operation failed or if the value did not need to be actually
1938 stored within the hash (as in the case of tied hashes). Otherwise it can
1939 be dereferenced to get the original C<SV*>. Note that the caller is
1940 responsible for suitably incrementing the reference count of C<val> before
1941 the call, and decrementing it if the function returned NULL. Effectively
1942 a successful hv_store takes ownership of one reference to C<val>. This is
1943 usually what you want; a newly created SV has a reference count of one, so
1944 if all your code does is create SVs then store them in a hash, hv_store
1945 will own the only reference to the new SV, and your code doesn't need to do
1946 anything further to tidy up. hv_store is not implemented as a call to
1947 hv_store_ent, and does not create a temporary SV for the key, so if your
1948 key data is not already in SV form then use hv_store in preference to
1951 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1952 information on how to use this function on tied hashes.
1954 SV** hv_store(HV *hv, const char *key, I32 klen, SV *val, U32 hash)
1962 Like C<hv_store>, but takes a literal string instead of a string/length pair
1963 and omits the hash parameter.
1965 SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
1968 Found in file handy.h
1973 Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1974 parameter is the precomputed hash value; if it is zero then Perl will
1975 compute it. The return value is the new hash entry so created. It will be
1976 NULL if the operation failed or if the value did not need to be actually
1977 stored within the hash (as in the case of tied hashes). Otherwise the
1978 contents of the return value can be accessed using the C<He?> macros
1979 described here. Note that the caller is responsible for suitably
1980 incrementing the reference count of C<val> before the call, and
1981 decrementing it if the function returned NULL. Effectively a successful
1982 hv_store_ent takes ownership of one reference to C<val>. This is
1983 usually what you want; a newly created SV has a reference count of one, so
1984 if all your code does is create SVs then store them in a hash, hv_store
1985 will own the only reference to the new SV, and your code doesn't need to do
1986 anything further to tidy up. Note that hv_store_ent only reads the C<key>;
1987 unlike C<val> it does not take ownership of it, so maintaining the correct
1988 reference count on C<key> is entirely the caller's responsibility. hv_store
1989 is not implemented as a call to hv_store_ent, and does not create a temporary
1990 SV for the key, so if your key data is not already in SV form then use
1991 hv_store in preference to hv_store_ent.
1993 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1994 information on how to use this function on tied hashes.
1996 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
2006 void hv_undef(HV *hv)
2014 Creates a new HV. The reference count is set to 1.
2024 =head1 Magical Functions
2031 Clear something magical that the SV represents. See C<sv_magic>.
2033 int mg_clear(SV* sv)
2041 Copies the magic from one SV to another. See C<sv_magic>.
2043 int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
2051 Finds the magic pointer for type matching the SV. See C<sv_magic>.
2053 MAGIC* mg_find(const SV* sv, int type)
2061 Free any magic storage used by the SV. See C<sv_magic>.
2071 Do magic after a value is retrieved from the SV. See C<sv_magic>.
2081 Report on the SV's length. See C<sv_magic>.
2083 U32 mg_length(SV* sv)
2091 Turns on the magical status of an SV. See C<sv_magic>.
2093 void mg_magical(SV* sv)
2101 Do magic after a value is assigned to the SV. See C<sv_magic>.
2111 Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
2112 argument more than once.
2114 void SvGETMAGIC(SV* sv)
2122 Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
2133 Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2134 argument more than once.
2136 void SvSETMAGIC(SV* sv)
2144 Like C<SvSetSV>, but does any set magic required afterwards.
2146 void SvSetMagicSV(SV* dsb, SV* ssv)
2151 =item SvSetMagicSV_nosteal
2152 X<SvSetMagicSV_nosteal>
2154 Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
2156 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2164 Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2167 void SvSetSV(SV* dsb, SV* ssv)
2172 =item SvSetSV_nosteal
2175 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2176 ssv. May evaluate arguments more than once.
2178 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2186 Arranges for sv to be shared between threads if a suitable module
2189 void SvSHARE(SV* sv)
2197 Releases a mutual exclusion lock on sv if a suitable module
2200 void SvUNLOCK(SV* sv)
2208 =head1 Memory Management
2215 The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
2216 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2217 the type. May fail on overlapping copies. See also C<Move>.
2219 void Copy(void* src, void* dest, int nitems, type)
2222 Found in file handy.h
2227 Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
2230 void * CopyD(void* src, void* dest, int nitems, type)
2233 Found in file handy.h
2238 The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
2239 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2240 the type. Can do overlapping moves. See also C<Copy>.
2242 void Move(void* src, void* dest, int nitems, type)
2245 Found in file handy.h
2250 Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
2253 void * MoveD(void* src, void* dest, int nitems, type)
2256 Found in file handy.h
2261 The XSUB-writer's interface to the C C<malloc> function.
2263 In 5.9.3, Newx() and friends replace the older New() API, and drops
2264 the first parameter, I<x>, a debug aid which allowed callers to identify
2265 themselves. This aid has been superseded by a new build option,
2266 PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>). The older API is still
2267 there for use in XS modules supporting older perls.
2269 void Newx(void* ptr, int nitems, type)
2272 Found in file handy.h
2277 The XSUB-writer's interface to the C C<malloc> function, with
2278 cast. See also C<Newx>.
2280 void Newxc(void* ptr, int nitems, type, cast)
2283 Found in file handy.h
2288 The XSUB-writer's interface to the C C<malloc> function. The allocated
2289 memory is zeroed with C<memzero>. See also C<Newx>.
2291 void Newxz(void* ptr, int nitems, type)
2294 Found in file handy.h
2299 PoisonWith(0xEF) for catching access to freed memory.
2301 void Poison(void* dest, int nitems, type)
2304 Found in file handy.h
2309 PoisonWith(0xEF) for catching access to freed memory.
2311 void PoisonFree(void* dest, int nitems, type)
2314 Found in file handy.h
2319 PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
2321 void PoisonNew(void* dest, int nitems, type)
2324 Found in file handy.h
2329 Fill up memory with a byte pattern (a byte repeated over and over
2330 again) that hopefully catches attempts to access uninitialized memory.
2332 void PoisonWith(void* dest, int nitems, type, U8 byte)
2335 Found in file handy.h
2340 The XSUB-writer's interface to the C C<realloc> function.
2342 void Renew(void* ptr, int nitems, type)
2345 Found in file handy.h
2350 The XSUB-writer's interface to the C C<realloc> function, with
2353 void Renewc(void* ptr, int nitems, type, cast)
2356 Found in file handy.h
2361 The XSUB-writer's interface to the C C<free> function.
2363 void Safefree(void* ptr)
2366 Found in file handy.h
2371 Perl's version of C<strdup()>. Returns a pointer to a newly allocated
2372 string which is a duplicate of C<pv>. The size of the string is
2373 determined by C<strlen()>. The memory allocated for the new string can
2374 be freed with the C<Safefree()> function.
2376 char* savepv(const char* pv)
2379 Found in file util.c
2384 Perl's version of what C<strndup()> would be if it existed. Returns a
2385 pointer to a newly allocated string which is a duplicate of the first
2386 C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
2387 the new string can be freed with the C<Safefree()> function.
2389 char* savepvn(const char* pv, I32 len)
2392 Found in file util.c
2397 Like C<savepvn>, but takes a literal string instead of a string/length pair.
2399 char* savepvs(const char* s)
2402 Found in file handy.h
2407 A version of C<savepv()> which allocates the duplicate string in memory
2408 which is shared between threads.
2410 char* savesharedpv(const char* pv)
2413 Found in file util.c
2418 A version of C<savepvn()> which allocates the duplicate string in memory
2419 which is shared between threads. (With the specific difference that a NULL
2420 pointer is not acceptable)
2422 char* savesharedpvn(const char *const pv, const STRLEN len)
2425 Found in file util.c
2430 A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
2431 the passed in SV using C<SvPV()>
2433 char* savesvpv(SV* sv)
2436 Found in file util.c
2441 This is an architecture-independent macro to copy one structure to another.
2443 void StructCopy(type src, type dest, type)
2446 Found in file handy.h
2451 The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
2452 destination, C<nitems> is the number of items, and C<type> is the type.
2454 void Zero(void* dest, int nitems, type)
2457 Found in file handy.h
2462 Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
2465 void * ZeroD(void* dest, int nitems, type)
2468 Found in file handy.h
2473 =head1 Miscellaneous Functions
2480 Analyses the string in order to make fast searches on it using fbm_instr()
2481 -- the Boyer-Moore algorithm.
2483 void fbm_compile(SV* sv, U32 flags)
2486 Found in file util.c
2491 Returns the location of the SV in the string delimited by C<str> and
2492 C<strend>. It returns C<NULL> if the string can't be found. The C<sv>
2493 does not have to be fbm_compiled, but the search will not be as fast
2496 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlestr, U32 flags)
2499 Found in file util.c
2504 Takes a sprintf-style format pattern and conventional
2505 (non-SV) arguments and returns the formatted string.
2507 (char *) Perl_form(pTHX_ const char* pat, ...)
2509 can be used any place a string (char *) is required:
2511 char * s = Perl_form("%d.%d",major,minor);
2513 Uses a single private buffer so if you want to format several strings you
2514 must explicitly copy the earlier strings away (and free the copies when you
2517 char* form(const char* pat, ...)
2520 Found in file util.c
2525 Fill the sv with current working directory
2527 int getcwd_sv(SV* sv)
2530 Found in file util.c
2535 The C library C<snprintf> functionality, if available and
2536 standards-compliant (uses C<vsnprintf>, actually). However, if the
2537 C<vsnprintf> is not available, will unfortunately use the unsafe
2538 C<vsprintf> which can overrun the buffer (there is an overrun check,
2539 but that may be too late). Consider using C<sv_vcatpvf> instead, or
2540 getting C<vsnprintf>.
2542 int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
2545 Found in file util.c
2550 The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2551 the length of the string written to the buffer. Only rare pre-ANSI systems
2552 need the wrapper function - usually this is a direct call to C<sprintf>.
2554 int my_sprintf(char *buffer, const char *pat, ...)
2557 Found in file util.c
2562 The C library C<vsnprintf> if available and standards-compliant.
2563 However, if if the C<vsnprintf> is not available, will unfortunately
2564 use the unsafe C<vsprintf> which can overrun the buffer (there is an
2565 overrun check, but that may be too late). Consider using
2566 C<sv_vcatpvf> instead, or getting C<vsnprintf>.
2568 int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
2571 Found in file util.c
2576 Returns a new version object based on the passed in SV:
2578 SV *sv = new_version(SV *ver);
2580 Does not alter the passed in ver SV. See "upg_version" if you
2581 want to upgrade the SV.
2583 SV* new_version(SV *ver)
2586 Found in file util.c
2591 Returns a pointer to the next character after the parsed
2592 version string, as well as upgrading the passed in SV to
2595 Function must be called with an already existing SV like
2598 s = scan_version(s, SV *sv, bool qv);
2600 Performs some preprocessing to the string to ensure that
2601 it has the correct characteristics of a version. Flags the
2602 object if it contains an underscore (which denotes this
2603 is an alpha version). The boolean qv denotes that the version
2604 should be interpreted as if it had multiple decimals, even if
2607 const char* scan_version(const char *s, SV *rv, bool qv)
2610 Found in file util.c
2615 Test two strings to see if they are equal. Returns true or false.
2617 bool strEQ(char* s1, char* s2)
2620 Found in file handy.h
2625 Test two strings to see if the first, C<s1>, is greater than or equal to
2626 the second, C<s2>. Returns true or false.
2628 bool strGE(char* s1, char* s2)
2631 Found in file handy.h
2636 Test two strings to see if the first, C<s1>, is greater than the second,
2637 C<s2>. Returns true or false.
2639 bool strGT(char* s1, char* s2)
2642 Found in file handy.h
2647 Test two strings to see if the first, C<s1>, is less than or equal to the
2648 second, C<s2>. Returns true or false.
2650 bool strLE(char* s1, char* s2)
2653 Found in file handy.h
2658 Test two strings to see if the first, C<s1>, is less than the second,
2659 C<s2>. Returns true or false.
2661 bool strLT(char* s1, char* s2)
2664 Found in file handy.h
2669 Test two strings to see if they are different. Returns true or
2672 bool strNE(char* s1, char* s2)
2675 Found in file handy.h
2680 Test two strings to see if they are equal. The C<len> parameter indicates
2681 the number of bytes to compare. Returns true or false. (A wrapper for
2684 bool strnEQ(char* s1, char* s2, STRLEN len)
2687 Found in file handy.h
2692 Test two strings to see if they are different. The C<len> parameter
2693 indicates the number of bytes to compare. Returns true or false. (A
2694 wrapper for C<strncmp>).
2696 bool strnNE(char* s1, char* s2, STRLEN len)
2699 Found in file handy.h
2701 =item sv_destroyable
2704 Dummy routine which reports that object can be destroyed when there is no
2705 sharing module present. It ignores its single SV argument, and returns
2706 'true'. Exists to avoid test for a NULL function pointer and because it
2707 could potentially warn under some level of strict-ness.
2709 bool sv_destroyable(SV *sv)
2712 Found in file util.c
2717 Dummy routine which "shares" an SV when there is no sharing module present.
2718 Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2719 Exists to avoid test for a NULL function pointer and because it could
2720 potentially warn under some level of strict-ness.
2722 void sv_nosharing(SV *sv)
2725 Found in file util.c
2730 In-place upgrade of the supplied SV to a version object.
2732 SV *sv = upg_version(SV *sv, bool qv);
2734 Returns a pointer to the upgraded SV. Set the boolean qv if you want
2735 to force this SV to be interpreted as an "extended" version.
2737 SV* upg_version(SV *ver, bool qv)
2740 Found in file util.c
2745 Version object aware cmp. Both operands must already have been
2746 converted into version objects.
2748 int vcmp(SV *lhv, SV *rhv)
2751 Found in file util.c
2756 Accepts a version object and returns the normalized string
2757 representation. Call like:
2761 NOTE: you can pass either the object directly or the SV
2762 contained within the RV.
2767 Found in file util.c
2772 Accepts a version object and returns the normalized floating
2773 point representation. Call like:
2777 NOTE: you can pass either the object directly or the SV
2778 contained within the RV.
2783 Found in file util.c
2788 In order to maintain maximum compatibility with earlier versions
2789 of Perl, this function will return either the floating point
2790 notation or the multiple dotted notation, depending on whether
2791 the original version contained 1 or more dots, respectively
2793 SV* vstringify(SV *vs)
2796 Found in file util.c
2801 Validates that the SV contains a valid version object.
2803 bool vverify(SV *vobj);
2805 Note that it only confirms the bare minimum structure (so as not to get
2806 confused by derived classes which may contain additional hash entries):
2808 bool vverify(SV *vs)
2811 Found in file util.c
2816 =head1 MRO Functions
2820 =item mro_get_linear_isa
2821 X<mro_get_linear_isa>
2823 Returns either C<mro_get_linear_isa_c3> or
2824 C<mro_get_linear_isa_dfs> for the given stash,
2825 dependant upon which MRO is in effect
2826 for that stash. The return value is a
2829 You are responsible for C<SvREFCNT_inc()> on the
2830 return value if you plan to store it anywhere
2831 semi-permanently (otherwise it might be deleted
2832 out from under you the next time the cache is
2835 AV* mro_get_linear_isa(HV* stash)
2840 =item mro_method_changed_in
2841 X<mro_method_changed_in>
2843 Invalidates method caching on any child classes
2844 of the given stash, so that they might notice
2845 the changes in this one.
2847 Ideally, all instances of C<PL_sub_generation++> in
2848 perl source outside of C<mro.c> should be
2849 replaced by calls to this.
2851 Perl automatically handles most of the common
2852 ways a method might be redefined. However, there
2853 are a few ways you could change a method in a stash
2854 without the cache code noticing, in which case you
2855 need to call this method afterwards:
2857 1) Directly manipulating the stash HV entries from
2860 2) Assigning a reference to a readonly scalar
2861 constant into a stash entry in order to create
2862 a constant subroutine (like constant.pm
2865 This same method is available from pure perl
2866 via, C<mro::method_changed_in(classname)>.
2868 void mro_method_changed_in(HV* stash)
2876 =head1 Multicall Functions
2883 Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2893 Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2903 Closing bracket for a lightweight callback.
2904 See L<perlcall/Lightweight Callbacks>.
2911 =item PUSH_MULTICALL
2914 Opening bracket for a lightweight callback.
2915 See L<perlcall/Lightweight Callbacks>.
2925 =head1 Numeric functions
2932 converts a string representing a binary number to numeric form.
2934 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2935 conversion flags, and I<result> should be NULL or a pointer to an NV.
2936 The scan stops at the end of the string, or the first invalid character.
2937 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2938 invalid character will also trigger a warning.
2939 On return I<*len> is set to the length of the scanned string,
2940 and I<*flags> gives output flags.
2942 If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
2943 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2944 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2945 and writes the value to I<*result> (or the value is discarded if I<result>
2948 The binary number may optionally be prefixed with "0b" or "b" unless
2949 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2950 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2951 number may use '_' characters to separate digits.
2953 UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
2956 Found in file numeric.c
2961 converts a string representing a hex number to numeric form.
2963 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2964 conversion flags, and I<result> should be NULL or a pointer to an NV.
2965 The scan stops at the end of the string, or the first invalid character.
2966 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2967 invalid character will also trigger a warning.
2968 On return I<*len> is set to the length of the scanned string,
2969 and I<*flags> gives output flags.
2971 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2972 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2973 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2974 and writes the value to I<*result> (or the value is discarded if I<result>
2977 The hex number may optionally be prefixed with "0x" or "x" unless
2978 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2979 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2980 number may use '_' characters to separate digits.
2982 UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
2985 Found in file numeric.c
2990 Recognise (or not) a number. The type of the number is returned
2991 (0 if unrecognised), otherwise it is a bit-ORed combination of
2992 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2993 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2995 If the value of the number can fit an in UV, it is returned in the *valuep
2996 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2997 will never be set unless *valuep is valid, but *valuep may have been assigned
2998 to during processing even though IS_NUMBER_IN_UV is not set on return.
2999 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
3000 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
3002 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
3003 seen (in which case *valuep gives the true value truncated to an integer), and
3004 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
3005 absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
3006 number is larger than a UV.
3008 int grok_number(const char *pv, STRLEN len, UV *valuep)
3011 Found in file numeric.c
3013 =item grok_numeric_radix
3014 X<grok_numeric_radix>
3016 Scan and skip for a numeric decimal separator (radix).
3018 bool grok_numeric_radix(const char **sp, const char *send)
3021 Found in file numeric.c
3026 converts a string representing an octal number to numeric form.
3028 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
3029 conversion flags, and I<result> should be NULL or a pointer to an NV.
3030 The scan stops at the end of the string, or the first invalid character.
3031 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
3032 invalid character will also trigger a warning.
3033 On return I<*len> is set to the length of the scanned string,
3034 and I<*flags> gives output flags.
3036 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
3037 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
3038 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
3039 and writes the value to I<*result> (or the value is discarded if I<result>
3042 If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
3043 number may use '_' characters to separate digits.
3045 UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
3048 Found in file numeric.c
3053 Return a non-zero integer if the sign bit on an NV is set, and 0 if
3056 If Configure detects this system has a signbit() that will work with
3057 our NVs, then we just use it via the #define in perl.h. Otherwise,
3058 fall back on this implementation. As a first pass, this gets everything
3059 right except -0.0. Alas, catching -0.0 is the main use for this function,
3060 so this is not too helpful yet. Still, at least we have the scaffolding
3061 in place to support other systems, should that prove useful.
3064 Configure notes: This function is called 'Perl_signbit' instead of a
3065 plain 'signbit' because it is easy to imagine a system having a signbit()
3066 function or macro that doesn't happen to work with our particular choice
3067 of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
3068 the standard system headers to be happy. Also, this is a no-context
3069 function (no pTHX_) because Perl_signbit() is usually re-#defined in
3070 perl.h as a simple macro call to the system's signbit().
3071 Users should just always call Perl_signbit().
3073 NOTE: this function is experimental and may change or be
3074 removed without notice.
3076 int Perl_signbit(NV f)
3079 Found in file numeric.c
3084 For backwards compatibility. Use C<grok_bin> instead.
3086 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
3089 Found in file numeric.c
3094 For backwards compatibility. Use C<grok_hex> instead.
3096 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
3099 Found in file numeric.c
3104 For backwards compatibility. Use C<grok_oct> instead.
3106 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
3109 Found in file numeric.c
3114 =head1 Optree Manipulation Functions
3121 If C<cv> is a constant sub eligible for inlining. returns the constant
3122 value returned by the sub. Otherwise, returns NULL.
3124 Constant subs can be created with C<newCONSTSUB> or as described in
3125 L<perlsub/"Constant Functions">.
3127 SV* cv_const_sv(const CV *const cv)
3135 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
3136 eligible for inlining at compile-time.
3138 Passing NULL for SV creates a constant sub equivalent to C<sub BAR () {}>,
3139 which won't be called if used as a destructor, but will suppress the overhead
3140 of a call to C<AUTOLOAD>. (This form, however, isn't eligible for inlining at
3143 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
3151 Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
3152 static storage, as it is used directly as CvFILE(), without a copy being made.
3160 =head1 Pad Data Structures
3167 Get the value at offset po in the current pad.
3168 Use macro PAD_SV instead of calling this function directly.
3170 SV* pad_sv(PADOFFSET po)
3178 =head1 Per-Interpreter Variables
3185 C<PL_modglobal> is a general purpose, interpreter global HV for use by
3186 extensions that need to keep information on a per-interpreter basis.
3187 In a pinch, it can also be used as a symbol table for extensions
3188 to share data among each other. It is a good idea to use keys
3189 prefixed by the package name of the extension that owns the data.
3194 Found in file intrpvar.h
3199 A convenience variable which is typically used with C<SvPV> when one
3200 doesn't care about the length of the string. It is usually more efficient
3201 to either declare a local variable and use that instead or to use the
3202 C<SvPV_nolen> macro.
3207 Found in file intrpvar.h
3212 This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
3218 Found in file intrpvar.h
3223 This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
3228 Found in file intrpvar.h
3233 This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
3239 Found in file intrpvar.h
3244 =head1 REGEXP Functions
3251 Convenience macro to get the REGEXP from a SV. This is approximately
3252 equivalent to the following snippet:
3257 (tmpsv = (SV*)SvRV(sv)) &&
3258 SvTYPE(tmpsv) == SVt_PVMG &&
3259 (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
3261 return (REGEXP *)tmpmg->mg_obj;
3264 NULL will be returned if a REGEXP* is not found.
3266 REGEXP * SvRX(SV *sv)
3269 Found in file regexp.h
3274 Returns a boolean indicating whether the SV contains qr magic
3277 If you want to do something with the REGEXP* later use SvRX instead
3283 Found in file regexp.h
3288 =head1 Simple Exception Handling Macros
3295 Set up necessary local variables for exception handling.
3296 See L<perlguts/"Exception Handling">.
3301 Found in file XSUB.h
3306 Introduces a catch block. See L<perlguts/"Exception Handling">.
3309 Found in file XSUB.h
3314 Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
3319 Found in file XSUB.h
3324 Ends a try block. See L<perlguts/"Exception Handling">.
3327 Found in file XSUB.h
3329 =item XCPT_TRY_START
3332 Starts a try block. See L<perlguts/"Exception Handling">.
3335 Found in file XSUB.h
3340 =head1 Stack Manipulation Macros
3347 Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
3358 Saves the original stack mark for the XSUB. See C<ORIGMARK>.
3368 Declares a local copy of perl's stack pointer for the XSUB, available via
3369 the C<SP> macro. See C<SP>.
3379 Used to extend the argument stack for an XSUB's return values. Once
3380 used, guarantees that there is room for at least C<nitems> to be pushed
3383 void EXTEND(SP, int nitems)
3391 Stack marker variable for the XSUB. See C<dMARK>.
3399 Push an integer onto the stack. The stack must have room for this element.
3400 Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi> and C<XPUSHi>.
3410 Push a double onto the stack. The stack must have room for this element.
3411 Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn> and C<XPUSHn>.
3421 Push a string onto the stack. The stack must have room for this element.
3422 The C<len> indicates the length of the string. Does not use C<TARG>.
3423 See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
3425 void mPUSHp(char* str, STRLEN len)
3433 Push an SV onto the stack and mortalizes the SV. The stack must have room
3434 for this element. Does not use C<TARG>. See also C<PUSHs> and C<mXPUSHs>.
3444 Push an unsigned integer onto the stack. The stack must have room for this
3445 element. Does not use C<TARG>. See also C<PUSHu>, C<mXPUSHu> and C<XPUSHu>.
3455 Push an integer onto the stack, extending the stack if necessary.
3456 Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and C<PUSHi>.
3466 Push a double onto the stack, extending the stack if necessary.
3467 Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and C<PUSHn>.
3477 Push a string onto the stack, extending the stack if necessary. The C<len>
3478 indicates the length of the string. Does not use C<TARG>. See also C<XPUSHp>,
3479 C<mPUSHp> and C<PUSHp>.
3481 void mXPUSHp(char* str, STRLEN len)
3489 Push an SV onto the stack, extending the stack if necessary and mortalizes
3490 the SV. Does not use C<TARG>. See also C<XPUSHs> and C<mPUSHs>.
3492 void mXPUSHs(SV* sv)
3500 Push an unsigned integer onto the stack, extending the stack if necessary.
3501 Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu> and C<PUSHu>.
3511 The original stack mark for the XSUB. See C<dORIGMARK>.
3519 Pops an integer off the stack.
3529 Pops a long off the stack.
3539 Pops a double off the stack.
3549 Pops a string off the stack. Deprecated. New code should use POPpx.
3559 Pops a string off the stack which must consist of bytes i.e. characters < 256.
3569 Pops a string off the stack.
3579 Pops an SV off the stack.
3589 Push an integer onto the stack. The stack must have room for this element.
3590 Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3591 called to declare it. Do not call multiple C<TARG>-oriented macros to
3592 return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
3603 Opening bracket for arguments on a callback. See C<PUTBACK> and
3614 Push a new mortal SV onto the stack. The stack must have room for this
3615 element. Does not use C<TARG>. See also C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3625 Push a double onto the stack. The stack must have room for this element.
3626 Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3627 called to declare it. Do not call multiple C<TARG>-oriented macros to
3628 return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
3639 Push a string onto the stack. The stack must have room for this element.
3640 The C<len> indicates the length of the string. Handles 'set' magic. Uses
3641 C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
3642 call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3643 C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
3645 void PUSHp(char* str, STRLEN len)
3653 Push an SV onto the stack. The stack must have room for this element.
3654 Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
3655 C<XPUSHs> and C<XPUSHmortal>.
3665 Push an unsigned integer onto the stack. The stack must have room for this
3666 element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3667 should be called to declare it. Do not call multiple C<TARG>-oriented
3668 macros to return lists from XSUB's - see C<mPUSHu> instead. See also
3669 C<XPUSHu> and C<mXPUSHu>.
3679 Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
3680 See C<PUSHMARK> and L<perlcall> for other uses.
3690 Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
3699 Refetch the stack pointer. Used after a callback. See L<perlcall>.
3709 Push an integer onto the stack, extending the stack if necessary. Handles
3710 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3711 declare it. Do not call multiple C<TARG>-oriented macros to return lists
3712 from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
3722 Push a new mortal SV onto the stack, extending the stack if necessary.
3723 Does not use C<TARG>. See also C<XPUSHs>, C<PUSHmortal> and C<PUSHs>.
3733 Push a double onto the stack, extending the stack if necessary. Handles
3734 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3735 declare it. Do not call multiple C<TARG>-oriented macros to return lists
3736 from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
3746 Push a string onto the stack, extending the stack if necessary. The C<len>
3747 indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
3748 C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
3749 multiple C<TARG>-oriented macros to return lists from XSUB's - see
3750 C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
3752 void XPUSHp(char* str, STRLEN len)
3760 Push an SV onto the stack, extending the stack if necessary. Does not
3761 handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
3762 C<PUSHs> and C<PUSHmortal>.
3772 Push an unsigned integer onto the stack, extending the stack if necessary.
3773 Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3774 called to declare it. Do not call multiple C<TARG>-oriented macros to
3775 return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
3786 Return from XSUB, indicating number of items on the stack. This is usually
3787 handled by C<xsubpp>.
3789 void XSRETURN(int nitems)
3792 Found in file XSUB.h
3794 =item XSRETURN_EMPTY
3797 Return an empty list from an XSUB immediately.
3802 Found in file XSUB.h
3807 Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3809 void XSRETURN_IV(IV iv)
3812 Found in file XSUB.h
3817 Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
3822 Found in file XSUB.h
3827 Return a double from an XSUB immediately. Uses C<XST_mNV>.
3829 void XSRETURN_NV(NV nv)
3832 Found in file XSUB.h
3837 Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3839 void XSRETURN_PV(char* str)
3842 Found in file XSUB.h
3844 =item XSRETURN_UNDEF
3847 Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3852 Found in file XSUB.h
3857 Return an integer from an XSUB immediately. Uses C<XST_mUV>.
3859 void XSRETURN_UV(IV uv)
3862 Found in file XSUB.h
3867 Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3872 Found in file XSUB.h
3877 Place an integer into the specified position C<pos> on the stack. The
3878 value is stored in a new mortal SV.
3880 void XST_mIV(int pos, IV iv)
3883 Found in file XSUB.h
3888 Place C<&PL_sv_no> into the specified position C<pos> on the
3891 void XST_mNO(int pos)
3894 Found in file XSUB.h
3899 Place a double into the specified position C<pos> on the stack. The value
3900 is stored in a new mortal SV.
3902 void XST_mNV(int pos, NV nv)
3905 Found in file XSUB.h
3910 Place a copy of a string into the specified position C<pos> on the stack.
3911 The value is stored in a new mortal SV.
3913 void XST_mPV(int pos, char* str)
3916 Found in file XSUB.h
3921 Place C<&PL_sv_undef> into the specified position C<pos> on the
3924 void XST_mUNDEF(int pos)
3927 Found in file XSUB.h
3932 Place C<&PL_sv_yes> into the specified position C<pos> on the
3935 void XST_mYES(int pos)
3938 Found in file XSUB.h
3950 An enum of flags for Perl types. These are found in the file B<sv.h>
3951 in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
3959 Integer type flag for scalars. See C<svtype>.
3967 Double type flag for scalars. See C<svtype>.
3975 Pointer type flag for scalars. See C<svtype>.
3983 Type flag for arrays. See C<svtype>.
3991 Type flag for code refs. See C<svtype>.
3999 Type flag for hashes. See C<svtype>.
4007 Type flag for blessed scalars. See C<svtype>.
4015 =head1 SV Manipulation Functions
4019 =item croak_xs_usage
4022 A specialised variant of C<croak()> for emitting the usage message for xsubs
4024 croak_xs_usage(cv, "eee_yow");
4026 works out the package name and subroutine name from C<cv>, and then calls
4027 C<croak()>. Hence if C<cv> is C<&ouch::awk>, it would call C<croak> as:
4029 Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow");
4031 void croak_xs_usage(const CV *const cv, const char *const params)
4034 Found in file universal.c
4039 Returns the SV of the specified Perl scalar. C<flags> are passed to
4040 C<gv_fetchpv>. If C<GV_ADD> is set and the
4041 Perl variable does not exist then it will be created. If C<flags> is zero
4042 and the variable does not exist then NULL is returned.
4044 NOTE: the perl_ form of this function is deprecated.
4046 SV* get_sv(const char *name, I32 flags)
4049 Found in file perl.c
4054 Creates an RV wrapper for an SV. The reference count for the original SV is
4057 SV* newRV_inc(SV* sv)
4065 Creates a new SV and copies a string into it. If utf8 is true, calls
4066 C<SvUTF8_on> on the new SV. Implemented as a wrapper around C<newSVpvn_flags>.
4068 SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8)
4076 Returns the length of the string which is in the SV. See C<SvLEN>.
4078 STRLEN SvCUR(SV* sv)
4086 Set the current length of the string which is in the SV. See C<SvCUR>
4089 void SvCUR_set(SV* sv, STRLEN len)
4097 Returns a pointer to the last character in the string which is in the SV.
4098 See C<SvCUR>. Access the character as *(SvEND(sv)).
4108 Returns true if the SV has get magic or overloading. If either is true then
4109 the scalar is active data, and has the potential to return a new value every
4110 time it is accessed. Hence you must be careful to only read it once per user
4111 logical operation and work with that returned value. If neither is true then
4112 the scalar's value cannot change unless written to.
4114 char* SvGAMAGIC(SV* sv)
4122 Expands the character buffer in the SV so that it has room for the
4123 indicated number of bytes (remember to reserve space for an extra trailing
4124 NUL character). Calls C<sv_grow> to perform the expansion if necessary.
4125 Returns a pointer to the character buffer.
4127 char * SvGROW(SV* sv, STRLEN len)
4135 Returns a U32 value indicating whether the SV contains an integer.
4145 Returns a U32 value indicating whether the SV contains an integer. Checks
4146 the B<private> setting. Use C<SvIOK> instead.
4156 Returns a boolean indicating whether the SV contains a signed integer.
4158 bool SvIOK_notUV(SV* sv)
4166 Unsets the IV status of an SV.
4168 void SvIOK_off(SV* sv)
4176 Tells an SV that it is an integer.
4178 void SvIOK_on(SV* sv)
4186 Tells an SV that it is an integer and disables all other OK bits.
4188 void SvIOK_only(SV* sv)
4196 Tells and SV that it is an unsigned integer and disables all other OK bits.
4198 void SvIOK_only_UV(SV* sv)
4206 Returns a boolean indicating whether the SV contains an unsigned integer.
4208 bool SvIOK_UV(SV* sv)
4216 Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
4217 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
4220 bool SvIsCOW(SV* sv)
4225 =item SvIsCOW_shared_hash
4226 X<SvIsCOW_shared_hash>
4228 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
4231 bool SvIsCOW_shared_hash(SV* sv)
4239 Coerces the given SV to an integer and returns it. See C<SvIVx> for a
4240 version which guarantees to evaluate sv only once.
4250 Returns the raw value in the SV's IV slot, without checks or conversions.
4251 Only use when you are sure SvIOK is true. See also C<SvIV()>.
4261 Coerces the given SV to an integer and returns it. Guarantees to evaluate
4262 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4263 otherwise use the more efficient C<SvIV>.
4273 Like C<SvIV> but doesn't process magic.
4275 IV SvIV_nomg(SV* sv)
4283 Set the value of the IV pointer in sv to val. It is possible to perform
4284 the same function of this macro with an lvalue assignment to C<SvIVX>.
4285 With future Perls, however, it will be more efficient to use
4286 C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
4288 void SvIV_set(SV* sv, IV val)
4296 Returns the size of the string buffer in the SV, not including any part
4297 attributable to C<SvOOK>. See C<SvCUR>.
4299 STRLEN SvLEN(SV* sv)
4307 Set the actual length of the string which is in the SV. See C<SvIV_set>.
4309 void SvLEN_set(SV* sv, STRLEN len)
4317 Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>.
4319 void SvMAGIC_set(SV* sv, MAGIC* val)
4327 Returns a U32 value indicating whether the SV contains a number, integer or
4338 Returns a U32 value indicating whether the SV contains a number, integer or
4339 double. Checks the B<private> setting. Use C<SvNIOK> instead.
4349 Unsets the NV/IV status of an SV.
4351 void SvNIOK_off(SV* sv)
4359 Returns a U32 value indicating whether the SV contains a double.
4369 Returns a U32 value indicating whether the SV contains a double. Checks the
4370 B<private> setting. Use C<SvNOK> instead.
4380 Unsets the NV status of an SV.
4382 void SvNOK_off(SV* sv)
4390 Tells an SV that it is a double.
4392 void SvNOK_on(SV* sv)
4400 Tells an SV that it is a double and disables all other OK bits.
4402 void SvNOK_only(SV* sv)
4410 Coerce the given SV to a double and return it. See C<SvNVx> for a version
4411 which guarantees to evaluate sv only once.
4421 Returns the raw value in the SV's NV slot, without checks or conversions.
4422 Only use when you are sure SvNOK is true. See also C<SvNV()>.
4432 Coerces the given SV to a double and returns it. Guarantees to evaluate
4433 C<sv> only once. Only use this if C<sv> is an expression with side effects,
4434 otherwise use the more efficient C<SvNV>.
4444 Set the value of the NV pointer in sv to val. See C<SvIV_set>.
4446 void SvNV_set(SV* sv, NV val)
4454 Returns a U32 value indicating whether the value is an SV. It also tells
4455 whether the value is defined or not.
4465 Returns a U32 indicating whether the pointer to the string buffer is offset.
4466 This hack is used internally to speed up removal of characters from the
4467 beginning of a SvPV. When SvOOK is true, then the start of the
4468 allocated string buffer is actually C<SvOOK_offset()> bytes before SvPVX.
4469 This offset used to be stored in SvIVX, but is now stored within the spare
4480 Reads into I<len> the offset from SvPVX back to the true start of the
4481 allocated buffer, which will be non-zero if C<sv_chop> has been used to
4482 efficiently remove characters from start of the buffer. Implemented as a
4483 macro, which takes the address of I<len>, which must be of type C<STRLEN>.
4484 Evaluates I<sv> more than once. Sets I<len> to 0 if C<SvOOK(sv)> is false.
4486 void SvOOK_offset(NN SV*sv, STRLEN len)
4494 Returns a U32 value indicating whether the SV contains a character
4505 Returns a U32 value indicating whether the SV contains a character string.
4506 Checks the B<private> setting. Use C<SvPOK> instead.
4516 Unsets the PV status of an SV.
4518 void SvPOK_off(SV* sv)
4526 Tells an SV that it is a string.
4528 void SvPOK_on(SV* sv)
4536 Tells an SV that it is a string and disables all other OK bits.
4537 Will also turn off the UTF-8 status.
4539 void SvPOK_only(SV* sv)
4544 =item SvPOK_only_UTF8
4547 Tells an SV that it is a string and disables all other OK bits,
4548 and leaves the UTF-8 status as it was.
4550 void SvPOK_only_UTF8(SV* sv)
4558 Returns a pointer to the string in the SV, or a stringified form of
4559 the SV if the SV does not contain a string. The SV may cache the
4560 stringified version becoming C<SvPOK>. Handles 'get' magic. See also
4561 C<SvPVx> for a version which guarantees to evaluate sv only once.
4563 char* SvPV(SV* sv, STRLEN len)
4571 Like C<SvPV>, but converts sv to byte representation first if necessary.
4573 char* SvPVbyte(SV* sv, STRLEN len)
4581 Like C<SvPV>, but converts sv to byte representation first if necessary.
4582 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
4585 char* SvPVbytex(SV* sv, STRLEN len)
4590 =item SvPVbytex_force
4593 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4594 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
4597 char* SvPVbytex_force(SV* sv, STRLEN len)
4602 =item SvPVbyte_force
4605 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4607 char* SvPVbyte_force(SV* sv, STRLEN len)
4612 =item SvPVbyte_nolen
4615 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
4617 char* SvPVbyte_nolen(SV* sv)
4625 Like C<SvPV>, but converts sv to utf8 first if necessary.
4627 char* SvPVutf8(SV* sv, STRLEN len)
4635 Like C<SvPV>, but converts sv to utf8 first if necessary.
4636 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
4639 char* SvPVutf8x(SV* sv, STRLEN len)
4644 =item SvPVutf8x_force
4647 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4648 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
4651 char* SvPVutf8x_force(SV* sv, STRLEN len)
4656 =item SvPVutf8_force
4659 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4661 char* SvPVutf8_force(SV* sv, STRLEN len)
4666 =item SvPVutf8_nolen
4669 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
4671 char* SvPVutf8_nolen(SV* sv)
4679 Returns a pointer to the physical string in the SV. The SV must contain a
4690 A version of C<SvPV> which guarantees to evaluate C<sv> only once.
4691 Only use this if C<sv> is an expression with side effects, otherwise use the
4692 more efficient C<SvPVX>.
4694 char* SvPVx(SV* sv, STRLEN len)
4702 Like C<SvPV> but will force the SV into containing just a string
4703 (C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
4706 char* SvPV_force(SV* sv, STRLEN len)
4711 =item SvPV_force_nomg
4714 Like C<SvPV> but will force the SV into containing just a string
4715 (C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
4716 directly. Doesn't process magic.
4718 char* SvPV_force_nomg(SV* sv, STRLEN len)
4726 Returns a pointer to the string in the SV, or a stringified form of
4727 the SV if the SV does not contain a string. The SV may cache the
4728 stringified form becoming C<SvPOK>. Handles 'get' magic.
4730 char* SvPV_nolen(SV* sv)
4738 Like C<SvPV> but doesn't process magic.
4740 char* SvPV_nomg(SV* sv, STRLEN len)
4748 Set the value of the PV pointer in sv to val. See C<SvIV_set>.
4750 void SvPV_set(SV* sv, char* val)
4758 Returns the value of the object's reference count.
4760 U32 SvREFCNT(SV* sv)
4768 Decrements the reference count of the given SV.
4770 void SvREFCNT_dec(SV* sv)
4778 Increments the reference count of the given SV.
4780 All of the following SvREFCNT_inc* macros are optimized versions of
4781 SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
4783 SV* SvREFCNT_inc(SV* sv)
4788 =item SvREFCNT_inc_NN
4791 Same as SvREFCNT_inc, but can only be used if you know I<sv>
4792 is not NULL. Since we don't have to check the NULLness, it's faster
4795 SV* SvREFCNT_inc_NN(SV* sv)
4800 =item SvREFCNT_inc_simple
4801 X<SvREFCNT_inc_simple>
4803 Same as SvREFCNT_inc, but can only be used with expressions without side
4804 effects. Since we don't have to store a temporary value, it's faster.
4806 SV* SvREFCNT_inc_simple(SV* sv)
4811 =item SvREFCNT_inc_simple_NN
4812 X<SvREFCNT_inc_simple_NN>
4814 Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
4815 is not NULL. Since we don't have to check the NULLness, it's faster
4818 SV* SvREFCNT_inc_simple_NN(SV* sv)
4823 =item SvREFCNT_inc_simple_void
4824 X<SvREFCNT_inc_simple_void>
4826 Same as SvREFCNT_inc_simple, but can only be used if you don't need the
4827 return value. The macro doesn't need to return a meaningful value.
4829 void SvREFCNT_inc_simple_void(SV* sv)
4834 =item SvREFCNT_inc_simple_void_NN
4835 X<SvREFCNT_inc_simple_void_NN>
4837 Same as SvREFCNT_inc, but can only be used if you don't need the return
4838 value, and you know that I<sv> is not NULL. The macro doesn't need
4839 to return a meaningful value, or check for NULLness, so it's smaller
4842 void SvREFCNT_inc_simple_void_NN(SV* sv)
4847 =item SvREFCNT_inc_void
4848 X<SvREFCNT_inc_void>
4850 Same as SvREFCNT_inc, but can only be used if you don't need the
4851 return value. The macro doesn't need to return a meaningful value.
4853 void SvREFCNT_inc_void(SV* sv)
4858 =item SvREFCNT_inc_void_NN
4859 X<SvREFCNT_inc_void_NN>
4861 Same as SvREFCNT_inc, but can only be used if you don't need the return
4862 value, and you know that I<sv> is not NULL. The macro doesn't need
4863 to return a meaningful value, or check for NULLness, so it's smaller
4866 void SvREFCNT_inc_void_NN(SV* sv)
4874 Tests if the SV is an RV.
4884 Unsets the RV status of an SV.
4886 void SvROK_off(SV* sv)
4894 Tells an SV that it is an RV.
4896 void SvROK_on(SV* sv)
4904 Dereferences an RV to return the SV.
4914 Set the value of the RV pointer in sv to val. See C<SvIV_set>.
4916 void SvRV_set(SV* sv, SV* val)
4924 Returns the stash of the SV.
4934 Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
4936 void SvSTASH_set(SV* sv, HV* val)
4944 Taints an SV if tainting is enabled.
4946 void SvTAINT(SV* sv)
4954 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4957 bool SvTAINTED(SV* sv)
4965 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
4966 some of Perl's fundamental security features. XS module authors should not
4967 use this function unless they fully understand all the implications of
4968 unconditionally untainting the value. Untainting should be done in the
4969 standard perl fashion, via a carefully crafted regexp, rather than directly
4970 untainting variables.
4972 void SvTAINTED_off(SV* sv)
4980 Marks an SV as tainted if tainting is enabled.
4982 void SvTAINTED_on(SV* sv)
4990 Returns a boolean indicating whether Perl would evaluate the SV as true or
4991 false, defined or undefined. Does not handle 'get' magic.
5001 Returns the type of the SV. See C<svtype>.
5003 svtype SvTYPE(SV* sv)
5011 Returns a boolean indicating whether the SV contains an unsigned integer.
5021 Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
5022 perform the upgrade if necessary. See C<svtype>.
5024 void SvUPGRADE(SV* sv, svtype type)
5032 Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
5033 Call this after SvPV() in case any call to string overloading updates the
5044 Unsets the UTF-8 status of an SV.
5046 void SvUTF8_off(SV *sv)
5054 Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
5055 Do not use frivolously.
5057 void SvUTF8_on(SV *sv)
5065 Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
5066 for a version which guarantees to evaluate sv only once.
5076 Returns the raw value in the SV's UV slot, without checks or conversions.
5077 Only use when you are sure SvIOK is true. See also C<SvUV()>.
5087 Coerces the given SV to an unsigned integer and returns it. Guarantees to
5088 C<sv> only once. Only use this if C<sv> is an expression with side effects,
5089 otherwise use the more efficient C<SvUV>.
5099 Like C<SvUV> but doesn't process magic.
5101 UV SvUV_nomg(SV* sv)
5109 Set the value of the UV pointer in sv to val. See C<SvIV_set>.
5111 void SvUV_set(SV* sv, UV val)
5119 Returns a boolean indicating whether the SV contains a v-string.
5126 =item sv_catpvn_nomg
5129 Like C<sv_catpvn> but doesn't process magic.
5131 void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
5139 Like C<sv_catsv> but doesn't process magic.
5141 void sv_catsv_nomg(SV* dsv, SV* ssv)
5146 =item sv_derived_from
5149 Returns a boolean indicating whether the SV is derived from the specified class
5150 I<at the C level>. To check derivation at the Perl level, call C<isa()> as a
5153 bool sv_derived_from(SV* sv, const char *const name)
5156 Found in file universal.c
5161 Returns a boolean indicating whether the SV performs a specific, named role.
5162 The SV can be a Perl object or the name of a Perl class.
5164 bool sv_does(SV* sv, const char *const name)
5167 Found in file universal.c
5169 =item sv_report_used
5172 Dump the contents of all SVs not yet freed. (Debugging aid).
5174 void sv_report_used()
5182 Like C<sv_setsv> but doesn't process magic.
5184 void sv_setsv_nomg(SV* dsv, SV* ssv)
5189 =item sv_utf8_upgrade_nomg
5190 X<sv_utf8_upgrade_nomg>
5192 Like sv_utf8_upgrade, but doesn't do magic on C<sv>
5194 STRLEN sv_utf8_upgrade_nomg(NN SV *sv)
5202 =head1 SV-Body Allocation
5206 =item looks_like_number
5207 X<looks_like_number>
5209 Test if the content of an SV looks like a number (or is a number).
5210 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
5211 non-numeric warning), even if your atof() doesn't grok them.
5213 I32 looks_like_number(SV *const sv)
5221 Creates an RV wrapper for an SV. The reference count for the original
5222 SV is B<not> incremented.
5224 SV* newRV_noinc(SV *const sv)
5232 Creates a new SV. A non-zero C<len> parameter indicates the number of
5233 bytes of preallocated string space the SV should have. An extra byte for a
5234 trailing NUL is also reserved. (SvPOK is not set for the SV even if string
5235 space is allocated.) The reference count for the new SV is set to 1.
5237 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
5238 parameter, I<x>, a debug aid which allowed callers to identify themselves.
5239 This aid has been superseded by a new build option, PERL_MEM_LOG (see
5240 L<perlhack/PERL_MEM_LOG>). The older API is still there for use in XS
5241 modules supporting older perls.
5243 SV* newSV(const STRLEN len)
5251 Creates a new SV from the hash key structure. It will generate scalars that
5252 point to the shared string table where possible. Returns a new (undefined)
5253 SV if the hek is NULL.
5255 SV* newSVhek(const HEK *const hek)
5263 Creates a new SV and copies an integer into it. The reference count for the
5266 SV* newSViv(const IV i)
5274 Creates a new SV and copies a floating point value into it.
5275 The reference count for the SV is set to 1.
5277 SV* newSVnv(const NV n)
5285 Creates a new SV and copies a string into it. The reference count for the
5286 SV is set to 1. If C<len> is zero, Perl will compute the length using
5287 strlen(). For efficiency, consider using C<newSVpvn> instead.
5289 SV* newSVpv(const char *const s, const STRLEN len)
5297 Creates a new SV and initializes it with the string formatted like
5300 SV* newSVpvf(const char *const pat, ...)
5308 Creates a new SV and copies a string into it. The reference count for the
5309 SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
5310 string. You are responsible for ensuring that the source string is at least
5311 C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
5313 SV* newSVpvn(const char *const s, const STRLEN len)
5318 =item newSVpvn_flags
5321 Creates a new SV and copies a string into it. The reference count for the
5322 SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
5323 string. You are responsible for ensuring that the source string is at least
5324 C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
5325 Currently the only flag bits accepted are C<SVf_UTF8> and C<SVs_TEMP>.
5326 If C<SVs_TEMP> is set, then C<sv2mortal()> is called on the result before
5327 returning. If C<SVf_UTF8> is set, then it will be set on the new SV.
5328 C<newSVpvn_utf8()> is a convenience wrapper for this function, defined as
5330 #define newSVpvn_utf8(s, len, u) \
5331 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
5333 SV* newSVpvn_flags(const char *const s, const STRLEN len, const U32 flags)
5338 =item newSVpvn_share
5341 Creates a new SV with its SvPVX_const pointing to a shared string in the string
5342 table. If the string does not already exist in the table, it is created
5343 first. Turns on READONLY and FAKE. If the C<hash> parameter is non-zero, that
5344 value is used; otherwise the hash is computed. The string's hash can be later
5345 be retrieved from the SV with the C<SvSHARED_HASH()> macro. The idea here is
5346 that as the string table is used for shared hash keys these strings will have
5347 SvPVX_const == HeKEY and hash lookup will avoid string compare.
5349 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
5357 Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
5359 SV* newSVpvs(const char* s)
5362 Found in file handy.h
5364 =item newSVpvs_flags
5367 Like C<newSVpvn_flags>, but takes a literal string instead of a string/length
5370 SV* newSVpvs_flags(const char* s, U32 flags)
5373 Found in file handy.h
5375 =item newSVpvs_share
5378 Like C<newSVpvn_share>, but takes a literal string instead of a string/length
5379 pair and omits the hash parameter.
5381 SV* newSVpvs_share(const char* s)
5384 Found in file handy.h
5389 Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
5390 it will be upgraded to one. If C<classname> is non-null then the new SV will
5391 be blessed in the specified package. The new SV is returned and its
5392 reference count is 1.
5394 SV* newSVrv(SV *const rv, const char *const classname)
5402 Creates a new SV which is an exact duplicate of the original SV.
5405 SV* newSVsv(SV *const old)
5413 Creates a new SV and copies an unsigned integer into it.
5414 The reference count for the SV is set to 1.
5416 SV* newSVuv(const UV u)
5424 Creates a new SV, of the type specified. The reference count for the new SV
5427 SV* newSV_type(const svtype type)
5435 This function is only called on magical items, and is only used by
5436 sv_true() or its macro equivalent.
5438 bool sv_2bool(SV *const sv)
5446 Using various gambits, try to get a CV from an SV; in addition, try if
5447 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
5448 The flags in C<lref> are passed to sv_fetchsv.
5450 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp, const I32 lref)
5458 Using various gambits, try to get an IO from an SV: the IO slot if its a
5459 GV; or the recursive result if we're an RV; or the IO slot of the symbol
5460 named after the PV if we're a string.
5462 IO* sv_2io(SV *const sv)
5470 Return the integer value of an SV, doing any necessary string
5471 conversion. If flags includes SV_GMAGIC, does an mg_get() first.
5472 Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
5474 IV sv_2iv_flags(SV *const sv, const I32 flags)
5482 Marks an existing SV as mortal. The SV will be destroyed "soon", either
5483 by an explicit call to FREETMPS, or by an implicit call at places such as
5484 statement boundaries. SvTEMP() is turned on which means that the SV's
5485 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
5486 and C<sv_mortalcopy>.
5488 SV* sv_2mortal(SV *const sv)
5496 Return the num value of an SV, doing any necessary string or integer
5497 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
5500 NV sv_2nv(SV *const sv)
5508 Return a pointer to the byte-encoded representation of the SV, and set *lp
5509 to its length. May cause the SV to be downgraded from UTF-8 as a
5512 Usually accessed via the C<SvPVbyte> macro.
5514 char* sv_2pvbyte(SV *const sv, STRLEN *const lp)
5522 Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
5523 to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.
5525 Usually accessed via the C<SvPVutf8> macro.
5527 char* sv_2pvutf8(SV *const sv, STRLEN *const lp)
5535 Returns a pointer to the string value of an SV, and sets *lp to its length.
5536 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
5538 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
5539 usually end up here too.
5541 char* sv_2pv_flags(SV *const sv, STRLEN *const lp, const I32 flags)
5549 Return the unsigned integer value of an SV, doing any necessary string
5550 conversion. If flags includes SV_GMAGIC, does an mg_get() first.
5551 Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
5553 UV sv_2uv_flags(SV *const sv, const I32 flags)
5561 Remove any string offset. You should normally use the C<SvOOK_off> macro
5564 int sv_backoff(SV *const sv)
5572 Blesses an SV into a specified package. The SV must be an RV. The package
5573 must be designated by its stash (see C<gv_stashpv()>). The reference count
5574 of the SV is unaffected.
5576 SV* sv_bless(SV *const sv, HV *const stash)
5584 Concatenates the string onto the end of the string which is in the SV.
5585 If the SV has the UTF-8 status set, then the bytes appended should be
5586 valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
5588 void sv_catpv(SV *const sv, const char* ptr)
5596 Processes its arguments like C<sprintf> and appends the formatted
5597 output to an SV. If the appended data contains "wide" characters
5598 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
5599 and characters >255 formatted with %c), the original SV might get
5600 upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See
5601 C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
5602 valid UTF-8; if the original SV was bytes, the pattern should be too.
5604 void sv_catpvf(SV *const sv, const char *const pat, ...)
5612 Like C<sv_catpvf>, but also handles 'set' magic.
5614 void sv_catpvf_mg(SV *const sv, const char *const pat, ...)
5622 Concatenates the string onto the end of the string which is in the SV. The
5623 C<len> indicates number of bytes to copy. If the SV has the UTF-8
5624 status set, then the bytes appended should be valid UTF-8.
5625 Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
5627 void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
5632 =item sv_catpvn_flags
5635 Concatenates the string onto the end of the string which is in the SV. The
5636 C<len> indicates number of bytes to copy. If the SV has the UTF-8
5637 status set, then the bytes appended should be valid UTF-8.
5638 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
5639 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
5640 in terms of this function.
5642 void sv_catpvn_flags(SV *const dstr, const char *sstr, const STRLEN len, const I32 flags)
5650 Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
5652 void sv_catpvs(SV* sv, const char* s)
5655 Found in file handy.h
5660 Like C<sv_catpv>, but also handles 'set' magic.
5662 void sv_catpv_mg(SV *const sv, const char *const ptr)
5670 Concatenates the string from SV C<ssv> onto the end of the string in
5671 SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
5672 not 'set' magic. See C<sv_catsv_mg>.
5674 void sv_catsv(SV *dstr, SV *sstr)
5679 =item sv_catsv_flags
5682 Concatenates the string from SV C<ssv> onto the end of the string in
5683 SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
5684 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
5685 and C<sv_catsv_nomg> are implemented in terms of this function.
5687 void sv_catsv_flags(SV *const dsv, SV *const ssv, const I32 flags)
5695 Efficient removal of characters from the beginning of the string buffer.
5696 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
5697 the string buffer. The C<ptr> becomes the first character of the adjusted
5698 string. Uses the "OOK hack".
5699 Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
5700 refer to the same chunk of data.
5702 void sv_chop(SV *const sv, const char *const ptr)
5710 Clear an SV: call any destructors, free up any memory used by the body,
5711 and free the body itself. The SV's head is I<not> freed, although
5712 its type is set to all 1's so that it won't inadvertently be assumed
5713 to be live during global destruction etc.
5714 This function should only be called when REFCNT is zero. Most of the time
5715 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
5718 void sv_clear(SV *const sv)
5726 Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
5727 string in C<sv1> is less than, equal to, or greater than the string in
5728 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5729 coerce its args to strings if necessary. See also C<sv_cmp_locale>.
5731 I32 sv_cmp(SV *const sv1, SV *const sv2)
5739 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
5740 'use bytes' aware, handles get magic, and will coerce its args to strings
5741 if necessary. See also C<sv_cmp>.
5743 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
5751 Add Collate Transform magic to an SV if it doesn't already have it.
5753 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
5754 scalar data of the variable, but transformed to such a format that a normal
5755 memory comparison can be used to compare the data according to the locale
5758 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
5766 Copies a stringified representation of the source SV into the
5767 destination SV. Automatically performs any necessary mg_get and
5768 coercion of numeric values into strings. Guaranteed to preserve
5769 UTF8 flag even from overloaded objects. Similar in nature to
5770 sv_2pv[_flags] but operates directly on an SV instead of just the
5771 string. Mostly uses sv_2pv_flags to do its work, except when that
5772 would lose the UTF-8'ness of the PV.
5774 void sv_copypv(SV *const dsv, SV *const ssv)
5782 Auto-decrement of the value in the SV, doing string to numeric conversion
5783 if necessary. Handles 'get' magic.
5785 void sv_dec(SV *const sv)
5793 Returns a boolean indicating whether the strings in the two SVs are
5794 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5795 coerce its args to strings if necessary.
5797 I32 sv_eq(SV* sv1, SV* sv2)
5802 =item sv_force_normal_flags
5803 X<sv_force_normal_flags>
5805 Undo various types of fakery on an SV: if the PV is a shared string, make
5806 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
5807 an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
5808 we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
5809 then a copy-on-write scalar drops its PV buffer (if any) and becomes
5810 SvPOK_off rather than making a copy. (Used where this scalar is about to be
5811 set to some other value.) In addition, the C<flags> parameter gets passed to
5812 C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
5813 with flags set to 0.
5815 void sv_force_normal_flags(SV *const sv, const U32 flags)
5823 Decrement an SV's reference count, and if it drops to zero, call
5824 C<sv_clear> to invoke destructors and free up any memory used by
5825 the body; finally, deallocate the SV's head itself.
5826 Normally called via a wrapper macro C<SvREFCNT_dec>.
5828 void sv_free(SV *const sv)
5836 Get a line from the filehandle and store it into the SV, optionally
5837 appending to the currently-stored string.
5839 char* sv_gets(SV *const sv, PerlIO *const fp, I32 append)
5847 Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
5848 upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
5849 Use the C<SvGROW> wrapper instead.
5851 char* sv_grow(SV *const sv, STRLEN newlen)
5859 Auto-increment of the value in the SV, doing string to numeric conversion
5860 if necessary. Handles 'get' magic.
5862 void sv_inc(SV *const sv)
5870 Inserts a string at the specified offset/length within the SV. Similar to
5871 the Perl substr() function. Handles get magic.
5873 void sv_insert(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen)
5878 =item sv_insert_flags
5881 Same as C<sv_insert>, but the extra C<flags> are passed the C<SvPV_force_flags> that applies to C<bigstr>.
5883 void sv_insert_flags(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen, const U32 flags)
5891 Returns a boolean indicating whether the SV is blessed into the specified
5892 class. This does not check for subtypes; use C<sv_derived_from> to verify
5893 an inheritance relationship.
5895 int sv_isa(SV* sv, const char *const name)
5903 Returns a boolean indicating whether the SV is an RV pointing to a blessed
5904 object. If the SV is not an RV, or if the object is not blessed, then this
5907 int sv_isobject(SV* sv)
5915 Returns the length of the string in the SV. Handles magic and type
5916 coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
5918 STRLEN sv_len(SV *const sv)
5926 Returns the number of characters in the string in an SV, counting wide
5927 UTF-8 bytes as a single character. Handles magic and type coercion.
5929 STRLEN sv_len_utf8(SV *const sv)
5937 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
5938 then adds a new magic item of type C<how> to the head of the magic list.
5940 See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
5941 handling of the C<name> and C<namlen> arguments.
5943 You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
5944 to add more than one instance of the same 'how'.
5946 void sv_magic(SV *const sv, SV *const obj, const int how, const char *const name, const I32 namlen)
5954 Adds magic to an SV, upgrading it if necessary. Applies the
5955 supplied vtable and returns a pointer to the magic added.
5957 Note that C<sv_magicext> will allow things that C<sv_magic> will not.
5958 In particular, you can add magic to SvREADONLY SVs, and add more than
5959 one instance of the same 'how'.
5961 If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
5962 stored, if C<namlen> is zero then C<name> is stored as-is and - as another
5963 special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
5964 to contain an C<SV*> and is stored as-is with its REFCNT incremented.
5966 (This is now used as a subroutine by C<sv_magic>.)
5968 MAGIC * sv_magicext(SV *const sv, SV *const obj, const int how, const MGVTBL *const vtbl, const char *const name, const I32 namlen)
5976 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
5977 The new SV is marked as mortal. It will be destroyed "soon", either by an
5978 explicit call to FREETMPS, or by an implicit call at places such as
5979 statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
5981 SV* sv_mortalcopy(SV *const oldsv)
5989 Creates a new null SV which is mortal. The reference count of the SV is
5990 set to 1. It will be destroyed "soon", either by an explicit call to
5991 FREETMPS, or by an implicit call at places such as statement boundaries.
5992 See also C<sv_mortalcopy> and C<sv_2mortal>.
6002 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
6005 SV* sv_newref(SV *const sv)
6013 Converts the value pointed to by offsetp from a count of bytes from the
6014 start of the string, to a count of the equivalent number of UTF-8 chars.
6015 Handles magic and type coercion.
6017 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
6025 Converts the value pointed to by offsetp from a count of UTF-8 chars from
6026 the start of the string, to a count of the equivalent number of bytes; if
6027 lenp is non-zero, it does the same to lenp, but this time starting from
6028 the offset, rather than from the start of the string. Handles magic and
6031 void sv_pos_u2b(SV *const sv, I32 *const offsetp, I32 *const lenp)
6036 =item sv_pvbyten_force
6039 The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
6041 char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
6049 Get a sensible string out of the SV somehow.
6050 A private implementation of the C<SvPV_force> macro for compilers which
6051 can't cope with complex macro expressions. Always use the macro instead.
6053 char* sv_pvn_force(SV* sv, STRLEN* lp)
6058 =item sv_pvn_force_flags
6059 X<sv_pvn_force_flags>
6061 Get a sensible string out of the SV somehow.
6062 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
6063 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
6064 implemented in terms of this function.
6065 You normally want to use the various wrapper macros instead: see
6066 C<SvPV_force> and C<SvPV_force_nomg>
6068 char* sv_pvn_force_flags(SV *const sv, STRLEN *const lp, const I32 flags)
6073 =item sv_pvutf8n_force
6076 The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
6078 char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
6086 Returns a string describing what the SV is a reference to.
6088 const char* sv_reftype(const SV *const sv, const int ob)
6096 Make the first argument a copy of the second, then delete the original.
6097 The target SV physically takes over ownership of the body of the source SV
6098 and inherits its flags; however, the target keeps any magic it owns,
6099 and any magic in the source is discarded.
6100 Note that this is a rather specialist SV copying operation; most of the
6101 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
6103 void sv_replace(SV *const sv, SV *const nsv)
6111 Underlying implementation for the C<reset> Perl function.
6112 Note that the perl-level function is vaguely deprecated.
6114 void sv_reset(const char* s, HV *const stash)
6122 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
6123 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
6124 push a back-reference to this RV onto the array of backreferences
6125 associated with that magic. If the RV is magical, set magic will be
6126 called after the RV is cleared.
6128 SV* sv_rvweaken(SV *const sv)
6136 Copies an integer into the given SV, upgrading first if necessary.
6137 Does not handle 'set' magic. See also C<sv_setiv_mg>.
6139 void sv_setiv(SV *const sv, const IV num)
6147 Like C<sv_setiv>, but also handles 'set' magic.
6149 void sv_setiv_mg(SV *const sv, const IV i)
6157 Copies a double into the given SV, upgrading first if necessary.
6158 Does not handle 'set' magic. See also C<sv_setnv_mg>.
6160 void sv_setnv(SV *const sv, const NV num)
6168 Like C<sv_setnv>, but also handles 'set' magic.
6170 void sv_setnv_mg(SV *const sv, const NV num)
6178 Copies a string into an SV. The string must be null-terminated. Does not
6179 handle 'set' magic. See C<sv_setpv_mg>.
6181 void sv_setpv(SV *const sv, const char *const ptr)
6189 Works like C<sv_catpvf> but copies the text into the SV instead of
6190 appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>.
6192 void sv_setpvf(SV *const sv, const char *const pat, ...)
6200 Like C<sv_setpvf>, but also handles 'set' magic.
6202 void sv_setpvf_mg(SV *const sv, const char *const pat, ...)
6210 Copies an integer into the given SV, also updating its string value.
6211 Does not handle 'set' magic. See C<sv_setpviv_mg>.
6213 void sv_setpviv(SV *const sv, const IV num)
6221 Like C<sv_setpviv>, but also handles 'set' magic.
6223 void sv_setpviv_mg(SV *const sv, const IV iv)
6231 Copies a string into an SV. The C<len> parameter indicates the number of
6232 bytes to be copied. If the C<ptr> argument is NULL the SV will become
6233 undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>.
6235 void sv_setpvn(SV *const sv, const char *const ptr, const STRLEN len)
6243 Like C<sv_setpvn>, but also handles 'set' magic.
6245 void sv_setpvn_mg(SV *const sv, const char *const ptr, const STRLEN len)
6253 Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
6255 void sv_setpvs(SV* sv, const char* s)
6258 Found in file handy.h
6263 Like C<sv_setpv>, but also handles 'set' magic.
6265 void sv_setpv_mg(SV *const sv, const char *const ptr)
6273 Copies an integer into a new SV, optionally blessing the SV. The C<rv>
6274 argument will be upgraded to an RV. That RV will be modified to point to
6275 the new SV. The C<classname> argument indicates the package for the
6276 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
6277 will have a reference count of 1, and the RV will be returned.
6279 SV* sv_setref_iv(SV *const rv, const char *const classname, const IV iv)
6287 Copies a double into a new SV, optionally blessing the SV. The C<rv>
6288 argument will be upgraded to an RV. That RV will be modified to point to
6289 the new SV. The C<classname> argument indicates the package for the
6290 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
6291 will have a reference count of 1, and the RV will be returned.
6293 SV* sv_setref_nv(SV *const rv, const char *const classname, const NV nv)
6301 Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
6302 argument will be upgraded to an RV. That RV will be modified to point to
6303 the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
6304 into the SV. The C<classname> argument indicates the package for the
6305 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
6306 will have a reference count of 1, and the RV will be returned.
6308 Do not use with other Perl types such as HV, AV, SV, CV, because those
6309 objects will become corrupted by the pointer copy process.
6311 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
6313 SV* sv_setref_pv(SV *const rv, const char *const classname, void *const pv)
6321 Copies a string into a new SV, optionally blessing the SV. The length of the
6322 string must be specified with C<n>. The C<rv> argument will be upgraded to
6323 an RV. That RV will be modified to point to the new SV. The C<classname>
6324 argument indicates the package for the blessing. Set C<classname> to
6325 C<NULL> to avoid the blessing. The new SV will have a reference count
6326 of 1, and the RV will be returned.
6328 Note that C<sv_setref_pv> copies the pointer while this copies the string.
6330 SV* sv_setref_pvn(SV *const rv, const char *const classname, const char *const pv, const STRLEN n)
6338 Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
6339 argument will be upgraded to an RV. That RV will be modified to point to
6340 the new SV. The C<classname> argument indicates the package for the
6341 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
6342 will have a reference count of 1, and the RV will be returned.
6344 SV* sv_setref_uv(SV *const rv, const char *const classname, const UV uv)
6352 Copies the contents of the source SV C<ssv> into the destination SV
6353 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
6354 function if the source SV needs to be reused. Does not handle 'set' magic.
6355 Loosely speaking, it performs a copy-by-value, obliterating any previous
6356 content of the destination.
6358 You probably want to use one of the assortment of wrappers, such as
6359 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
6360 C<SvSetMagicSV_nosteal>.
6362 void sv_setsv(SV *dstr, SV *sstr)
6367 =item sv_setsv_flags
6370 Copies the contents of the source SV C<ssv> into the destination SV
6371 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
6372 function if the source SV needs to be reused. Does not handle 'set' magic.
6373 Loosely speaking, it performs a copy-by-value, obliterating any previous
6374 content of the destination.
6375 If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
6376 C<ssv> if appropriate, else not. If the C<flags> parameter has the
6377 C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv>
6378 and C<sv_setsv_nomg> are implemented in terms of this function.
6380 You probably want to use one of the assortment of wrappers, such as
6381 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
6382 C<SvSetMagicSV_nosteal>.
6384 This is the primary function for copying scalars, and most other
6385 copy-ish functions and macros use this underneath.
6387 void sv_setsv_flags(SV *dstr, SV *sstr, const I32 flags)
6395 Like C<sv_setsv>, but also handles 'set' magic.
6397 void sv_setsv_mg(SV *const dstr, SV *const sstr)
6405 Copies an unsigned integer into the given SV, upgrading first if necessary.
6406 Does not handle 'set' magic. See also C<sv_setuv_mg>.
6408 void sv_setuv(SV *const sv, const UV num)
6416 Like C<sv_setuv>, but also handles 'set' magic.
6418 void sv_setuv_mg(SV *const sv, const UV u)
6426 Test an SV for taintedness. Use C<SvTAINTED> instead.
6427 bool sv_tainted(SV *const sv)
6435 Returns true if the SV has a true value by Perl's rules.
6436 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
6437 instead use an in-line version.
6439 I32 sv_true(SV *const sv)
6447 Removes all magic of type C<type> from an SV.
6449 int sv_unmagic(SV *const sv, const int type)
6454 =item sv_unref_flags
6457 Unsets the RV status of the SV, and decrements the reference count of
6458 whatever was being referenced by the RV. This can almost be thought of
6459 as a reversal of C<newSVrv>. The C<cflags> argument can contain
6460 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
6461 (otherwise the decrementing is conditional on the reference count being
6462 different from one or the reference being a readonly SV).
6465 void sv_unref_flags(SV *const ref, const U32 flags)
6473 Untaint an SV. Use C<SvTAINTED_off> instead.
6474 void sv_untaint(SV *const sv)
6482 Upgrade an SV to a more complex form. Generally adds a new body type to the
6483 SV, then copies across as much information as possible from the old body.
6484 You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
6486 void sv_upgrade(SV *const sv, svtype new_type)
6491 =item sv_usepvn_flags
6494 Tells an SV to use C<ptr> to find its string value. Normally the
6495 string is stored inside the SV but sv_usepvn allows the SV to use an
6496 outside string. The C<ptr> should point to memory that was allocated
6497 by C<malloc>. The string length, C<len>, must be supplied. By default
6498 this function will realloc (i.e. move) the memory pointed to by C<ptr>,
6499 so that pointer should not be freed or used by the programmer after
6500 giving it to sv_usepvn, and neither should any pointers from "behind"
6501 that pointer (e.g. ptr + 1) be used.
6503 If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
6504 SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
6505 will be skipped. (i.e. the buffer is actually at least 1 byte longer than
6506 C<len>, and already meets the requirements for storing in C<SvPVX>)
6508 void sv_usepvn_flags(SV *const sv, char* ptr, const STRLEN len, const U32 flags)
6513 =item sv_utf8_decode
6516 If the PV of the SV is an octet sequence in UTF-8
6517 and contains a multiple-byte character, the C<SvUTF8> flag is turned on
6518 so that it looks like a character. If the PV contains only single-byte
6519 characters, the C<SvUTF8> flag stays being off.
6520 Scans PV for validity and returns false if the PV is invalid UTF-8.
6522 NOTE: this function is experimental and may change or be
6523 removed without notice.
6525 bool sv_utf8_decode(SV *const sv)
6530 =item sv_utf8_downgrade
6531 X<sv_utf8_downgrade>
6533 Attempts to convert the PV of an SV from characters to bytes.
6534 If the PV contains a character that cannot fit
6535 in a byte, this conversion will fail;
6536 in this case, either returns false or, if C<fail_ok> is not
6539 This is not as a general purpose Unicode to byte encoding interface:
6540 use the Encode extension for that.
6542 NOTE: this function is experimental and may change or be
6543 removed without notice.
6545 bool sv_utf8_downgrade(SV *const sv, const bool fail_ok)
6550 =item sv_utf8_encode
6553 Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
6554 flag off so that it looks like octets again.
6556 void sv_utf8_encode(SV *const sv)
6561 =item sv_utf8_upgrade
6564 Converts the PV of an SV to its UTF-8-encoded form.
6565 Forces the SV to string form if it is not already.
6566 Will C<mg_get> on C<sv> if appropriate.
6567 Always sets the SvUTF8 flag to avoid future validity checks even
6568 if the whole string is the same in UTF-8 as not.
6569 Returns the number of bytes in the converted string
6571 This is not as a general purpose byte encoding to Unicode interface:
6572 use the Encode extension for that.
6574 STRLEN sv_utf8_upgrade(SV *sv)
6579 =item sv_utf8_upgrade_flags
6580 X<sv_utf8_upgrade_flags>
6582 Converts the PV of an SV to its UTF-8-encoded form.
6583 Forces the SV to string form if it is not already.
6584 Always sets the SvUTF8 flag to avoid future validity checks even
6585 if all the bytes are invariant in UTF-8. If C<flags> has C<SV_GMAGIC> bit set,
6586 will C<mg_get> on C<sv> if appropriate, else not.
6587 Returns the number of bytes in the converted string
6588 C<sv_utf8_upgrade> and
6589 C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
6591 This is not as a general purpose byte encoding to Unicode interface:
6592 use the Encode extension for that.
6594 STRLEN sv_utf8_upgrade_flags(SV *const sv, const I32 flags)
6599 =item sv_utf8_upgrade_nomg
6600 X<sv_utf8_upgrade_nomg>
6602 Like sv_utf8_upgrade, but doesn't do magic on C<sv>
6604 STRLEN sv_utf8_upgrade_nomg(SV *sv)
6612 Processes its arguments like C<vsprintf> and appends the formatted output
6613 to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>.
6615 Usually used via its frontend C<sv_catpvf>.
6617 void sv_vcatpvf(SV *const sv, const char *const pat, va_list *const args)
6625 Processes its arguments like C<vsprintf> and appends the formatted output
6626 to an SV. Uses an array of SVs if the C style variable argument list is
6627 missing (NULL). When running with taint checks enabled, indicates via
6628 C<maybe_tainted> if results are untrustworthy (often due to the use of
6631 Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
6633 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)
6641 Like C<sv_vcatpvf>, but also handles 'set' magic.
6643 Usually used via its frontend C<sv_catpvf_mg>.
6645 void sv_vcatpvf_mg(SV *const sv, const char *const pat, va_list *const args)
6653 Works like C<sv_vcatpvf> but copies the text into the SV instead of
6654 appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>.
6656 Usually used via its frontend C<sv_setpvf>.
6658 void sv_vsetpvf(SV *const sv, const char *const pat, va_list *const args)
6666 Works like C<sv_vcatpvfn> but copies the text into the SV instead of
6669 Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
6671 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)
6679 Like C<sv_vsetpvf>, but also handles 'set' magic.
6681 Usually used via its frontend C<sv_setpvf_mg>.
6683 void sv_vsetpvf_mg(SV *const sv, const char *const pat, va_list *const args)
6691 =head1 Unicode Support
6695 =item bytes_from_utf8
6698 Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
6699 Unlike C<utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
6700 the newly-created string, and updates C<len> to contain the new
6701 length. Returns the original string if no conversion occurs, C<len>
6702 is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
6703 0 if C<s> is converted or consisted entirely of characters that are invariant
6704 in utf8 (i.e., US-ASCII on non-EBCDIC machines).
6706 NOTE: this function is experimental and may change or be
6707 removed without notice.
6709 U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
6712 Found in file utf8.c
6717 Converts a string C<s> of length C<len> from the native encoding into UTF-8.
6718 Returns a pointer to the newly-created string, and sets C<len> to
6719 reflect the new length.
6721 A NUL character will be written after the end of the string.
6723 If you want to convert to UTF-8 from encodings other than
6724 the native (Latin1 or EBCDIC),
6725 see sv_recode_to_utf8().
6727 NOTE: this function is experimental and may change or be
6728 removed without notice.
6730 U8* bytes_to_utf8(const U8 *s, STRLEN *len)
6733 Found in file utf8.c
6738 Return true if the strings s1 and s2 differ case-insensitively, false
6739 if not (if they are equal case-insensitively). If u1 is true, the
6740 string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
6741 the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2
6742 are false, the respective string is assumed to be in native 8-bit
6745 If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
6746 in there (they will point at the beginning of the I<next> character).
6747 If the pointers behind pe1 or pe2 are non-NULL, they are the end
6748 pointers beyond which scanning will not continue under any
6749 circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
6750 s2+l2 will be used as goal end pointers that will also stop the scan,
6751 and which qualify towards defining a successful match: all the scans
6752 that define an explicit length must reach their goal pointers for
6753 a match to succeed).
6755 For case-insensitiveness, the "casefolding" of Unicode is used
6756 instead of upper/lowercasing both the characters, see
6757 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
6759 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2)
6762 Found in file utf8.c
6767 Tests if some arbitrary number of bytes begins in a valid UTF-8
6768 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines)
6769 character is a valid UTF-8 character. The actual number of bytes in the UTF-8
6770 character will be returned if it is valid, otherwise 0.
6772 STRLEN is_utf8_char(const U8 *s)
6775 Found in file utf8.c
6777 =item is_utf8_string
6780 Returns true if first C<len> bytes of the given string form a valid
6781 UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does
6782 not mean 'a string that contains code points above 0x7F encoded in UTF-8'
6783 because a valid ASCII string is a valid UTF-8 string.
6785 See also is_utf8_string_loclen() and is_utf8_string_loc().
6787 bool is_utf8_string(const U8 *s, STRLEN len)
6790 Found in file utf8.c
6792 =item is_utf8_string_loc
6793 X<is_utf8_string_loc>
6795 Like is_utf8_string() but stores the location of the failure (in the
6796 case of "utf8ness failure") or the location s+len (in the case of
6797 "utf8ness success") in the C<ep>.
6799 See also is_utf8_string_loclen() and is_utf8_string().
6801 bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
6804 Found in file utf8.c
6806 =item is_utf8_string_loclen
6807 X<is_utf8_string_loclen>
6809 Like is_utf8_string() but stores the location of the failure (in the
6810 case of "utf8ness failure") or the location s+len (in the case of
6811 "utf8ness success") in the C<ep>, and the number of UTF-8
6812 encoded characters in the C<el>.
6814 See also is_utf8_string_loc() and is_utf8_string().
6816 bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
6819 Found in file utf8.c
6821 =item pv_uni_display
6824 Build to the scalar dsv a displayable version of the string spv,
6825 length len, the displayable version being at most pvlim bytes long
6826 (if longer, the rest is truncated and "..." will be appended).
6828 The flags argument can have UNI_DISPLAY_ISPRINT set to display
6829 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
6830 to display the \\[nrfta\\] as the backslashed versions (like '\n')
6831 (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
6832 UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
6833 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
6835 The pointer to the PV of the dsv is returned.
6837 char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
6840 Found in file utf8.c
6845 The encoding is assumed to be an Encode object, the PV of the ssv is
6846 assumed to be octets in that encoding and decoding the input starts
6847 from the position which (PV + *offset) pointed to. The dsv will be
6848 concatenated the decoded UTF-8 string from ssv. Decoding will terminate
6849 when the string tstr appears in decoding output or the input ends on
6850 the PV of the ssv. The value which the offset points will be modified
6851 to the last input position on the ssv.
6853 Returns TRUE if the terminator was found, else returns FALSE.
6855 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
6860 =item sv_recode_to_utf8
6861 X<sv_recode_to_utf8>
6863 The encoding is assumed to be an Encode object, on entry the PV
6864 of the sv is assumed to be octets in that encoding, and the sv
6865 will be converted into Unicode (and UTF-8).
6867 If the sv already is UTF-8 (or if it is not POK), or if the encoding
6868 is not a reference, nothing is done to the sv. If the encoding is not
6869 an C<Encode::XS> Encoding object, bad things will happen.
6870 (See F<lib/encoding.pm> and L<Encode>).
6872 The PV of the sv is returned.
6874 char* sv_recode_to_utf8(SV* sv, SV *encoding)
6879 =item sv_uni_display
6882 Build to the scalar dsv a displayable version of the scalar sv,
6883 the displayable version being at most pvlim bytes long
6884 (if longer, the rest is truncated and "..." will be appended).
6886 The flags argument is as in pv_uni_display().
6888 The pointer to the PV of the dsv is returned.
6890 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
6893 Found in file utf8.c
6898 The "p" contains the pointer to the UTF-8 string encoding
6899 the character that is being converted.
6901 The "ustrp" is a pointer to the character buffer to put the
6902 conversion result to. The "lenp" is a pointer to the length
6905 The "swashp" is a pointer to the swash to use.
6907 Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
6908 and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually,
6909 but not always, a multicharacter mapping), is tried first.
6911 The "special" is a string like "utf8::ToSpecLower", which means the
6912 hash %utf8::ToSpecLower. The access to the hash is through
6913 Perl_to_utf8_case().
6915 The "normal" is a string like "ToLower" which means the swash
6918 UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
6921 Found in file utf8.c
6926 Convert the UTF-8 encoded character at p to its foldcase version and
6927 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6928 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6929 foldcase version may be longer than the original character (up to
6932 The first character of the foldcased version is returned
6933 (but note, as explained above, that there may be more.)
6935 UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
6938 Found in file utf8.c
6943 Convert the UTF-8 encoded character at p to its lowercase version and
6944 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6945 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6946 lowercase version may be longer than the original character.
6948 The first character of the lowercased version is returned
6949 (but note, as explained above, that there may be more.)
6951 UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
6954 Found in file utf8.c
6959 Convert the UTF-8 encoded character at p to its titlecase version and
6960 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6961 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6962 titlecase version may be longer than the original character.
6964 The first character of the titlecased version is returned
6965 (but note, as explained above, that there may be more.)
6967 UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
6970 Found in file utf8.c
6975 Convert the UTF-8 encoded character at p to its uppercase version and
6976 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6977 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
6978 the uppercase version may be longer than the original character.
6980 The first character of the uppercased version is returned
6981 (but note, as explained above, that there may be more.)
6983 UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
6986 Found in file utf8.c
6988 =item utf8n_to_uvchr
6993 Returns the native character value of the first character in the string
6995 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6996 length, in bytes, of that character.
6998 Allows length and flags to be passed to low level routine.
7000 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
7003 Found in file utf8.c
7005 =item utf8n_to_uvuni
7008 Bottom level UTF-8 decode routine.
7009 Returns the Unicode code point value of the first character in the string C<s>
7010 which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
7011 C<retlen> will be set to the length, in bytes, of that character.
7013 If C<s> does not point to a well-formed UTF-8 character, the behaviour
7014 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
7015 it is assumed that the caller will raise a warning, and this function
7016 will silently just set C<retlen> to C<-1> and return zero. If the
7017 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
7018 malformations will be given, C<retlen> will be set to the expected
7019 length of the UTF-8 character in bytes, and zero will be returned.
7021 The C<flags> can also contain various flags to allow deviations from
7022 the strict UTF-8 encoding (see F<utf8.h>).
7024 Most code should use utf8_to_uvchr() rather than call this directly.
7026 UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
7029 Found in file utf8.c
7034 Returns the number of UTF-8 characters between the UTF-8 pointers C<a>
7037 WARNING: use only if you *know* that the pointers point inside the
7040 IV utf8_distance(const U8 *a, const U8 *b)
7043 Found in file utf8.c
7048 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
7049 forward or backward.
7051 WARNING: do not use the following unless you *know* C<off> is within
7052 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
7053 on the first byte of character or just after the last byte of a character.
7055 U8* utf8_hop(const U8 *s, I32 off)
7058 Found in file utf8.c
7063 Return the length of the UTF-8 char encoded string C<s> in characters.
7064 Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
7065 up past C<e>, croaks.
7067 STRLEN utf8_length(const U8* s, const U8 *e)
7070 Found in file utf8.c
7075 Converts a string C<s> of length C<len> from UTF-8 into native byte encoding.
7076 Unlike C<bytes_to_utf8>, this over-writes the original string, and
7077 updates len to contain the new length.
7078 Returns zero on failure, setting C<len> to -1.
7080 If you need a copy of the string, see C<bytes_from_utf8>.
7082 NOTE: this function is experimental and may change or be
7083 removed without notice.
7085 U8* utf8_to_bytes(U8 *s, STRLEN *len)
7088 Found in file utf8.c
7093 Returns the native character value of the first character in the string C<s>
7094 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
7095 length, in bytes, of that character.
7097 If C<s> does not point to a well-formed UTF-8 character, zero is
7098 returned and retlen is set, if possible, to -1.
7100 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
7103 Found in file utf8.c
7108 Returns the Unicode code point of the first character in the string C<s>
7109 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
7110 length, in bytes, of that character.
7112 This function should only be used when the returned UV is considered
7113 an index into the Unicode semantic tables (e.g. swashes).
7115 If C<s> does not point to a well-formed UTF-8 character, zero is
7116 returned and retlen is set, if possible, to -1.
7118 UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
7121 Found in file utf8.c
7126 Adds the UTF-8 representation of the Native codepoint C<uv> to the end
7127 of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
7128 bytes available. The return value is the pointer to the byte after the
7129 end of the new character. In other words,
7131 d = uvchr_to_utf8(d, uv);
7133 is the recommended wide native character-aware way of saying
7137 U8* uvchr_to_utf8(U8 *d, UV uv)
7140 Found in file utf8.c
7142 =item uvuni_to_utf8_flags
7143 X<uvuni_to_utf8_flags>
7145 Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
7146 of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
7147 bytes available. The return value is the pointer to the byte after the
7148 end of the new character. In other words,
7150 d = uvuni_to_utf8_flags(d, uv, flags);
7154 d = uvuni_to_utf8(d, uv);
7156 (which is equivalent to)
7158 d = uvuni_to_utf8_flags(d, uv, 0);
7160 is the recommended Unicode-aware way of saying
7164 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
7167 Found in file utf8.c
7172 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
7179 Variable which is setup by C<xsubpp> to indicate the stack base offset,
7180 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
7181 must be called prior to setup the C<MARK> variable.
7186 Found in file XSUB.h
7191 Variable which is setup by C<xsubpp> to indicate the
7192 class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
7197 Found in file XSUB.h
7202 Sets up the C<ax> variable.
7203 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
7208 Found in file XSUB.h
7213 Sets up the C<ax> variable and stack marker variable C<mark>.
7214 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
7219 Found in file XSUB.h
7224 Sets up the C<items> variable.
7225 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
7230 Found in file XSUB.h
7235 Sets up the C<padoff_du> variable for an XSUB that wishes to use
7241 Found in file XSUB.h
7246 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
7247 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
7248 This is usually handled automatically by C<xsubpp>.
7253 Found in file XSUB.h
7258 Sets up the C<ix> variable for an XSUB which has aliases. This is usually
7259 handled automatically by C<xsubpp>.
7264 Found in file XSUB.h
7269 Variable which is setup by C<xsubpp> to indicate the number of
7270 items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
7275 Found in file XSUB.h
7280 Variable which is setup by C<xsubpp> to indicate which of an
7281 XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
7286 Found in file XSUB.h
7291 Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
7295 Found in file XSUB.h
7300 Variable which is setup by C<xsubpp> to hold the return value for an
7301 XSUB. This is always the proper type for the XSUB. See
7302 L<perlxs/"The RETVAL Variable">.
7307 Found in file XSUB.h
7312 Used to access elements on the XSUB's stack.
7317 Found in file XSUB.h
7322 Variable which is setup by C<xsubpp> to designate the object in a C++
7323 XSUB. This is always the proper type for the C++ object. See C<CLASS> and
7324 L<perlxs/"Using XS With C++">.
7329 Found in file XSUB.h
7334 The SV* corresponding to the $_ variable. Works even if there
7335 is a lexical $_ in scope.
7338 Found in file XSUB.h
7343 Macro to declare an XSUB and its C parameter list. This is handled by
7347 Found in file XSUB.h
7352 The version identifier for an XS module. This is usually
7353 handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
7356 Found in file XSUB.h
7358 =item XS_VERSION_BOOTCHECK
7359 X<XS_VERSION_BOOTCHECK>
7361 Macro to verify that a PM module's $VERSION variable matches the XS
7362 module's C<XS_VERSION> variable. This is usually handled automatically by
7363 C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
7365 XS_VERSION_BOOTCHECK;
7368 Found in file XSUB.h
7373 =head1 Warning and Dieing
7380 This is the XSUB-writer's interface to Perl's C<die> function.
7381 Normally call this function the same way you call the C C<printf>
7382 function. Calling C<croak> returns control directly to Perl,
7383 sidestepping the normal C order of execution. See C<warn>.
7385 If you want to throw an exception object, assign the object to
7386 C<$@> and then pass C<NULL> to croak():
7388 errsv = get_sv("@", GV_ADD);
7389 sv_setsv(errsv, exception_object);
7392 void croak(const char* pat, ...)
7395 Found in file util.c
7400 This is the XSUB-writer's interface to Perl's C<warn> function. Call this
7401 function the same way you call the C C<printf> function. See C<croak>.
7403 void warn(const char* pat, ...)
7406 Found in file util.c
7413 Until May 1997, this document was maintained by Jeff Okamoto
7414 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
7416 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
7417 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
7418 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
7419 Stephen McCamant, and Gurusamy Sarathy.
7421 API Listing originally by Dean Roehrich <roehrich@cray.com>.
7423 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
7427 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
projects / p5sagit/p5-mst-13.2.git / blob