3 perlapi - autogenerated documentation for the perl public API
7 This file contains the documentation of the perl public API generated by
8 embed.pl, specifically a listing of functions, macros, flags, and variables
9 that may be used by extension writers. The interfaces of any functions that
10 are not listed here are subject to change without notice. For this reason,
11 blindly using functions listed in proto.h is to be avoided when writing
14 Note that all Perl API global variables must be referenced with the C<PL_>
15 prefix. Some macros are provided for compatibility with the older,
16 unadorned names, but this support may be disabled in a future release.
18 The listing is alphabetical, case insensitive.
27 A backward-compatible version of C<GIMME_V> which can only return
28 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
29 Deprecated. Use C<GIMME_V> instead.
38 The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
39 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
49 Used to indicate list context. See C<GIMME_V>, C<GIMME> and
57 Indicates that arguments returned from a callback should be discarded. See
65 Used to force a Perl C<eval> wrapper around a callback. See
73 Indicates that no arguments are being sent to a callback. See
81 Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
89 Used to indicate void context. See C<GIMME_V> and L<perlcall>.
97 =head1 Array Manipulation Functions
103 Same as C<av_len()>. Deprecated, use C<av_len()> instead.
112 Clears an array, making it empty. Does not free the memory used by the
115 void av_clear(AV* ar)
122 Deletes the element indexed by C<key> from the array. Returns the
123 deleted element. C<flags> is currently ignored.
125 SV* av_delete(AV* ar, I32 key, I32 flags)
132 Returns true if the element indexed by C<key> has been initialized.
134 This relies on the fact that uninitialized array elements are set to
137 bool av_exists(AV* ar, I32 key)
144 Pre-extend an array. The C<key> is the index to which the array should be
147 void av_extend(AV* ar, I32 key)
154 Returns the SV at the specified index in the array. The C<key> is the
155 index. If C<lval> is set then the fetch will be part of a store. Check
156 that the return value is non-null before dereferencing it to a C<SV*>.
158 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
159 more information on how to use this function on tied arrays.
161 SV** av_fetch(AV* ar, I32 key, I32 lval)
168 Ensure than an array has a given number of elements, equivalent to
169 Perl's C<$#array = $fill;>.
171 void av_fill(AV* ar, I32 fill)
178 Returns the highest index in the array. Returns -1 if the array is
188 Creates a new AV and populates it with a list of SVs. The SVs are copied
189 into the array, so they may be freed after the call to av_make. The new AV
190 will have a reference count of 1.
192 AV* av_make(I32 size, SV** svp)
199 Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
209 Pushes an SV onto the end of the array. The array will grow automatically
210 to accommodate the addition.
212 void av_push(AV* ar, SV* val)
219 Shifts an SV off the beginning of the array.
228 Stores an SV in an array. The array index is specified as C<key>. The
229 return value will be NULL if the operation failed or if the value did not
230 need to be actually stored within the array (as in the case of tied
231 arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
232 that the caller is responsible for suitably incrementing the reference
233 count of C<val> before the call, and decrementing it if the function
236 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
237 more information on how to use this function on tied arrays.
239 SV** av_store(AV* ar, I32 key, SV* val)
246 Undefines the array. Frees the memory used by the array itself.
248 void av_undef(AV* ar)
255 Unshift the given number of C<undef> values onto the beginning of the
256 array. The array will grow automatically to accommodate the addition. You
257 must then use C<av_store> to assign values to these new elements.
259 void av_unshift(AV* ar, I32 num)
266 Returns the AV of the specified Perl array. If C<create> is set and the
267 Perl variable does not exist then it will be created. If C<create> is not
268 set and the variable does not exist then NULL is returned.
270 NOTE: the perl_ form of this function is deprecated.
272 AV* get_av(const char* name, I32 create)
279 Creates a new AV. The reference count is set to 1.
296 Sort an array. Here is an example:
298 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
300 void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
303 Found in file pp_sort.c
308 =head1 Callback Functions
314 Performs a callback to the specified Perl sub. See L<perlcall>.
316 NOTE: the perl_ form of this function is deprecated.
318 I32 call_argv(const char* sub_name, I32 flags, char** argv)
325 Performs a callback to the specified Perl method. The blessed object must
326 be on the stack. See L<perlcall>.
328 NOTE: the perl_ form of this function is deprecated.
330 I32 call_method(const char* methname, I32 flags)
337 Performs a callback to the specified Perl sub. See L<perlcall>.
339 NOTE: the perl_ form of this function is deprecated.
341 I32 call_pv(const char* sub_name, I32 flags)
348 Performs a callback to the Perl sub whose name is in the SV. See
351 NOTE: the perl_ form of this function is deprecated.
353 I32 call_sv(SV* sv, I32 flags)
360 Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
365 Found in file scope.h
369 Tells Perl to C<eval> the given string and return an SV* result.
371 NOTE: the perl_ form of this function is deprecated.
373 SV* eval_pv(const char* p, I32 croak_on_error)
380 Tells Perl to C<eval> the string in the SV.
382 NOTE: the perl_ form of this function is deprecated.
384 I32 eval_sv(SV* sv, I32 flags)
391 Closing bracket for temporaries on a callback. See C<SAVETMPS> and
397 Found in file scope.h
401 Closing bracket on a callback. See C<ENTER> and L<perlcall>.
406 Found in file scope.h
410 Opening bracket for temporaries on a callback. See C<FREETMPS> and
416 Found in file scope.h
421 =head1 Character classes
427 Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
428 character (including underscore) or digit.
430 bool isALNUM(char ch)
433 Found in file handy.h
437 Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
440 bool isALPHA(char ch)
443 Found in file handy.h
447 Returns a boolean indicating whether the C C<char> is an ASCII
450 bool isDIGIT(char ch)
453 Found in file handy.h
457 Returns a boolean indicating whether the C C<char> is a lowercase
460 bool isLOWER(char ch)
463 Found in file handy.h
467 Returns a boolean indicating whether the C C<char> is whitespace.
469 bool isSPACE(char ch)
472 Found in file handy.h
476 Returns a boolean indicating whether the C C<char> is an uppercase
479 bool isUPPER(char ch)
482 Found in file handy.h
486 Converts the specified character to lowercase.
488 char toLOWER(char ch)
491 Found in file handy.h
495 Converts the specified character to uppercase.
497 char toUPPER(char ch)
500 Found in file handy.h
505 =head1 Cloning an interpreter
511 Create and return a new interpreter by cloning the current one.
513 PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
521 =head1 CV Manipulation Functions
527 Returns the stash of the CV.
536 Returns the CV of the specified Perl subroutine. If C<create> is set and
537 the Perl subroutine does not exist then it will be declared (which has the
538 same effect as saying C<sub name;>). If C<create> is not set and the
539 subroutine does not exist then NULL is returned.
541 NOTE: the perl_ form of this function is deprecated.
543 CV* get_cv(const char* name, I32 create)
559 =head1 Embedding Functions
565 Loads the module whose name is pointed to by the string part of name.
566 Note that the actual module name, not its filename, should be given.
567 Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
568 PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
569 (or 0 for no flags). ver, if specified, provides version semantics
570 similar to C<use Foo::Bar VERSION>. The optional trailing SV*
571 arguments can be used to specify arguments to the module's import()
572 method, similar to C<use Foo::Bar VERSION LIST>.
574 void load_module(U32 flags, SV* name, SV* ver, ...)
581 Allocates a new Perl interpreter. See L<perlembed>.
583 PerlInterpreter* perl_alloc()
590 Initializes a new Perl interpreter. See L<perlembed>.
592 void perl_construct(PerlInterpreter* interp)
599 Shuts down a Perl interpreter. See L<perlembed>.
601 int perl_destruct(PerlInterpreter* interp)
608 Releases a Perl interpreter. See L<perlembed>.
610 void perl_free(PerlInterpreter* interp)
617 Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
619 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
626 Tells a Perl interpreter to run. See L<perlembed>.
628 int perl_run(PerlInterpreter* interp)
635 Tells Perl to C<require> the file named by the string argument. It is
636 analogous to the Perl code C<eval "require '$file'">. It's even
637 implemented that way; consider using Perl_load_module instead.
639 NOTE: the perl_ form of this function is deprecated.
641 void require_pv(const char* pv)
649 =head1 Global Variables
655 C<PL_modglobal> is a general purpose, interpreter global HV for use by
656 extensions that need to keep information on a per-interpreter basis.
657 In a pinch, it can also be used as a symbol table for extensions
658 to share data among each other. It is a good idea to use keys
659 prefixed by the package name of the extension that owns the data.
664 Found in file intrpvar.h
668 A convenience variable which is typically used with C<SvPV> when one
669 doesn't care about the length of the string. It is usually more efficient
670 to either declare a local variable and use that instead or to use the
676 Found in file thrdvar.h
680 This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
686 Found in file intrpvar.h
690 This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
695 Found in file intrpvar.h
699 This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
705 Found in file intrpvar.h
716 Return the SV from the GV.
725 Returns the glob with the given C<name> and a defined subroutine or
726 C<NULL>. The glob lives in the given C<stash>, or in the stashes
727 accessible via @ISA and UNIVERSAL::.
729 The argument C<level> should be either 0 or -1. If C<level==0>, as a
730 side-effect creates a glob with the given C<name> in the given C<stash>
731 which in the case of success contains an alias for the subroutine, and sets
732 up caching info for this glob. Similarly for all the searched stashes.
734 This function grants C<"SUPER"> token as a postfix of the stash name. The
735 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
736 visible to Perl code. So when calling C<call_sv>, you should not use
737 the GV directly; instead, you should use the method's CV, which can be
738 obtained from the GV with the C<GvCV> macro.
740 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
747 See L<gv_fetchmethod_autoload>.
749 GV* gv_fetchmethod(HV* stash, const char* name)
754 =item gv_fetchmethod_autoload
756 Returns the glob which contains the subroutine to call to invoke the method
757 on the C<stash>. In fact in the presence of autoloading this may be the
758 glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
761 The third parameter of C<gv_fetchmethod_autoload> determines whether
762 AUTOLOAD lookup is performed if the given method is not present: non-zero
763 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
764 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
765 with a non-zero C<autoload> parameter.
767 These functions grant C<"SUPER"> token as a prefix of the method name. Note
768 that if you want to keep the returned glob for a long time, you need to
769 check for it being "AUTOLOAD", since at the later time the call may load a
770 different subroutine due to $AUTOLOAD changing its value. Use the glob
771 created via a side effect to do this.
773 These functions have the same side-effects and as C<gv_fetchmeth> with
774 C<level==0>. C<name> should be writable if contains C<':'> or C<'
775 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
776 C<call_sv> apply equally to these functions.
778 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
785 Returns a pointer to the stash for a specified package. C<name> should
786 be a valid UTF-8 string. If C<create> is set then the package will be
787 created if it does not already exist. If C<create> is not set and the
788 package does not exist then NULL is returned.
790 HV* gv_stashpv(const char* name, I32 create)
797 Returns a pointer to the stash for a specified package, which must be a
798 valid UTF-8 string. See C<gv_stashpv>.
800 HV* gv_stashsv(SV* sv, I32 create)
814 This flag, used in the length slot of hash entries and magic structures,
815 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
816 is to be expected. (For information only--not to be used).
824 Null character pointer.
826 Found in file handy.h
833 Found in file handy.h
838 =head1 Hash Manipulation Functions
844 Returns the HV of the specified Perl hash. If C<create> is set and the
845 Perl variable does not exist then it will be created. If C<create> is not
846 set and the variable does not exist then NULL is returned.
848 NOTE: the perl_ form of this function is deprecated.
850 HV* get_hv(const char* name, I32 create)
857 Returns the computed hash stored in the hash entry.
866 Returns the actual pointer stored in the key slot of the hash entry. The
867 pointer may be either C<char*> or C<SV*>, depending on the value of
868 C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
869 usually preferable for finding the value of a key.
878 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
879 holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
880 be assigned to. The C<HePV()> macro is usually preferable for finding key
883 STRLEN HeKLEN(HE* he)
890 Returns the key slot of the hash entry as a C<char*> value, doing any
891 necessary dereferencing of possibly C<SV*> keys. The length of the string
892 is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
893 not care about what the length of the key is, you may use the global
894 variable C<PL_na>, though this is rather less efficient than using a local
895 variable. Remember though, that hash keys in perl are free to contain
896 embedded nulls, so using C<strlen()> or similar is not a good way to find
897 the length of hash keys. This is very similar to the C<SvPV()> macro
898 described elsewhere in this document.
900 char* HePV(HE* he, STRLEN len)
907 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
908 contain an C<SV*> key.
917 Returns the key as an C<SV*>. Will create and return a temporary mortal
918 C<SV*> if the hash entry contains only a C<char*> key.
920 SV* HeSVKEY_force(HE* he)
927 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
928 indicate the presence of an C<SV*> key, and returns the same
931 SV* HeSVKEY_set(HE* he, SV* sv)
938 Returns the value slot (type C<SV*>) stored in the hash entry.
947 Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
949 char* HvNAME(HV* stash)
956 Clears a hash, making it empty.
958 void hv_clear(HV* tb)
965 Deletes a key/value pair in the hash. The value SV is removed from the
966 hash and returned to the caller. The C<klen> is the length of the key.
967 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
970 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
977 Deletes a key/value pair in the hash. The value SV is removed from the
978 hash and returned to the caller. The C<flags> value will normally be zero;
979 if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
980 precomputed hash value, or 0 to ask for it to be computed.
982 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
989 Returns a boolean indicating whether the specified hash key exists. The
990 C<klen> is the length of the key.
992 bool hv_exists(HV* tb, const char* key, I32 klen)
999 Returns a boolean indicating whether the specified hash key exists. C<hash>
1000 can be a valid precomputed hash value, or 0 to ask for it to be
1003 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
1010 Returns the SV which corresponds to the specified key in the hash. The
1011 C<klen> is the length of the key. If C<lval> is set then the fetch will be
1012 part of a store. Check that the return value is non-null before
1013 dereferencing it to an C<SV*>.
1015 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1016 information on how to use this function on tied hashes.
1018 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
1025 Returns the hash entry which corresponds to the specified key in the hash.
1026 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1027 if you want the function to compute it. IF C<lval> is set then the fetch
1028 will be part of a store. Make sure the return value is non-null before
1029 accessing it. The return value when C<tb> is a tied hash is a pointer to a
1030 static location, so be sure to make a copy of the structure if you need to
1033 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1034 information on how to use this function on tied hashes.
1036 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1043 Prepares a starting point to traverse a hash table. Returns the number of
1044 keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
1045 currently only meaningful for hashes without tie magic.
1047 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1048 hash buckets that happen to be in use. If you still need that esoteric
1049 value, you can get it through the macro C<HvFILL(tb)>.
1051 I32 hv_iterinit(HV* tb)
1058 Returns the key from the current position of the hash iterator. See
1061 char* hv_iterkey(HE* entry, I32* retlen)
1068 Returns the key as an C<SV*> from the current position of the hash
1069 iterator. The return value will always be a mortal copy of the key. Also
1072 SV* hv_iterkeysv(HE* entry)
1079 Returns entries from a hash iterator. See C<hv_iterinit>.
1081 HE* hv_iternext(HV* tb)
1088 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1091 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
1098 Returns the value from the current position of the hash iterator. See
1101 SV* hv_iterval(HV* tb, HE* entry)
1108 Adds magic to a hash. See C<sv_magic>.
1110 void hv_magic(HV* hv, GV* gv, int how)
1117 Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1118 the length of the key. The C<hash> parameter is the precomputed hash
1119 value; if it is zero then Perl will compute it. The return value will be
1120 NULL if the operation failed or if the value did not need to be actually
1121 stored within the hash (as in the case of tied hashes). Otherwise it can
1122 be dereferenced to get the original C<SV*>. Note that the caller is
1123 responsible for suitably incrementing the reference count of C<val> before
1124 the call, and decrementing it if the function returned NULL.
1126 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1127 information on how to use this function on tied hashes.
1129 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
1136 Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1137 parameter is the precomputed hash value; if it is zero then Perl will
1138 compute it. The return value is the new hash entry so created. It will be
1139 NULL if the operation failed or if the value did not need to be actually
1140 stored within the hash (as in the case of tied hashes). Otherwise the
1141 contents of the return value can be accessed using the C<He?> macros
1142 described here. Note that the caller is responsible for suitably
1143 incrementing the reference count of C<val> before the call, and
1144 decrementing it if the function returned NULL.
1146 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1147 information on how to use this function on tied hashes.
1149 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1158 void hv_undef(HV* tb)
1165 Creates a new HV. The reference count is set to 1.
1183 =head1 Magical Functions
1189 Clear something magical that the SV represents. See C<sv_magic>.
1191 int mg_clear(SV* sv)
1198 Copies the magic from one SV to another. See C<sv_magic>.
1200 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1207 Finds the magic pointer for type matching the SV. See C<sv_magic>.
1209 MAGIC* mg_find(SV* sv, int type)
1216 Free any magic storage used by the SV. See C<sv_magic>.
1225 Do magic after a value is retrieved from the SV. See C<sv_magic>.
1234 Report on the SV's length. See C<sv_magic>.
1236 U32 mg_length(SV* sv)
1243 Turns on the magical status of an SV. See C<sv_magic>.
1245 void mg_magical(SV* sv)
1252 Do magic after a value is assigned to the SV. See C<sv_magic>.
1261 Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
1262 argument more than once.
1264 void SvGETMAGIC(SV* sv)
1271 Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
1281 Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
1282 argument more than once.
1284 void SvSETMAGIC(SV* sv)
1291 Like C<SvSetSV>, but does any set magic required afterwards.
1293 void SvSetMagicSV(SV* dsb, SV* ssv)
1298 =item SvSetMagicSV_nosteal
1300 Like C<SvSetMagicSV>, but does any set magic required afterwards.
1302 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
1309 Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
1312 void SvSetSV(SV* dsb, SV* ssv)
1317 =item SvSetSV_nosteal
1319 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
1320 ssv. May evaluate arguments more than once.
1322 void SvSetSV_nosteal(SV* dsv, SV* ssv)
1329 Arranges for sv to be shared between threads if a suitable module
1332 void SvSHARE(SV* sv)
1340 =head1 Memory Management
1346 The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
1347 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1348 the type. May fail on overlapping copies. See also C<Move>.
1350 void Copy(void* src, void* dest, int nitems, type)
1353 Found in file handy.h
1357 The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
1358 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1359 the type. Can do overlapping moves. See also C<Copy>.
1361 void Move(void* src, void* dest, int nitems, type)
1364 Found in file handy.h
1368 The XSUB-writer's interface to the C C<malloc> function.
1370 void New(int id, void* ptr, int nitems, type)
1373 Found in file handy.h
1377 The XSUB-writer's interface to the C C<malloc> function, with
1380 void Newc(int id, void* ptr, int nitems, type, cast)
1383 Found in file handy.h
1387 Creates a new SV. A non-zero C<len> parameter indicates the number of
1388 bytes of preallocated string space the SV should have. An extra byte for a
1389 tailing NUL is also reserved. (SvPOK is not set for the SV even if string
1390 space is allocated.) The reference count for the new SV is set to 1.
1391 C<id> is an integer id between 0 and 1299 (used to identify leaks).
1394 SV* NEWSV(int id, STRLEN len)
1397 Found in file handy.h
1401 The XSUB-writer's interface to the C C<malloc> function. The allocated
1402 memory is zeroed with C<memzero>.
1404 void Newz(int id, void* ptr, int nitems, type)
1407 Found in file handy.h
1411 The XSUB-writer's interface to the C C<realloc> function.
1413 void Renew(void* ptr, int nitems, type)
1416 Found in file handy.h
1420 The XSUB-writer's interface to the C C<realloc> function, with
1423 void Renewc(void* ptr, int nitems, type, cast)
1426 Found in file handy.h
1430 The XSUB-writer's interface to the C C<free> function.
1432 void Safefree(void* ptr)
1435 Found in file handy.h
1439 Copy a string to a safe spot. This does not use an SV.
1441 char* savepv(const char* sv)
1444 Found in file util.c
1448 Copy a string to a safe spot. The C<len> indicates number of bytes to
1449 copy. If pointer is NULL allocate space for a string of size specified.
1450 This does not use an SV.
1452 char* savepvn(const char* sv, I32 len)
1455 Found in file util.c
1459 Copy a string to a safe spot in memory shared between threads.
1460 This does not use an SV.
1462 char* savesharedpv(const char* sv)
1465 Found in file util.c
1469 This is an architecture-independent macro to copy one structure to another.
1471 void StructCopy(type src, type dest, type)
1474 Found in file handy.h
1478 The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
1479 destination, C<nitems> is the number of items, and C<type> is the type.
1481 void Zero(void* dest, int nitems, type)
1484 Found in file handy.h
1489 =head1 Miscellaneous Functions
1495 Analyses the string in order to make fast searches on it using fbm_instr()
1496 -- the Boyer-Moore algorithm.
1498 void fbm_compile(SV* sv, U32 flags)
1501 Found in file util.c
1505 Returns the location of the SV in the string delimited by C<str> and
1506 C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
1507 does not have to be fbm_compiled, but the search will not be as fast
1510 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
1513 Found in file util.c
1517 Takes a sprintf-style format pattern and conventional
1518 (non-SV) arguments and returns the formatted string.
1520 (char *) Perl_form(pTHX_ const char* pat, ...)
1522 can be used any place a string (char *) is required:
1524 char * s = Perl_form("%d.%d",major,minor);
1526 Uses a single private buffer so if you want to format several strings you
1527 must explicitly copy the earlier strings away (and free the copies when you
1530 char* form(const char* pat, ...)
1533 Found in file util.c
1537 Fill the sv with current working directory
1539 int getcwd_sv(SV* sv)
1542 Found in file util.c
1546 Test two strings to see if they are equal. Returns true or false.
1548 bool strEQ(char* s1, char* s2)
1551 Found in file handy.h
1555 Test two strings to see if the first, C<s1>, is greater than or equal to
1556 the second, C<s2>. Returns true or false.
1558 bool strGE(char* s1, char* s2)
1561 Found in file handy.h
1565 Test two strings to see if the first, C<s1>, is greater than the second,
1566 C<s2>. Returns true or false.
1568 bool strGT(char* s1, char* s2)
1571 Found in file handy.h
1575 Test two strings to see if the first, C<s1>, is less than or equal to the
1576 second, C<s2>. Returns true or false.
1578 bool strLE(char* s1, char* s2)
1581 Found in file handy.h
1585 Test two strings to see if the first, C<s1>, is less than the second,
1586 C<s2>. Returns true or false.
1588 bool strLT(char* s1, char* s2)
1591 Found in file handy.h
1595 Test two strings to see if they are different. Returns true or
1598 bool strNE(char* s1, char* s2)
1601 Found in file handy.h
1605 Test two strings to see if they are equal. The C<len> parameter indicates
1606 the number of bytes to compare. Returns true or false. (A wrapper for
1609 bool strnEQ(char* s1, char* s2, STRLEN len)
1612 Found in file handy.h
1616 Test two strings to see if they are different. The C<len> parameter
1617 indicates the number of bytes to compare. Returns true or false. (A
1618 wrapper for C<strncmp>).
1620 bool strnNE(char* s1, char* s2, STRLEN len)
1623 Found in file handy.h
1628 =head1 Numeric functions
1634 converts a string representing a binary number to numeric form.
1636 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1637 conversion flags, and I<result> should be NULL or a pointer to an NV.
1638 The scan stops at the end of the string, or the first invalid character.
1639 On return I<*len> is set to the length scanned string, and I<*flags> gives
1642 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1643 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
1644 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1645 and writes the value to I<*result> (or the value is discarded if I<result>
1648 The hex number may optionally be prefixed with "0b" or "b" unless
1649 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1650 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
1651 number may use '_' characters to separate digits.
1653 UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
1656 Found in file numeric.c
1660 converts a string representing a hex number to numeric form.
1662 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
1663 conversion flags, and I<result> should be NULL or a pointer to an NV.
1664 The scan stops at the end of the string, or the first non-hex-digit character.
1665 On return I<*len> is set to the length scanned string, and I<*flags> gives
1668 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
1669 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
1670 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
1671 and writes the value to I<*result> (or the value is discarded if I<result>
1674 The hex number may optionally be prefixed with "0x" or "x" unless
1675 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
1676 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
1677 number may use '_' characters to separate digits.
1679 UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
1682 Found in file numeric.c
1686 Recognise (or not) a number. The type of the number is returned
1687 (0 if unrecognised), otherwise it is a bit-ORed combination of
1688 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
1689 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
1691 If the value of the number can fit an in UV, it is returned in the *valuep
1692 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
1693 will never be set unless *valuep is valid, but *valuep may have been assigned
1694 to during processing even though IS_NUMBER_IN_UV is not set on return.
1695 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
1696 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
1698 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
1699 seen (in which case *valuep gives the true value truncated to an integer), and
1700 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
1701 absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
1702 number is larger than a UV.
1704 int grok_number(const char *pv, STRLEN len, UV *valuep)
1707 Found in file numeric.c
1709 =item grok_numeric_radix
1711 Scan and skip for a numeric decimal separator (radix).
1713 bool grok_numeric_radix(const char **sp, const char *send)
1716 Found in file numeric.c
1721 UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
1724 Found in file numeric.c
1728 For backwards compatibility. Use C<grok_bin> instead.
1730 NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
1733 Found in file numeric.c
1737 For backwards compatibility. Use C<grok_hex> instead.
1739 NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
1742 Found in file numeric.c
1746 For backwards compatibility. Use C<grok_oct> instead.
1748 NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
1751 Found in file numeric.c
1756 =head1 Optree Manipulation Functions
1762 If C<cv> is a constant sub eligible for inlining. returns the constant
1763 value returned by the sub. Otherwise, returns NULL.
1765 Constant subs can be created with C<newCONSTSUB> or as described in
1766 L<perlsub/"Constant Functions">.
1768 SV* cv_const_sv(CV* cv)
1775 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
1776 eligible for inlining at compile-time.
1778 CV* newCONSTSUB(HV* stash, char* name, SV* sv)
1785 Used by C<xsubpp> to hook up XSUBs as Perl subs.
1793 =head1 Stack Manipulation Macros
1799 Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
1809 Saves the original stack mark for the XSUB. See C<ORIGMARK>.
1818 Declares a local copy of perl's stack pointer for the XSUB, available via
1819 the C<SP> macro. See C<SP>.
1828 Used to extend the argument stack for an XSUB's return values. Once
1829 used, guarantees that there is room for at least C<nitems> to be pushed
1832 void EXTEND(SP, int nitems)
1839 Stack marker variable for the XSUB. See C<dMARK>.
1846 The original stack mark for the XSUB. See C<dORIGMARK>.
1853 Pops an integer off the stack.
1862 Pops a long off the stack.
1871 Pops a double off the stack.
1880 Pops a string off the stack. Deprecated. New code should provide
1881 a STRLEN n_a and use POPpx.
1890 Pops a string off the stack which must consist of bytes i.e. characters < 256.
1891 Requires a variable STRLEN n_a in scope.
1900 Pops a string off the stack.
1901 Requires a variable STRLEN n_a in scope.
1910 Pops an SV off the stack.
1919 Push an integer onto the stack. The stack must have room for this element.
1920 Handles 'set' magic. See C<XPUSHi>.
1929 Opening bracket for arguments on a callback. See C<PUTBACK> and
1939 Push a double onto the stack. The stack must have room for this element.
1940 Handles 'set' magic. See C<XPUSHn>.
1949 Push a string onto the stack. The stack must have room for this element.
1950 The C<len> indicates the length of the string. Handles 'set' magic. See
1953 void PUSHp(char* str, STRLEN len)
1960 Push an SV onto the stack. The stack must have room for this element.
1961 Does not handle 'set' magic. See C<XPUSHs>.
1970 Push an unsigned integer onto the stack. The stack must have room for this
1971 element. See C<XPUSHu>.
1980 Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1981 See C<PUSHMARK> and L<perlcall> for other uses.
1990 Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
1998 Refetch the stack pointer. Used after a callback. See L<perlcall>.
2007 Push an integer onto the stack, extending the stack if necessary. Handles
2008 'set' magic. See C<PUSHi>.
2017 Push a double onto the stack, extending the stack if necessary. Handles
2018 'set' magic. See C<PUSHn>.
2027 Push a string onto the stack, extending the stack if necessary. The C<len>
2028 indicates the length of the string. Handles 'set' magic. See
2031 void XPUSHp(char* str, STRLEN len)
2038 Push an SV onto the stack, extending the stack if necessary. Does not
2039 handle 'set' magic. See C<PUSHs>.
2048 Push an unsigned integer onto the stack, extending the stack if necessary.
2058 Return from XSUB, indicating number of items on the stack. This is usually
2059 handled by C<xsubpp>.
2061 void XSRETURN(int nitems)
2064 Found in file XSUB.h
2068 Return an integer from an XSUB immediately. Uses C<XST_mIV>.
2070 void XSRETURN_IV(IV iv)
2073 Found in file XSUB.h
2077 Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
2082 Found in file XSUB.h
2086 Return a double from an XSUB immediately. Uses C<XST_mNV>.
2088 void XSRETURN_NV(NV nv)
2091 Found in file XSUB.h
2095 Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
2097 void XSRETURN_PV(char* str)
2100 Found in file XSUB.h
2102 =item XSRETURN_UNDEF
2104 Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
2109 Found in file XSUB.h
2113 Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
2118 Found in file XSUB.h
2122 Place an integer into the specified position C<pos> on the stack. The
2123 value is stored in a new mortal SV.
2125 void XST_mIV(int pos, IV iv)
2128 Found in file XSUB.h
2132 Place C<&PL_sv_no> into the specified position C<pos> on the
2135 void XST_mNO(int pos)
2138 Found in file XSUB.h
2142 Place a double into the specified position C<pos> on the stack. The value
2143 is stored in a new mortal SV.
2145 void XST_mNV(int pos, NV nv)
2148 Found in file XSUB.h
2152 Place a copy of a string into the specified position C<pos> on the stack.
2153 The value is stored in a new mortal SV.
2155 void XST_mPV(int pos, char* str)
2158 Found in file XSUB.h
2162 Place C<&PL_sv_undef> into the specified position C<pos> on the
2165 void XST_mUNDEF(int pos)
2168 Found in file XSUB.h
2172 Place C<&PL_sv_yes> into the specified position C<pos> on the
2175 void XST_mYES(int pos)
2178 Found in file XSUB.h
2189 An enum of flags for Perl types. These are found in the file B<sv.h>
2190 in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
2197 Integer type flag for scalars. See C<svtype>.
2204 Double type flag for scalars. See C<svtype>.
2211 Pointer type flag for scalars. See C<svtype>.
2218 Type flag for arrays. See C<svtype>.
2225 Type flag for code refs. See C<svtype>.
2232 Type flag for hashes. See C<svtype>.
2239 Type flag for blessed scalars. See C<svtype>.
2247 =head1 SV Manipulation Functions
2253 Returns the SV of the specified Perl scalar. If C<create> is set and the
2254 Perl variable does not exist then it will be created. If C<create> is not
2255 set and the variable does not exist then NULL is returned.
2257 NOTE: the perl_ form of this function is deprecated.
2259 SV* get_sv(const char* name, I32 create)
2262 Found in file perl.c
2264 =item looks_like_number
2266 Test if the content of an SV looks like a number (or is a number).
2267 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
2268 non-numeric warning), even if your atof() doesn't grok them.
2270 I32 looks_like_number(SV* sv)
2277 Creates an RV wrapper for an SV. The reference count for the original SV is
2280 SV* newRV_inc(SV* sv)
2287 Creates an RV wrapper for an SV. The reference count for the original
2288 SV is B<not> incremented.
2290 SV* newRV_noinc(SV *sv)
2297 Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
2298 with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
2301 SV* newSV(STRLEN len)
2308 Creates a new SV and copies an integer into it. The reference count for the
2318 Creates a new SV and copies a floating point value into it.
2319 The reference count for the SV is set to 1.
2328 Creates a new SV and copies a string into it. The reference count for the
2329 SV is set to 1. If C<len> is zero, Perl will compute the length using
2330 strlen(). For efficiency, consider using C<newSVpvn> instead.
2332 SV* newSVpv(const char* s, STRLEN len)
2339 Creates a new SV and initializes it with the string formatted like
2342 SV* newSVpvf(const char* pat, ...)
2349 Creates a new SV and copies a string into it. The reference count for the
2350 SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
2351 string. You are responsible for ensuring that the source string is at least
2354 SV* newSVpvn(const char* s, STRLEN len)
2359 =item newSVpvn_share
2361 Creates a new SV with its SvPVX pointing to a shared string in the string
2362 table. If the string does not already exist in the table, it is created
2363 first. Turns on READONLY and FAKE. The string's hash is stored in the UV
2364 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
2365 otherwise the hash is computed. The idea here is that as the string table
2366 is used for shared hash keys these strings will have SvPVX == HeKEY and
2367 hash lookup will avoid string compare.
2369 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
2376 Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
2377 it will be upgraded to one. If C<classname> is non-null then the new SV will
2378 be blessed in the specified package. The new SV is returned and its
2379 reference count is 1.
2381 SV* newSVrv(SV* rv, const char* classname)
2388 Creates a new SV which is an exact duplicate of the original SV.
2391 SV* newSVsv(SV* old)
2398 Creates a new SV and copies an unsigned integer into it.
2399 The reference count for the SV is set to 1.
2408 Returns a pointer to the next character after the parsed
2409 vstring, as well as updating the passed in sv.
2411 Function must be called like
2414 s = new_vstring(s,sv);
2416 The sv must already be large enough to store the vstring
2419 char* new_vstring(char *vstr, SV *sv)
2422 Found in file util.c
2426 Returns the length of the string which is in the SV. See C<SvLEN>.
2428 STRLEN SvCUR(SV* sv)
2435 Set the length of the string which is in the SV. See C<SvCUR>.
2437 void SvCUR_set(SV* sv, STRLEN len)
2444 Returns a pointer to the last character in the string which is in the SV.
2445 See C<SvCUR>. Access the character as *(SvEND(sv)).
2454 Expands the character buffer in the SV so that it has room for the
2455 indicated number of bytes (remember to reserve space for an extra trailing
2456 NUL character). Calls C<sv_grow> to perform the expansion if necessary.
2457 Returns a pointer to the character buffer.
2459 char * SvGROW(SV* sv, STRLEN len)
2466 Returns a boolean indicating whether the SV contains an integer.
2475 Returns a boolean indicating whether the SV contains an integer. Checks
2476 the B<private> setting. Use C<SvIOK>.
2485 Returns a boolean indicating whether the SV contains a signed integer.
2487 void SvIOK_notUV(SV* sv)
2494 Unsets the IV status of an SV.
2496 void SvIOK_off(SV* sv)
2503 Tells an SV that it is an integer.
2505 void SvIOK_on(SV* sv)
2512 Tells an SV that it is an integer and disables all other OK bits.
2514 void SvIOK_only(SV* sv)
2521 Tells and SV that it is an unsigned integer and disables all other OK bits.
2523 void SvIOK_only_UV(SV* sv)
2530 Returns a boolean indicating whether the SV contains an unsigned integer.
2532 void SvIOK_UV(SV* sv)
2539 Coerces the given SV to an integer and returns it. See C<SvIVx> for a
2540 version which guarantees to evaluate sv only once.
2549 Returns the raw value in the SV's IV slot, without checks or conversions.
2550 Only use when you are sure SvIOK is true. See also C<SvIV()>.
2559 Coerces the given SV to an integer and returns it. Guarantees to evaluate
2560 sv only once. Use the more efficient C<SvIV> otherwise.
2569 Returns the size of the string buffer in the SV, not including any part
2570 attributable to C<SvOOK>. See C<SvCUR>.
2572 STRLEN SvLEN(SV* sv)
2579 Returns a boolean indicating whether the SV contains a number, integer or
2589 Returns a boolean indicating whether the SV contains a number, integer or
2590 double. Checks the B<private> setting. Use C<SvNIOK>.
2592 bool SvNIOKp(SV* sv)
2599 Unsets the NV/IV status of an SV.
2601 void SvNIOK_off(SV* sv)
2608 Returns a boolean indicating whether the SV contains a double.
2617 Returns a boolean indicating whether the SV contains a double. Checks the
2618 B<private> setting. Use C<SvNOK>.
2627 Unsets the NV status of an SV.
2629 void SvNOK_off(SV* sv)
2636 Tells an SV that it is a double.
2638 void SvNOK_on(SV* sv)
2645 Tells an SV that it is a double and disables all other OK bits.
2647 void SvNOK_only(SV* sv)
2654 Coerce the given SV to a double and return it. See C<SvNVx> for a version
2655 which guarantees to evaluate sv only once.
2664 Coerces the given SV to a double and returns it. Guarantees to evaluate
2665 sv only once. Use the more efficient C<SvNV> otherwise.
2674 Returns the raw value in the SV's NV slot, without checks or conversions.
2675 Only use when you are sure SvNOK is true. See also C<SvNV()>.
2684 Returns a boolean indicating whether the value is an SV.
2693 Returns a boolean indicating whether the SvIVX is a valid offset value for
2694 the SvPVX. This hack is used internally to speed up removal of characters
2695 from the beginning of a SvPV. When SvOOK is true, then the start of the
2696 allocated string buffer is really (SvPVX - SvIVX).
2705 Returns a boolean indicating whether the SV contains a character
2715 Returns a boolean indicating whether the SV contains a character string.
2716 Checks the B<private> setting. Use C<SvPOK>.
2725 Unsets the PV status of an SV.
2727 void SvPOK_off(SV* sv)
2734 Tells an SV that it is a string.
2736 void SvPOK_on(SV* sv)
2743 Tells an SV that it is a string and disables all other OK bits.
2744 Will also turn off the UTF8 status.
2746 void SvPOK_only(SV* sv)
2751 =item SvPOK_only_UTF8
2753 Tells an SV that it is a string and disables all other OK bits,
2754 and leaves the UTF8 status as it was.
2756 void SvPOK_only_UTF8(SV* sv)
2763 Returns a pointer to the string in the SV, or a stringified form of
2764 the SV if the SV does not contain a string. The SV may cache the
2765 stringified version becoming C<SvPOK>. Handles 'get' magic. See also
2766 C<SvPVx> for a version which guarantees to evaluate sv only once.
2768 char* SvPV(SV* sv, STRLEN len)
2775 Like C<SvPV>, but converts sv to byte representation first if necessary.
2777 char* SvPVbyte(SV* sv, STRLEN len)
2784 Like C<SvPV>, but converts sv to byte representation first if necessary.
2785 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
2789 char* SvPVbytex(SV* sv, STRLEN len)
2794 =item SvPVbytex_force
2796 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2797 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
2800 char* SvPVbytex_force(SV* sv, STRLEN len)
2805 =item SvPVbyte_force
2807 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2809 char* SvPVbyte_force(SV* sv, STRLEN len)
2814 =item SvPVbyte_nolen
2816 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
2818 char* SvPVbyte_nolen(SV* sv)
2825 Like C<SvPV>, but converts sv to utf8 first if necessary.
2827 char* SvPVutf8(SV* sv, STRLEN len)
2834 Like C<SvPV>, but converts sv to utf8 first if necessary.
2835 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
2838 char* SvPVutf8x(SV* sv, STRLEN len)
2843 =item SvPVutf8x_force
2845 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2846 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
2849 char* SvPVutf8x_force(SV* sv, STRLEN len)
2854 =item SvPVutf8_force
2856 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2858 char* SvPVutf8_force(SV* sv, STRLEN len)
2863 =item SvPVutf8_nolen
2865 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
2867 char* SvPVutf8_nolen(SV* sv)
2874 Returns a pointer to the physical string in the SV. The SV must contain a
2884 A version of C<SvPV> which guarantees to evaluate sv only once.
2886 char* SvPVx(SV* sv, STRLEN len)
2893 Like C<SvPV> but will force the SV into containing just a string
2894 (C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
2897 char* SvPV_force(SV* sv, STRLEN len)
2902 =item SvPV_force_nomg
2904 Like C<SvPV> but will force the SV into containing just a string
2905 (C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
2906 directly. Doesn't process magic.
2908 char* SvPV_force_nomg(SV* sv, STRLEN len)
2915 Returns a pointer to the string in the SV, or a stringified form of
2916 the SV if the SV does not contain a string. The SV may cache the
2917 stringified form becoming C<SvPOK>. Handles 'get' magic.
2919 char* SvPV_nolen(SV* sv)
2926 Returns the value of the object's reference count.
2928 U32 SvREFCNT(SV* sv)
2935 Decrements the reference count of the given SV.
2937 void SvREFCNT_dec(SV* sv)
2944 Increments the reference count of the given SV.
2946 SV* SvREFCNT_inc(SV* sv)
2953 Tests if the SV is an RV.
2962 Unsets the RV status of an SV.
2964 void SvROK_off(SV* sv)
2971 Tells an SV that it is an RV.
2973 void SvROK_on(SV* sv)
2980 Dereferences an RV to return the SV.
2989 Returns the stash of the SV.
2998 Taints an SV if tainting is enabled
3000 void SvTAINT(SV* sv)
3007 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
3010 bool SvTAINTED(SV* sv)
3017 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
3018 some of Perl's fundamental security features. XS module authors should not
3019 use this function unless they fully understand all the implications of
3020 unconditionally untainting the value. Untainting should be done in the
3021 standard perl fashion, via a carefully crafted regexp, rather than directly
3022 untainting variables.
3024 void SvTAINTED_off(SV* sv)
3031 Marks an SV as tainted.
3033 void SvTAINTED_on(SV* sv)
3040 Returns a boolean indicating whether Perl would evaluate the SV as true or
3041 false, defined or undefined. Does not handle 'get' magic.
3050 Returns the type of the SV. See C<svtype>.
3052 svtype SvTYPE(SV* sv)
3059 Releases a mutual exclusion lock on sv if a suitable module
3063 void SvUNLOCK(SV* sv)
3070 Returns a boolean indicating whether the SV contains an unsigned integer.
3079 Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
3080 perform the upgrade if necessary. See C<svtype>.
3082 void SvUPGRADE(SV* sv, svtype type)
3089 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
3098 Unsets the UTF8 status of an SV.
3100 void SvUTF8_off(SV *sv)
3107 Turn on the UTF8 status of an SV (the data is not changed, just the flag).
3108 Do not use frivolously.
3110 void SvUTF8_on(SV *sv)
3117 Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
3118 for a version which guarantees to evaluate sv only once.
3127 Returns the raw value in the SV's UV slot, without checks or conversions.
3128 Only use when you are sure SvIOK is true. See also C<SvUV()>.
3137 Coerces the given SV to an unsigned integer and returns it. Guarantees to
3138 evaluate sv only once. Use the more efficient C<SvUV> otherwise.
3147 This function is only called on magical items, and is only used by
3148 sv_true() or its macro equivalent.
3150 bool sv_2bool(SV* sv)
3157 Using various gambits, try to get a CV from an SV; in addition, try if
3158 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
3160 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
3167 Using various gambits, try to get an IO from an SV: the IO slot if its a
3168 GV; or the recursive result if we're an RV; or the IO slot of the symbol
3169 named after the PV if we're a string.
3178 Return the integer value of an SV, doing any necessary string conversion,
3179 magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
3188 Marks an existing SV as mortal. The SV will be destroyed "soon", either
3189 by an explicit call to FREETMPS, or by an implicit call at places such as
3190 statement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
3192 SV* sv_2mortal(SV* sv)
3199 Return the num value of an SV, doing any necessary string or integer
3200 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
3210 Return a pointer to the byte-encoded representation of the SV, and set *lp
3211 to its length. May cause the SV to be downgraded from UTF8 as a
3214 Usually accessed via the C<SvPVbyte> macro.
3216 char* sv_2pvbyte(SV* sv, STRLEN* lp)
3221 =item sv_2pvbyte_nolen
3223 Return a pointer to the byte-encoded representation of the SV.
3224 May cause the SV to be downgraded from UTF8 as a side-effect.
3226 Usually accessed via the C<SvPVbyte_nolen> macro.
3228 char* sv_2pvbyte_nolen(SV* sv)
3235 Return a pointer to the UTF8-encoded representation of the SV, and set *lp
3236 to its length. May cause the SV to be upgraded to UTF8 as a side-effect.
3238 Usually accessed via the C<SvPVutf8> macro.
3240 char* sv_2pvutf8(SV* sv, STRLEN* lp)
3245 =item sv_2pvutf8_nolen
3247 Return a pointer to the UTF8-encoded representation of the SV.
3248 May cause the SV to be upgraded to UTF8 as a side-effect.
3250 Usually accessed via the C<SvPVutf8_nolen> macro.
3252 char* sv_2pvutf8_nolen(SV* sv)
3259 Returns a pointer to the string value of an SV, and sets *lp to its length.
3260 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
3262 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
3263 usually end up here too.
3265 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
3272 Like C<sv_2pv()>, but doesn't return the length too. You should usually
3273 use the macro wrapper C<SvPV_nolen(sv)> instead.
3274 char* sv_2pv_nolen(SV* sv)
3281 Return the unsigned integer value of an SV, doing any necessary string
3282 conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
3292 Remove any string offset. You should normally use the C<SvOOK_off> macro
3295 int sv_backoff(SV* sv)
3302 Blesses an SV into a specified package. The SV must be an RV. The package
3303 must be designated by its stash (see C<gv_stashpv()>). The reference count
3304 of the SV is unaffected.
3306 SV* sv_bless(SV* sv, HV* stash)
3313 Concatenates the string onto the end of the string which is in the SV.
3314 If the SV has the UTF8 status set, then the bytes appended should be
3315 valid UTF8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
3317 void sv_catpv(SV* sv, const char* ptr)
3324 Processes its arguments like C<sprintf> and appends the formatted
3325 output to an SV. If the appended data contains "wide" characters
3326 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
3327 and characters >255 formatted with %c), the original SV might get
3328 upgraded to UTF-8. Handles 'get' magic, but not 'set' magic.
3329 C<SvSETMAGIC()> must typically be called after calling this function
3330 to handle 'set' magic.
3332 void sv_catpvf(SV* sv, const char* pat, ...)
3339 Like C<sv_catpvf>, but also handles 'set' magic.
3341 void sv_catpvf_mg(SV *sv, const char* pat, ...)
3348 Concatenates the string onto the end of the string which is in the SV. The
3349 C<len> indicates number of bytes to copy. If the SV has the UTF8
3350 status set, then the bytes appended should be valid UTF8.
3351 Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
3353 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
3358 =item sv_catpvn_flags
3360 Concatenates the string onto the end of the string which is in the SV. The
3361 C<len> indicates number of bytes to copy. If the SV has the UTF8
3362 status set, then the bytes appended should be valid UTF8.
3363 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
3364 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
3365 in terms of this function.
3367 void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
3374 Like C<sv_catpvn>, but also handles 'set' magic.
3376 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
3383 Like C<sv_catpv>, but also handles 'set' magic.
3385 void sv_catpv_mg(SV *sv, const char *ptr)
3392 Concatenates the string from SV C<ssv> onto the end of the string in
3393 SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
3394 not 'set' magic. See C<sv_catsv_mg>.
3396 void sv_catsv(SV* dsv, SV* ssv)
3401 =item sv_catsv_flags
3403 Concatenates the string from SV C<ssv> onto the end of the string in
3404 SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
3405 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
3406 and C<sv_catsv_nomg> are implemented in terms of this function.
3408 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
3415 Like C<sv_catsv>, but also handles 'set' magic.
3417 void sv_catsv_mg(SV *dstr, SV *sstr)
3424 Efficient removal of characters from the beginning of the string buffer.
3425 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
3426 the string buffer. The C<ptr> becomes the first character of the adjusted
3427 string. Uses the "OOK hack".
3429 void sv_chop(SV* sv, char* ptr)
3436 Clear an SV: call any destructors, free up any memory used by the body,
3437 and free the body itself. The SV's head is I<not> freed, although
3438 its type is set to all 1's so that it won't inadvertently be assumed
3439 to be live during global destruction etc.
3440 This function should only be called when REFCNT is zero. Most of the time
3441 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
3444 void sv_clear(SV* sv)
3451 Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
3452 string in C<sv1> is less than, equal to, or greater than the string in
3453 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3454 coerce its args to strings if necessary. See also C<sv_cmp_locale>.
3456 I32 sv_cmp(SV* sv1, SV* sv2)
3463 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
3464 'use bytes' aware, handles get magic, and will coerce its args to strings
3465 if necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>.
3467 I32 sv_cmp_locale(SV* sv1, SV* sv2)
3474 Add Collate Transform magic to an SV if it doesn't already have it.
3476 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
3477 scalar data of the variable, but transformed to such a format that a normal
3478 memory comparison can be used to compare the data according to the locale
3481 char* sv_collxfrm(SV* sv, STRLEN* nxp)
3488 Auto-decrement of the value in the SV, doing string to numeric conversion
3489 if necessary. Handles 'get' magic.
3496 =item sv_derived_from
3498 Returns a boolean indicating whether the SV is derived from the specified
3499 class. This is the function that implements C<UNIVERSAL::isa>. It works
3500 for class names as well as for objects.
3502 bool sv_derived_from(SV* sv, const char* name)
3505 Found in file universal.c
3509 Returns a boolean indicating whether the strings in the two SVs are
3510 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3511 coerce its args to strings if necessary.
3513 I32 sv_eq(SV* sv1, SV* sv2)
3518 =item sv_force_normal
3520 Undo various types of fakery on an SV: if the PV is a shared string, make
3521 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3522 an xpvmg. See also C<sv_force_normal_flags>.
3524 void sv_force_normal(SV *sv)
3529 =item sv_force_normal_flags
3531 Undo various types of fakery on an SV: if the PV is a shared string, make
3532 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3533 an xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()>
3534 when unrefing. C<sv_force_normal> calls this function with flags set to 0.
3536 void sv_force_normal_flags(SV *sv, U32 flags)
3543 Decrement an SV's reference count, and if it drops to zero, call
3544 C<sv_clear> to invoke destructors and free up any memory used by
3545 the body; finally, deallocate the SV's head itself.
3546 Normally called via a wrapper macro C<SvREFCNT_dec>.
3548 void sv_free(SV* sv)
3555 Get a line from the filehandle and store it into the SV, optionally
3556 appending to the currently-stored string.
3558 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
3565 Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
3566 upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
3567 Use the C<SvGROW> wrapper instead.
3569 char* sv_grow(SV* sv, STRLEN newlen)
3576 Auto-increment of the value in the SV, doing string to numeric conversion
3577 if necessary. Handles 'get' magic.
3586 Inserts a string at the specified offset/length within the SV. Similar to
3587 the Perl substr() function.
3589 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
3596 Returns a boolean indicating whether the SV is blessed into the specified
3597 class. This does not check for subtypes; use C<sv_derived_from> to verify
3598 an inheritance relationship.
3600 int sv_isa(SV* sv, const char* name)
3607 Returns a boolean indicating whether the SV is an RV pointing to a blessed
3608 object. If the SV is not an RV, or if the object is not blessed, then this
3611 int sv_isobject(SV* sv)
3618 A private implementation of the C<SvIVx> macro for compilers which can't
3619 cope with complex macro expressions. Always use the macro instead.
3628 Returns the length of the string in the SV. Handles magic and type
3629 coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
3631 STRLEN sv_len(SV* sv)
3638 Returns the number of characters in the string in an SV, counting wide
3639 UTF8 bytes as a single character. Handles magic and type coercion.
3641 STRLEN sv_len_utf8(SV* sv)
3648 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
3649 then adds a new magic item of type C<how> to the head of the magic list.
3651 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
3658 Adds magic to an SV, upgrading it if necessary. Applies the
3659 supplied vtable and returns pointer to the magic added.
3661 Note that sv_magicext will allow things that sv_magic will not.
3662 In particular you can add magic to SvREADONLY SVs and and more than
3663 one instance of the same 'how'
3665 I C<namelen> is greater then zero then a savepvn() I<copy> of C<name> is stored,
3666 if C<namelen> is zero then C<name> is stored as-is and - as another special
3667 case - if C<(name && namelen == HEf_SVKEY)> then C<name> is assumed to contain
3668 an C<SV*> and has its REFCNT incremented
3670 (This is now used as a subroutine by sv_magic.)
3672 MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen )
3679 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
3680 The new SV is marked as mortal. It will be destroyed "soon", either by an
3681 explicit call to FREETMPS, or by an implicit call at places such as
3682 statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
3684 SV* sv_mortalcopy(SV* oldsv)
3691 Creates a new null SV which is mortal. The reference count of the SV is
3692 set to 1. It will be destroyed "soon", either by an explicit call to
3693 FREETMPS, or by an implicit call at places such as statement boundaries.
3694 See also C<sv_mortalcopy> and C<sv_2mortal>.
3703 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
3706 SV* sv_newref(SV* sv)
3713 Dummy routine which "locks" an SV when there is no locking module present.
3714 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3715 some level of strict-ness.
3717 void sv_nolocking(SV *)
3720 Found in file util.c
3724 Dummy routine which "shares" an SV when there is no sharing module present.
3725 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3726 some level of strict-ness.
3728 void sv_nosharing(SV *)
3731 Found in file util.c
3733 =item sv_nounlocking
3735 Dummy routine which "unlocks" an SV when there is no locking module present.
3736 Exists to avoid test for a NULL function pointer and because it could potentially warn under
3737 some level of strict-ness.
3739 void sv_nounlocking(SV *)
3742 Found in file util.c
3746 A private implementation of the C<SvNVx> macro for compilers which can't
3747 cope with complex macro expressions. Always use the macro instead.
3756 Converts the value pointed to by offsetp from a count of bytes from the
3757 start of the string, to a count of the equivalent number of UTF8 chars.
3758 Handles magic and type coercion.
3760 void sv_pos_b2u(SV* sv, I32* offsetp)
3767 Converts the value pointed to by offsetp from a count of UTF8 chars from
3768 the start of the string, to a count of the equivalent number of bytes; if
3769 lenp is non-zero, it does the same to lenp, but this time starting from
3770 the offset, rather than from the start of the string. Handles magic and
3773 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
3780 A private implementation of the C<SvPV_nolen> macro for compilers which can't
3781 cope with complex macro expressions. Always use the macro instead.
3790 A private implementation of the C<SvPVbyte_nolen> macro for compilers
3791 which can't cope with complex macro expressions. Always use the macro
3794 char* sv_pvbyte(SV *sv)
3801 A private implementation of the C<SvPVbyte> macro for compilers
3802 which can't cope with complex macro expressions. Always use the macro
3805 char* sv_pvbyten(SV *sv, STRLEN *len)
3810 =item sv_pvbyten_force
3812 A private implementation of the C<SvPVbytex_force> macro for compilers
3813 which can't cope with complex macro expressions. Always use the macro
3816 char* sv_pvbyten_force(SV* sv, STRLEN* lp)
3823 A private implementation of the C<SvPV> macro for compilers which can't
3824 cope with complex macro expressions. Always use the macro instead.
3826 char* sv_pvn(SV *sv, STRLEN *len)
3833 Get a sensible string out of the SV somehow.
3834 A private implementation of the C<SvPV_force> macro for compilers which
3835 can't cope with complex macro expressions. Always use the macro instead.
3837 char* sv_pvn_force(SV* sv, STRLEN* lp)
3842 =item sv_pvn_force_flags
3844 Get a sensible string out of the SV somehow.
3845 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
3846 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
3847 implemented in terms of this function.
3848 You normally want to use the various wrapper macros instead: see
3849 C<SvPV_force> and C<SvPV_force_nomg>
3851 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
3858 A private implementation of the C<SvPVutf8_nolen> macro for compilers
3859 which can't cope with complex macro expressions. Always use the macro
3862 char* sv_pvutf8(SV *sv)
3869 A private implementation of the C<SvPVutf8> macro for compilers
3870 which can't cope with complex macro expressions. Always use the macro
3873 char* sv_pvutf8n(SV *sv, STRLEN *len)
3878 =item sv_pvutf8n_force
3880 A private implementation of the C<SvPVutf8_force> macro for compilers
3881 which can't cope with complex macro expressions. Always use the macro
3884 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
3891 Returns a string describing what the SV is a reference to.
3893 char* sv_reftype(SV* sv, int ob)
3900 Make the first argument a copy of the second, then delete the original.
3901 The target SV physically takes over ownership of the body of the source SV
3902 and inherits its flags; however, the target keeps any magic it owns,
3903 and any magic in the source is discarded.
3904 Note that this is a rather specialist SV copying operation; most of the
3905 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
3907 void sv_replace(SV* sv, SV* nsv)
3912 =item sv_report_used
3914 Dump the contents of all SVs not yet freed. (Debugging aid).
3916 void sv_report_used()
3923 Underlying implementation for the C<reset> Perl function.
3924 Note that the perl-level function is vaguely deprecated.
3926 void sv_reset(char* s, HV* stash)
3933 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
3934 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
3935 push a back-reference to this RV onto the array of backreferences
3936 associated with that magic.
3938 SV* sv_rvweaken(SV *sv)
3945 Copies an integer into the given SV, upgrading first if necessary.
3946 Does not handle 'set' magic. See also C<sv_setiv_mg>.
3948 void sv_setiv(SV* sv, IV num)
3955 Like C<sv_setiv>, but also handles 'set' magic.
3957 void sv_setiv_mg(SV *sv, IV i)
3964 Copies a double into the given SV, upgrading first if necessary.
3965 Does not handle 'set' magic. See also C<sv_setnv_mg>.
3967 void sv_setnv(SV* sv, NV num)
3974 Like C<sv_setnv>, but also handles 'set' magic.
3976 void sv_setnv_mg(SV *sv, NV num)
3983 Copies a string into an SV. The string must be null-terminated. Does not
3984 handle 'set' magic. See C<sv_setpv_mg>.
3986 void sv_setpv(SV* sv, const char* ptr)
3993 Processes its arguments like C<sprintf> and sets an SV to the formatted
3994 output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
3996 void sv_setpvf(SV* sv, const char* pat, ...)
4003 Like C<sv_setpvf>, but also handles 'set' magic.
4005 void sv_setpvf_mg(SV *sv, const char* pat, ...)
4012 Copies an integer into the given SV, also updating its string value.
4013 Does not handle 'set' magic. See C<sv_setpviv_mg>.
4015 void sv_setpviv(SV* sv, IV num)
4022 Like C<sv_setpviv>, but also handles 'set' magic.
4024 void sv_setpviv_mg(SV *sv, IV iv)
4031 Copies a string into an SV. The C<len> parameter indicates the number of
4032 bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
4034 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
4041 Like C<sv_setpvn>, but also handles 'set' magic.
4043 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
4050 Like C<sv_setpv>, but also handles 'set' magic.
4052 void sv_setpv_mg(SV *sv, const char *ptr)
4059 Copies an integer into a new SV, optionally blessing the SV. The C<rv>
4060 argument will be upgraded to an RV. That RV will be modified to point to
4061 the new SV. The C<classname> argument indicates the package for the
4062 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
4063 will be returned and will have a reference count of 1.
4065 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
4072 Copies a double into a new SV, optionally blessing the SV. The C<rv>
4073 argument will be upgraded to an RV. That RV will be modified to point to
4074 the new SV. The C<classname> argument indicates the package for the
4075 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
4076 will be returned and will have a reference count of 1.
4078 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
4085 Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
4086 argument will be upgraded to an RV. That RV will be modified to point to
4087 the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
4088 into the SV. The C<classname> argument indicates the package for the
4089 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
4090 will be returned and will have a reference count of 1.
4092 Do not use with other Perl types such as HV, AV, SV, CV, because those
4093 objects will become corrupted by the pointer copy process.
4095 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
4097 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
4104 Copies a string into a new SV, optionally blessing the SV. The length of the
4105 string must be specified with C<n>. The C<rv> argument will be upgraded to
4106 an RV. That RV will be modified to point to the new SV. The C<classname>
4107 argument indicates the package for the blessing. Set C<classname> to
4108 C<Nullch> to avoid the blessing. The new SV will be returned and will have
4109 a reference count of 1.
4111 Note that C<sv_setref_pv> copies the pointer while this copies the string.
4113 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
4120 Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
4121 argument will be upgraded to an RV. That RV will be modified to point to
4122 the new SV. The C<classname> argument indicates the package for the
4123 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
4124 will be returned and will have a reference count of 1.
4126 SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
4133 Copies the contents of the source SV C<ssv> into the destination SV
4134 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
4135 function if the source SV needs to be reused. Does not handle 'set' magic.
4136 Loosely speaking, it performs a copy-by-value, obliterating any previous
4137 content of the destination.
4139 You probably want to use one of the assortment of wrappers, such as
4140 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4141 C<SvSetMagicSV_nosteal>.
4144 void sv_setsv(SV* dsv, SV* ssv)
4149 =item sv_setsv_flags
4151 Copies the contents of the source SV C<ssv> into the destination SV
4152 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
4153 function if the source SV needs to be reused. Does not handle 'set' magic.
4154 Loosely speaking, it performs a copy-by-value, obliterating any previous
4155 content of the destination.
4156 If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
4157 C<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
4158 implemented in terms of this function.
4160 You probably want to use one of the assortment of wrappers, such as
4161 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4162 C<SvSetMagicSV_nosteal>.
4164 This is the primary function for copying scalars, and most other
4165 copy-ish functions and macros use this underneath.
4167 void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
4174 Like C<sv_setsv>, but also handles 'set' magic.
4176 void sv_setsv_mg(SV *dstr, SV *sstr)
4183 Copies an unsigned integer into the given SV, upgrading first if necessary.
4184 Does not handle 'set' magic. See also C<sv_setuv_mg>.
4186 void sv_setuv(SV* sv, UV num)
4193 Like C<sv_setuv>, but also handles 'set' magic.
4195 void sv_setuv_mg(SV *sv, UV u)
4202 Taint an SV. Use C<SvTAINTED_on> instead.
4203 void sv_taint(SV* sv)
4210 Test an SV for taintedness. Use C<SvTAINTED> instead.
4211 bool sv_tainted(SV* sv)
4218 Returns true if the SV has a true value by Perl's rules.
4219 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
4220 instead use an in-line version.
4229 Removes all magic of type C<type> from an SV.
4231 int sv_unmagic(SV* sv, int type)
4238 Unsets the RV status of the SV, and decrements the reference count of
4239 whatever was being referenced by the RV. This can almost be thought of
4240 as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
4241 being zero. See C<SvROK_off>.
4243 void sv_unref(SV* sv)
4248 =item sv_unref_flags
4250 Unsets the RV status of the SV, and decrements the reference count of
4251 whatever was being referenced by the RV. This can almost be thought of
4252 as a reversal of C<newSVrv>. The C<cflags> argument can contain
4253 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
4254 (otherwise the decrementing is conditional on the reference count being
4255 different from one or the reference being a readonly SV).
4258 void sv_unref_flags(SV* sv, U32 flags)
4265 Untaint an SV. Use C<SvTAINTED_off> instead.
4266 void sv_untaint(SV* sv)
4273 Upgrade an SV to a more complex form. Generally adds a new body type to the
4274 SV, then copies across as much information as possible from the old body.
4275 You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
4277 bool sv_upgrade(SV* sv, U32 mt)
4284 Tells an SV to use C<ptr> to find its string value. Normally the string is
4285 stored inside the SV but sv_usepvn allows the SV to use an outside string.
4286 The C<ptr> should point to memory that was allocated by C<malloc>. The
4287 string length, C<len>, must be supplied. This function will realloc the
4288 memory pointed to by C<ptr>, so that pointer should not be freed or used by
4289 the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
4290 See C<sv_usepvn_mg>.
4292 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
4299 Like C<sv_usepvn>, but also handles 'set' magic.
4301 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
4306 =item sv_utf8_decode
4308 Convert the octets in the PV from UTF-8 to chars. Scan for validity and then
4309 turn off SvUTF8 if needed so that we see characters. Used as a building block
4310 for decode_utf8 in Encode.xs
4312 NOTE: this function is experimental and may change or be
4313 removed without notice.
4315 bool sv_utf8_decode(SV *sv)
4320 =item sv_utf8_downgrade
4322 Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
4323 This may not be possible if the PV contains non-byte encoding characters;
4324 if this is the case, either returns false or, if C<fail_ok> is not
4327 NOTE: this function is experimental and may change or be
4328 removed without notice.
4330 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
4335 =item sv_utf8_encode
4337 Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
4338 flag so that it looks like octets again. Used as a building block
4339 for encode_utf8 in Encode.xs
4341 void sv_utf8_encode(SV *sv)
4346 =item sv_utf8_upgrade
4348 Convert the PV of an SV to its UTF8-encoded form.
4349 Forces the SV to string form if it is not already.
4350 Always sets the SvUTF8 flag to avoid future validity checks even
4351 if all the bytes have hibit clear.
4353 STRLEN sv_utf8_upgrade(SV *sv)
4358 =item sv_utf8_upgrade_flags
4360 Convert the PV of an SV to its UTF8-encoded form.
4361 Forces the SV to string form if it is not already.
4362 Always sets the SvUTF8 flag to avoid future validity checks even
4363 if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
4364 will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
4365 C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
4367 STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
4374 A private implementation of the C<SvUVx> macro for compilers which can't
4375 cope with complex macro expressions. Always use the macro instead.
4384 Processes its arguments like C<vsprintf> and appends the formatted output
4385 to an SV. Uses an array of SVs if the C style variable argument list is
4386 missing (NULL). When running with taint checks enabled, indicates via
4387 C<maybe_tainted> if results are untrustworthy (often due to the use of
4390 Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
4392 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4399 Works like C<vcatpvfn> but copies the text into the SV instead of
4402 Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
4404 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4412 =head1 Unicode Support
4416 =item bytes_from_utf8
4418 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
4419 Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
4420 the newly-created string, and updates C<len> to contain the new
4421 length. Returns the original string if no conversion occurs, C<len>
4422 is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
4423 0 if C<s> is converted or contains all 7bit characters.
4425 NOTE: this function is experimental and may change or be
4426 removed without notice.
4428 U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
4431 Found in file utf8.c
4435 Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
4436 Returns a pointer to the newly-created string, and sets C<len> to
4437 reflect the new length.
4439 NOTE: this function is experimental and may change or be
4440 removed without notice.
4442 U8* bytes_to_utf8(U8 *s, STRLEN *len)
4445 Found in file utf8.c
4449 Return true if the strings s1 and s2 differ case-insensitively, false
4450 if not (if they are equal case-insensitively). If u1 is true, the
4451 string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
4452 the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2
4453 are false, the respective string is assumed to be in native 8-bit
4456 If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
4457 in there (they will point at the beginning of the I<next> character).
4458 If the pointers behind pe1 or pe2 are non-NULL, they are the end
4459 pointers beyond which scanning will not continue under any
4460 circustances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
4461 s2+l2 will be used as goal end pointers that will also stop the scan,
4462 and which qualify towards defining a successful match: all the scans
4463 that define an explicit length must reach their goal pointers for
4464 a match to succeed).
4466 For case-insensitiveness, the "casefolding" of Unicode is used
4467 instead of upper/lowercasing both the characters, see
4468 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
4470 I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
4473 Found in file utf8.c
4477 Tests if some arbitrary number of bytes begins in a valid UTF-8
4478 character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character.
4479 The actual number of bytes in the UTF-8 character will be returned if
4480 it is valid, otherwise 0.
4482 STRLEN is_utf8_char(U8 *p)
4485 Found in file utf8.c
4487 =item is_utf8_string
4489 Returns true if first C<len> bytes of the given string form a valid UTF8
4490 string, false otherwise. Note that 'a valid UTF8 string' does not mean
4491 'a string that contains UTF8' because a valid ASCII string is a valid
4494 bool is_utf8_string(U8 *s, STRLEN len)
4497 Found in file utf8.c
4499 =item pv_uni_display
4501 Build to the scalar dsv a displayable version of the string spv,
4502 length len, the displayable version being at most pvlim bytes long
4503 (if longer, the rest is truncated and "..." will be appended).
4505 The flags argument can have UNI_DISPLAY_ISPRINT set to display
4506 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
4507 to display the \\[nrfta\\] as the backslashed versions (like '\n')
4508 (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
4509 UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
4510 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
4512 The pointer to the PV of the dsv is returned.
4514 char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
4517 Found in file utf8.c
4519 =item sv_recode_to_utf8
4521 The encoding is assumed to be an Encode object, on entry the PV
4522 of the sv is assumed to be octets in that encoding, and the sv
4523 will be converted into Unicode (and UTF-8).
4525 If the sv already is UTF-8 (or if it is not POK), or if the encoding
4526 is not a reference, nothing is done to the sv. If the encoding is not
4527 an C<Encode::XS> Encoding object, bad things will happen.
4528 (See F<lib/encoding.pm> and L<Encode>).
4530 The PV of the sv is returned.
4532 char* sv_recode_to_utf8(SV* sv, SV *encoding)
4537 =item sv_uni_display
4539 Build to the scalar dsv a displayable version of the scalar sv,
4540 the displayable version being at most pvlim bytes long
4541 (if longer, the rest is truncated and "..." will be appended).
4543 The flags argument is as in pv_uni_display().
4545 The pointer to the PV of the dsv is returned.
4547 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
4550 Found in file utf8.c
4554 The "p" contains the pointer to the UTF-8 string encoding
4555 the character that is being converted.
4557 The "ustrp" is a pointer to the character buffer to put the
4558 conversion result to. The "lenp" is a pointer to the length
4561 The "swashp" is a pointer to the swash to use.
4563 Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
4564 and loaded by SWASHGET, using lib/utf8_heavy.pl. The special (usually,
4565 but not always, a multicharacter mapping), is tried first.
4567 The "special" is a string like "utf8::ToSpecLower", which means the
4568 hash %utf8::ToSpecLower. The access to the hash is through
4569 Perl_to_utf8_case().
4571 The "normal" is a string like "ToLower" which means the swash
4574 UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
4577 Found in file utf8.c
4581 Convert the UTF-8 encoded character at p to its foldcase version and
4582 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
4583 that the ustrp needs to be at least UTF8_MAXLEN_FOLD+1 bytes since the
4584 foldcase version may be longer than the original character (up to
4587 The first character of the foldcased version is returned
4588 (but note, as explained above, that there may be more.)
4590 UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
4593 Found in file utf8.c
4597 Convert the UTF-8 encoded character at p to its lowercase version and
4598 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
4599 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4600 lowercase version may be longer than the original character (up to two
4603 The first character of the lowercased version is returned
4604 (but note, as explained above, that there may be more.)
4606 UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
4609 Found in file utf8.c
4613 Convert the UTF-8 encoded character at p to its titlecase version and
4614 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
4615 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4616 titlecase version may be longer than the original character (up to two
4619 The first character of the titlecased version is returned
4620 (but note, as explained above, that there may be more.)
4622 UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
4625 Found in file utf8.c
4629 Convert the UTF-8 encoded character at p to its uppercase version and
4630 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
4631 that the ustrp needs to be at least UTF8_MAXLEN_UCLC+1 bytes since the
4632 uppercase version may be longer than the original character (up to two
4635 The first character of the uppercased version is returned
4636 (but note, as explained above, that there may be more.)
4638 UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
4641 Found in file utf8.c
4643 =item utf8n_to_uvchr
4645 Returns the native character value of the first character in the string C<s>
4646 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4647 length, in bytes, of that character.
4649 Allows length and flags to be passed to low level routine.
4651 UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4654 Found in file utf8.c
4656 =item utf8n_to_uvuni
4658 Bottom level UTF-8 decode routine.
4659 Returns the unicode code point value of the first character in the string C<s>
4660 which is assumed to be in UTF8 encoding and no longer than C<curlen>;
4661 C<retlen> will be set to the length, in bytes, of that character.
4663 If C<s> does not point to a well-formed UTF8 character, the behaviour
4664 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
4665 it is assumed that the caller will raise a warning, and this function
4666 will silently just set C<retlen> to C<-1> and return zero. If the
4667 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
4668 malformations will be given, C<retlen> will be set to the expected
4669 length of the UTF-8 character in bytes, and zero will be returned.
4671 The C<flags> can also contain various flags to allow deviations from
4672 the strict UTF-8 encoding (see F<utf8.h>).
4674 Most code should use utf8_to_uvchr() rather than call this directly.
4676 UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4679 Found in file utf8.c
4683 Returns the number of UTF8 characters between the UTF-8 pointers C<a>
4686 WARNING: use only if you *know* that the pointers point inside the
4689 IV utf8_distance(U8 *a, U8 *b)
4692 Found in file utf8.c
4696 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
4697 forward or backward.
4699 WARNING: do not use the following unless you *know* C<off> is within
4700 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
4701 on the first byte of character or just after the last byte of a character.
4703 U8* utf8_hop(U8 *s, I32 off)
4706 Found in file utf8.c
4710 Return the length of the UTF-8 char encoded string C<s> in characters.
4711 Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
4712 up past C<e>, croaks.
4714 STRLEN utf8_length(U8* s, U8 *e)
4717 Found in file utf8.c
4721 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
4722 Unlike C<bytes_to_utf8>, this over-writes the original string, and
4723 updates len to contain the new length.
4724 Returns zero on failure, setting C<len> to -1.
4726 NOTE: this function is experimental and may change or be
4727 removed without notice.
4729 U8* utf8_to_bytes(U8 *s, STRLEN *len)
4732 Found in file utf8.c
4736 Returns the native character value of the first character in the string C<s>
4737 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4738 length, in bytes, of that character.
4740 If C<s> does not point to a well-formed UTF8 character, zero is
4741 returned and retlen is set, if possible, to -1.
4743 UV utf8_to_uvchr(U8 *s, STRLEN* retlen)
4746 Found in file utf8.c
4750 Returns the Unicode code point of the first character in the string C<s>
4751 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4752 length, in bytes, of that character.
4754 This function should only be used when returned UV is considered
4755 an index into the Unicode semantic tables (e.g. swashes).
4757 If C<s> does not point to a well-formed UTF8 character, zero is
4758 returned and retlen is set, if possible, to -1.
4760 UV utf8_to_uvuni(U8 *s, STRLEN* retlen)
4763 Found in file utf8.c
4767 Adds the UTF8 representation of the Native codepoint C<uv> to the end
4768 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4769 bytes available. The return value is the pointer to the byte after the
4770 end of the new character. In other words,
4772 d = uvchr_to_utf8(d, uv);
4774 is the recommended wide native character-aware way of saying
4778 U8* uvchr_to_utf8(U8 *d, UV uv)
4781 Found in file utf8.c
4783 =item uvuni_to_utf8_flags
4785 Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
4786 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4787 bytes available. The return value is the pointer to the byte after the
4788 end of the new character. In other words,
4790 d = uvuni_to_utf8_flags(d, uv, flags);
4794 d = uvuni_to_utf8(d, uv);
4796 (which is equivalent to)
4798 d = uvuni_to_utf8_flags(d, uv, 0);
4800 is the recommended Unicode-aware way of saying
4804 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
4807 Found in file utf8.c
4812 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
4818 Variable which is setup by C<xsubpp> to indicate the stack base offset,
4819 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
4820 must be called prior to setup the C<MARK> variable.
4825 Found in file XSUB.h
4829 Variable which is setup by C<xsubpp> to indicate the
4830 class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
4835 Found in file XSUB.h
4839 Sets up the C<ax> variable.
4840 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
4845 Found in file XSUB.h
4849 Sets up the C<items> variable.
4850 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
4855 Found in file XSUB.h
4859 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
4860 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
4861 This is usually handled automatically by C<xsubpp>.
4866 Found in file XSUB.h
4870 Sets up the C<ix> variable for an XSUB which has aliases. This is usually
4871 handled automatically by C<xsubpp>.
4876 Found in file XSUB.h
4880 Variable which is setup by C<xsubpp> to indicate the number of
4881 items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
4886 Found in file XSUB.h
4890 Variable which is setup by C<xsubpp> to indicate which of an
4891 XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
4896 Found in file XSUB.h
4900 Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
4904 Found in file XSUB.h
4908 Variable which is setup by C<xsubpp> to hold the return value for an
4909 XSUB. This is always the proper type for the XSUB. See
4910 L<perlxs/"The RETVAL Variable">.
4915 Found in file XSUB.h
4919 Used to access elements on the XSUB's stack.
4924 Found in file XSUB.h
4928 Variable which is setup by C<xsubpp> to designate the object in a C++
4929 XSUB. This is always the proper type for the C++ object. See C<CLASS> and
4930 L<perlxs/"Using XS With C++">.
4935 Found in file XSUB.h
4939 Macro to declare an XSUB and its C parameter list. This is handled by
4943 Found in file XSUB.h
4945 =item XSRETURN_EMPTY
4947 Return an empty list from an XSUB immediately.
4953 Found in file XSUB.h
4957 The version identifier for an XS module. This is usually
4958 handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
4961 Found in file XSUB.h
4963 =item XS_VERSION_BOOTCHECK
4965 Macro to verify that a PM module's $VERSION variable matches the XS
4966 module's C<XS_VERSION> variable. This is usually handled automatically by
4967 C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
4969 XS_VERSION_BOOTCHECK;
4972 Found in file XSUB.h
4977 =head1 Warning and Dieing
4983 This is the XSUB-writer's interface to Perl's C<die> function.
4984 Normally use this function the same way you use the C C<printf>
4985 function. See C<warn>.
4987 If you want to throw an exception object, assign the object to
4988 C<$@> and then pass C<Nullch> to croak():
4990 errsv = get_sv("@", TRUE);
4991 sv_setsv(errsv, exception_object);
4994 void croak(const char* pat, ...)
4997 Found in file util.c
5001 This is the XSUB-writer's interface to Perl's C<warn> function. Use this
5002 function the same way you use the C C<printf> function. See
5005 void warn(const char* pat, ...)
5008 Found in file util.c
5015 Until May 1997, this document was maintained by Jeff Okamoto
5016 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
5018 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
5019 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
5020 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
5021 Stephen McCamant, and Gurusamy Sarathy.
5023 API Listing originally by Dean Roehrich <roehrich@cray.com>.
5025 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
5029 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
projects / p5sagit/p5-mst-13.2.git / blob