1 -*- buffer-read-only: t -*-
3 !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
4 This file is built by autodoc.pl extracting documentation from the C source
9 perlapi - autogenerated documentation for the perl public API
12 X<Perl API> X<API> X<api>
14 This file contains the documentation of the perl public API generated by
15 embed.pl, specifically a listing of functions, macros, flags, and variables
16 that may be used by extension writers. The interfaces of any functions that
17 are not listed here are subject to change without notice. For this reason,
18 blindly using functions listed in proto.h is to be avoided when writing
21 Note that all Perl API global variables must be referenced with the C<PL_>
22 prefix. Some macros are provided for compatibility with the older,
23 unadorned names, but this support may be disabled in a future release.
25 The listing is alphabetical, case insensitive.
35 A backward-compatible version of C<GIMME_V> which can only return
36 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
37 Deprecated. Use C<GIMME_V> instead.
47 The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
48 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
59 Used to indicate list context. See C<GIMME_V>, C<GIMME> and
68 Indicates that arguments returned from a callback should be discarded. See
77 Used to force a Perl C<eval> wrapper around a callback. See
86 Indicates that no arguments are being sent to a callback. See
95 Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
104 Used to indicate void context. See C<GIMME_V> and L<perlcall>.
112 =head1 Array Manipulation Functions
119 Same as C<av_len()>. Deprecated, use C<av_len()> instead.
129 Clears an array, making it empty. Does not free the memory used by the
132 void av_clear(AV* ar)
140 Deletes the element indexed by C<key> from the array. Returns the
141 deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
142 and null is returned.
144 SV* av_delete(AV* ar, I32 key, I32 flags)
152 Returns true if the element indexed by C<key> has been initialized.
154 This relies on the fact that uninitialized array elements are set to
157 bool av_exists(AV* ar, I32 key)
165 Pre-extend an array. The C<key> is the index to which the array should be
168 void av_extend(AV* ar, I32 key)
176 Returns the SV at the specified index in the array. The C<key> is the
177 index. If C<lval> is set then the fetch will be part of a store. Check
178 that the return value is non-null before dereferencing it to a C<SV*>.
180 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
181 more information on how to use this function on tied arrays.
183 SV** av_fetch(AV* ar, I32 key, I32 lval)
191 Set the highest index in the array to the given number, equivalent to
192 Perl's C<$#array = $fill;>.
194 The number of elements in the an array will be C<fill + 1> after
195 av_fill() returns. If the array was previously shorter then the
196 additional elements appended are set to C<PL_sv_undef>. If the array
197 was longer, then the excess elements are freed. C<av_fill(av, -1)> is
198 the same as C<av_clear(av)>.
200 void av_fill(AV* ar, I32 fill)
208 Returns the highest index in the array. The number of elements in the
209 array is C<av_len(av) + 1>. Returns -1 if the array is empty.
211 I32 av_len(const AV* ar)
219 Creates a new AV and populates it with a list of SVs. The SVs are copied
220 into the array, so they may be freed after the call to av_make. The new AV
221 will have a reference count of 1.
223 AV* av_make(I32 size, SV** svp)
231 Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
242 Pushes an SV onto the end of the array. The array will grow automatically
243 to accommodate the addition.
245 void av_push(AV* ar, SV* val)
253 Shifts an SV off the beginning of the array.
263 Stores an SV in an array. The array index is specified as C<key>. The
264 return value will be NULL if the operation failed or if the value did not
265 need to be actually stored within the array (as in the case of tied
266 arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
267 that the caller is responsible for suitably incrementing the reference
268 count of C<val> before the call, and decrementing it if the function
271 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
272 more information on how to use this function on tied arrays.
274 SV** av_store(AV* ar, I32 key, SV* val)
282 Undefines the array. Frees the memory used by the array itself.
284 void av_undef(AV* ar)
292 Unshift the given number of C<undef> values onto the beginning of the
293 array. The array will grow automatically to accommodate the addition. You
294 must then use C<av_store> to assign values to these new elements.
296 void av_unshift(AV* ar, I32 num)
304 Returns the AV of the specified Perl array. If C<create> is set and the
305 Perl variable does not exist then it will be created. If C<create> is not
306 set and the variable does not exist then NULL is returned.
308 NOTE: the perl_ form of this function is deprecated.
310 AV* get_av(const char* name, I32 create)
318 Creates a new AV. The reference count is set to 1.
328 Sort an array. Here is an example:
330 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
332 Currently this always uses mergesort. See sortsv_flags for a more
335 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
338 Found in file pp_sort.c
343 Sort an array, with various options.
345 void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
348 Found in file pp_sort.c
353 =head1 Callback Functions
360 Performs a callback to the specified Perl sub. See L<perlcall>.
362 NOTE: the perl_ form of this function is deprecated.
364 I32 call_argv(const char* sub_name, I32 flags, char** argv)
372 Performs a callback to the specified Perl method. The blessed object must
373 be on the stack. See L<perlcall>.
375 NOTE: the perl_ form of this function is deprecated.
377 I32 call_method(const char* methname, I32 flags)
385 Performs a callback to the specified Perl sub. See L<perlcall>.
387 NOTE: the perl_ form of this function is deprecated.
389 I32 call_pv(const char* sub_name, I32 flags)
397 Performs a callback to the Perl sub whose name is in the SV. See
400 NOTE: the perl_ form of this function is deprecated.
402 I32 call_sv(SV* sv, I32 flags)
410 Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
415 Found in file scope.h
420 Tells Perl to C<eval> the given string and return an SV* result.
422 NOTE: the perl_ form of this function is deprecated.
424 SV* eval_pv(const char* p, I32 croak_on_error)
432 Tells Perl to C<eval> the string in the SV.
434 NOTE: the perl_ form of this function is deprecated.
436 I32 eval_sv(SV* sv, I32 flags)
444 Closing bracket for temporaries on a callback. See C<SAVETMPS> and
450 Found in file scope.h
455 Closing bracket on a callback. See C<ENTER> and L<perlcall>.
460 Found in file scope.h
465 Opening bracket for temporaries on a callback. See C<FREETMPS> and
471 Found in file scope.h
476 =head1 Character classes
483 Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
484 character (including underscore) or digit.
486 bool isALNUM(char ch)
489 Found in file handy.h
494 Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
497 bool isALPHA(char ch)
500 Found in file handy.h
505 Returns a boolean indicating whether the C C<char> is an ASCII
508 bool isDIGIT(char ch)
511 Found in file handy.h
516 Returns a boolean indicating whether the C C<char> is a lowercase
519 bool isLOWER(char ch)
522 Found in file handy.h
527 Returns a boolean indicating whether the C C<char> is whitespace.
529 bool isSPACE(char ch)
532 Found in file handy.h
537 Returns a boolean indicating whether the C C<char> is an uppercase
540 bool isUPPER(char ch)
543 Found in file handy.h
548 Converts the specified character to lowercase.
550 char toLOWER(char ch)
553 Found in file handy.h
558 Converts the specified character to uppercase.
560 char toUPPER(char ch)
563 Found in file handy.h
568 =head1 Cloning an interpreter
575 Create and return a new interpreter by cloning the current one.
577 perl_clone takes these flags as parameters:
579 CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
580 without it we only clone the data and zero the stacks,
581 with it we copy the stacks and the new perl interpreter is
582 ready to run at the exact same point as the previous one.
583 The pseudo-fork code uses COPY_STACKS while the
584 threads->new doesn't.
586 CLONEf_KEEP_PTR_TABLE
587 perl_clone keeps a ptr_table with the pointer of the old
588 variable as a key and the new variable as a value,
589 this allows it to check if something has been cloned and not
590 clone it again but rather just use the value and increase the
591 refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
592 the ptr_table using the function
593 C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
594 reason to keep it around is if you want to dup some of your own
595 variable who are outside the graph perl scans, example of this
596 code is in threads.xs create
599 This is a win32 thing, it is ignored on unix, it tells perls
600 win32host code (which is c++) to clone itself, this is needed on
601 win32 if you want to run two threads at the same time,
602 if you just want to do some stuff in a separate perl interpreter
603 and then throw it away and return to the original one,
604 you don't need to do anything.
606 PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
614 =head1 CV Manipulation Functions
621 Returns the stash of the CV.
631 Returns the CV of the specified Perl subroutine. If C<create> is set and
632 the Perl subroutine does not exist then it will be declared (which has the
633 same effect as saying C<sub name;>). If C<create> is not set and the
634 subroutine does not exist then NULL is returned.
636 NOTE: the perl_ form of this function is deprecated.
638 CV* get_cv(const char* name, I32 create)
646 =head1 Embedding Functions
653 Clear out all the active components of a CV. This can happen either
654 by an explicit C<undef &foo>, or by the reference count going to zero.
655 In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
656 children can still follow the full lexical scope chain.
658 void cv_undef(CV* cv)
666 Loads the module whose name is pointed to by the string part of name.
667 Note that the actual module name, not its filename, should be given.
668 Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
669 PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
670 (or 0 for no flags). ver, if specified, provides version semantics
671 similar to C<use Foo::Bar VERSION>. The optional trailing SV*
672 arguments can be used to specify arguments to the module's import()
673 method, similar to C<use Foo::Bar VERSION LIST>.
675 void load_module(U32 flags, SV* name, SV* ver, ...)
683 Stub that provides thread hook for perl_destruct when there are
694 Allocates a new Perl interpreter. See L<perlembed>.
696 PerlInterpreter* perl_alloc()
704 Initializes a new Perl interpreter. See L<perlembed>.
706 void perl_construct(PerlInterpreter* interp)
714 Shuts down a Perl interpreter. See L<perlembed>.
716 int perl_destruct(PerlInterpreter* interp)
724 Releases a Perl interpreter. See L<perlembed>.
726 void perl_free(PerlInterpreter* interp)
734 Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
736 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
744 Tells a Perl interpreter to run. See L<perlembed>.
746 int perl_run(PerlInterpreter* interp)
754 Tells Perl to C<require> the file named by the string argument. It is
755 analogous to the Perl code C<eval "require '$file'">. It's even
756 implemented that way; consider using load_module instead.
758 NOTE: the perl_ form of this function is deprecated.
760 void require_pv(const char* pv)
768 =head1 Functions in file dump.c
776 char *pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
777 STRLEN pvlim, U32 flags)
781 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
783 except that an additional "\0" will be appended to the string when
784 len > cur and pv[cur] is "\0".
786 Note that the final string may be up to 7 chars longer than pvlim.
788 char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
796 |const STRLEN count|const STRLEN max
797 |STRLEN const *escaped, const U32 flags
799 Escapes at most the first "count" chars of pv and puts the results into
800 dsv such that the size of the escaped string will not exceed "max" chars
801 and will not contain any incomplete escape sequences.
803 If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
804 will also be escaped.
806 Normally the SV will be cleared before the escaped string is prepared,
807 but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
809 If PERL_PV_ESCAPE_UNI is set then the input string is treated as unicode,
810 if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
811 using C<is_utf8_string()> to determine if it is unicode.
813 If PERL_PV_ESCAPE_ALL is set then all input chars will be output
814 using C<\x01F1> style escapes, otherwise only chars above 255 will be
815 escaped using this style, other non printable chars will use octal or
816 common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
817 then all chars below 255 will be treated as printable and
818 will be output as literals.
820 If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
821 string will be escaped, regardles of max. If the string is utf8 and
822 the chars value is >255 then it will be returned as a plain hex
823 sequence. Thus the output will either be a single char,
824 an octal escape sequence, a special escape like C<\n> or a 3 or
825 more digit hex value.
827 If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
828 not a '\\'. This is because regexes very often contain backslashed
829 sequences, whereas '%' is not a particularly common character in patterns.
831 Returns a pointer to the escaped text as held by dsv.
833 NOTE: the perl_ form of this function is deprecated.
835 char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
843 |const STRLEN count|const STRLEN max\
844 |const char const *start_color| const char const *end_color\
847 Converts a string into something presentable, handling escaping via
848 pv_escape() and supporting quoting and elipses.
850 If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
851 double quoted with any double quotes in the string escaped. Otherwise
852 if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
855 If the PERL_PV_PRETTY_ELIPSES flag is set and not all characters in
856 string were output then an elipses C<...> will be appended to the
857 string. Note that this happens AFTER it has been quoted.
859 If start_color is non-null then it will be inserted after the opening
860 quote (if there is one) but before the escaped text. If end_color
861 is non-null then it will be inserted after the escaped text but before
862 any quotes or elipses.
864 Returns a pointer to the prettified text as held by dsv.
866 NOTE: the perl_ form of this function is deprecated.
868 char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
876 =head1 Functions in file mathoms.c
884 See L<gv_fetchmethod_autoload>.
886 GV* gv_fetchmethod(HV* stash, const char* name)
889 Found in file mathoms.c
894 The engine implementing pack() Perl function. Note: parameters next_in_list and
895 flags are not used. This call should not be used; use packlist instead.
897 void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
900 Found in file mathoms.c
902 =item sv_2pvbyte_nolen
905 Return a pointer to the byte-encoded representation of the SV.
906 May cause the SV to be downgraded from UTF-8 as a side-effect.
908 Usually accessed via the C<SvPVbyte_nolen> macro.
910 char* sv_2pvbyte_nolen(SV* sv)
913 Found in file mathoms.c
915 =item sv_2pvutf8_nolen
918 Return a pointer to the UTF-8-encoded representation of the SV.
919 May cause the SV to be upgraded to UTF-8 as a side-effect.
921 Usually accessed via the C<SvPVutf8_nolen> macro.
923 char* sv_2pvutf8_nolen(SV* sv)
926 Found in file mathoms.c
931 Like C<sv_2pv()>, but doesn't return the length too. You should usually
932 use the macro wrapper C<SvPV_nolen(sv)> instead.
933 char* sv_2pv_nolen(SV* sv)
936 Found in file mathoms.c
941 Like C<sv_catpvn>, but also handles 'set' magic.
943 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
946 Found in file mathoms.c
951 Like C<sv_catsv>, but also handles 'set' magic.
953 void sv_catsv_mg(SV *dstr, SV *sstr)
956 Found in file mathoms.c
958 =item sv_force_normal
961 Undo various types of fakery on an SV: if the PV is a shared string, make
962 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
963 an xpvmg. See also C<sv_force_normal_flags>.
965 void sv_force_normal(SV *sv)
968 Found in file mathoms.c
973 A private implementation of the C<SvIVx> macro for compilers which can't
974 cope with complex macro expressions. Always use the macro instead.
979 Found in file mathoms.c
984 Dummy routine which "locks" an SV when there is no locking module present.
985 Exists to avoid test for a NULL function pointer and because it could
986 potentially warn under some level of strict-ness.
988 "Superseded" by sv_nosharing().
990 void sv_nolocking(SV *sv)
993 Found in file mathoms.c
998 Dummy routine which "unlocks" an SV when there is no locking module present.
999 Exists to avoid test for a NULL function pointer and because it could
1000 potentially warn under some level of strict-ness.
1002 "Superseded" by sv_nosharing().
1004 void sv_nounlocking(SV *sv)
1007 Found in file mathoms.c
1012 A private implementation of the C<SvNVx> macro for compilers which can't
1013 cope with complex macro expressions. Always use the macro instead.
1018 Found in file mathoms.c
1023 Use the C<SvPV_nolen> macro instead
1028 Found in file mathoms.c
1033 Use C<SvPVbyte_nolen> instead.
1035 char* sv_pvbyte(SV *sv)
1038 Found in file mathoms.c
1043 A private implementation of the C<SvPVbyte> macro for compilers
1044 which can't cope with complex macro expressions. Always use the macro
1047 char* sv_pvbyten(SV *sv, STRLEN *len)
1050 Found in file mathoms.c
1055 A private implementation of the C<SvPV> macro for compilers which can't
1056 cope with complex macro expressions. Always use the macro instead.
1058 char* sv_pvn(SV *sv, STRLEN *len)
1061 Found in file mathoms.c
1066 Use the C<SvPVutf8_nolen> macro instead
1068 char* sv_pvutf8(SV *sv)
1071 Found in file mathoms.c
1076 A private implementation of the C<SvPVutf8> macro for compilers
1077 which can't cope with complex macro expressions. Always use the macro
1080 char* sv_pvutf8n(SV *sv, STRLEN *len)
1083 Found in file mathoms.c
1088 Taint an SV. Use C<SvTAINTED_on> instead.
1089 void sv_taint(SV* sv)
1092 Found in file mathoms.c
1097 Unsets the RV status of the SV, and decrements the reference count of
1098 whatever was being referenced by the RV. This can almost be thought of
1099 as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
1100 being zero. See C<SvROK_off>.
1102 void sv_unref(SV* sv)
1105 Found in file mathoms.c
1110 Tells an SV to use C<ptr> to find its string value. Implemented by
1111 calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
1112 magic. See C<sv_usepvn_flags>.
1114 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
1117 Found in file mathoms.c
1122 Like C<sv_usepvn>, but also handles 'set' magic.
1124 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
1127 Found in file mathoms.c
1132 A private implementation of the C<SvUVx> macro for compilers which can't
1133 cope with complex macro expressions. Always use the macro instead.
1138 Found in file mathoms.c
1143 The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
1144 and ocnt are not used. This call should not be used, use unpackstring instead.
1146 I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
1149 Found in file mathoms.c
1154 =head1 Functions in file pp_pack.c
1162 The engine implementing pack() Perl function.
1164 void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
1167 Found in file pp_pack.c
1172 The engine implementing unpack() Perl function. C<unpackstring> puts the
1173 extracted list items on the stack and returns the number of elements.
1174 Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
1176 I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
1179 Found in file pp_pack.c
1184 =head1 Global Variables
1191 C<PL_modglobal> is a general purpose, interpreter global HV for use by
1192 extensions that need to keep information on a per-interpreter basis.
1193 In a pinch, it can also be used as a symbol table for extensions
1194 to share data among each other. It is a good idea to use keys
1195 prefixed by the package name of the extension that owns the data.
1200 Found in file intrpvar.h
1205 A convenience variable which is typically used with C<SvPV> when one
1206 doesn't care about the length of the string. It is usually more efficient
1207 to either declare a local variable and use that instead or to use the
1208 C<SvPV_nolen> macro.
1213 Found in file thrdvar.h
1218 This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1224 Found in file intrpvar.h
1229 This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
1234 Found in file intrpvar.h
1239 This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1245 Found in file intrpvar.h
1257 Return the SV from the GV.
1267 If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
1268 inlining, or C<gv> is a placeholder reference that would be promoted to such
1269 a typeglob, then returns the value returned by the sub. Otherwise, returns
1272 SV* gv_const_sv(GV* gv)
1280 Returns the glob with the given C<name> and a defined subroutine or
1281 C<NULL>. The glob lives in the given C<stash>, or in the stashes
1282 accessible via @ISA and UNIVERSAL::.
1284 The argument C<level> should be either 0 or -1. If C<level==0>, as a
1285 side-effect creates a glob with the given C<name> in the given C<stash>
1286 which in the case of success contains an alias for the subroutine, and sets
1287 up caching info for this glob. Similarly for all the searched stashes.
1289 This function grants C<"SUPER"> token as a postfix of the stash name. The
1290 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
1291 visible to Perl code. So when calling C<call_sv>, you should not use
1292 the GV directly; instead, you should use the method's CV, which can be
1293 obtained from the GV with the C<GvCV> macro.
1295 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
1300 =item gv_fetchmethod_autoload
1301 X<gv_fetchmethod_autoload>
1303 Returns the glob which contains the subroutine to call to invoke the method
1304 on the C<stash>. In fact in the presence of autoloading this may be the
1305 glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
1308 The third parameter of C<gv_fetchmethod_autoload> determines whether
1309 AUTOLOAD lookup is performed if the given method is not present: non-zero
1310 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
1311 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
1312 with a non-zero C<autoload> parameter.
1314 These functions grant C<"SUPER"> token as a prefix of the method name. Note
1315 that if you want to keep the returned glob for a long time, you need to
1316 check for it being "AUTOLOAD", since at the later time the call may load a
1317 different subroutine due to $AUTOLOAD changing its value. Use the glob
1318 created via a side effect to do this.
1320 These functions have the same side-effects and as C<gv_fetchmeth> with
1321 C<level==0>. C<name> should be writable if contains C<':'> or C<'
1322 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
1323 C<call_sv> apply equally to these functions.
1325 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
1330 =item gv_fetchmeth_autoload
1331 X<gv_fetchmeth_autoload>
1333 Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
1334 Returns a glob for the subroutine.
1336 For an autoloaded subroutine without a GV, will create a GV even
1337 if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
1338 of the result may be zero.
1340 GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
1348 Returns a pointer to the stash for a specified package. C<name> should
1349 be a valid UTF-8 string and must be null-terminated. If C<create> is set
1350 then the package will be created if it does not already exist. If C<create>
1351 is not set and the package does not exist then NULL is returned.
1353 HV* gv_stashpv(const char* name, I32 create)
1361 Returns a pointer to the stash for a specified package. C<name> should
1362 be a valid UTF-8 string. The C<namelen> parameter indicates the length of
1363 the C<name>, in bytes. If C<create> is set then the package will be
1364 created if it does not already exist. If C<create> is not set and the
1365 package does not exist then NULL is returned.
1367 HV* gv_stashpvn(const char* name, U32 namelen, I32 create)
1375 Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
1377 HV* gv_stashpvs(const char* name, I32 create)
1380 Found in file handy.h
1385 Returns a pointer to the stash for a specified package, which must be a
1386 valid UTF-8 string. See C<gv_stashpv>.
1388 HV* gv_stashsv(SV* sv, I32 create)
1411 Null character pointer.
1414 Found in file handy.h
1438 Found in file handy.h
1443 =head1 Hash Manipulation Functions
1450 Returns the HV of the specified Perl hash. If C<create> is set and the
1451 Perl variable does not exist then it will be created. If C<create> is not
1452 set and the variable does not exist then NULL is returned.
1454 NOTE: the perl_ form of this function is deprecated.
1456 HV* get_hv(const char* name, I32 create)
1459 Found in file perl.c
1464 This flag, used in the length slot of hash entries and magic structures,
1465 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
1466 is to be expected. (For information only--not to be used).
1474 Returns the computed hash stored in the hash entry.
1484 Returns the actual pointer stored in the key slot of the hash entry. The
1485 pointer may be either C<char*> or C<SV*>, depending on the value of
1486 C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
1487 usually preferable for finding the value of a key.
1497 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
1498 holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
1499 be assigned to. The C<HePV()> macro is usually preferable for finding key
1502 STRLEN HeKLEN(HE* he)
1510 Returns the key slot of the hash entry as a C<char*> value, doing any
1511 necessary dereferencing of possibly C<SV*> keys. The length of the string
1512 is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
1513 not care about what the length of the key is, you may use the global
1514 variable C<PL_na>, though this is rather less efficient than using a local
1515 variable. Remember though, that hash keys in perl are free to contain
1516 embedded nulls, so using C<strlen()> or similar is not a good way to find
1517 the length of hash keys. This is very similar to the C<SvPV()> macro
1518 described elsewhere in this document.
1520 char* HePV(HE* he, STRLEN len)
1528 Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
1529 contain an C<SV*> key.
1539 Returns the key as an C<SV*>. Will create and return a temporary mortal
1540 C<SV*> if the hash entry contains only a C<char*> key.
1542 SV* HeSVKEY_force(HE* he)
1550 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
1551 indicate the presence of an C<SV*> key, and returns the same
1554 SV* HeSVKEY_set(HE* he, SV* sv)
1562 Returns the value slot (type C<SV*>) stored in the hash entry.
1572 Returns the package name of a stash, or NULL if C<stash> isn't a stash.
1573 See C<SvSTASH>, C<CvSTASH>.
1575 char* HvNAME(HV* stash)
1583 Check that a hash is in an internally consistent state.
1585 void hv_assert(HV* tb)
1593 Clears a hash, making it empty.
1595 void hv_clear(HV* tb)
1600 =item hv_clear_placeholders
1601 X<hv_clear_placeholders>
1603 Clears any placeholders from a hash. If a restricted hash has any of its keys
1604 marked as readonly and the key is subsequently deleted, the key is not actually
1605 deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
1606 it so it will be ignored by future operations such as iterating over the hash,
1607 but will still allow the hash to have a value reassigned to the key at some
1608 future point. This function clears any such placeholder keys from the hash.
1609 See Hash::Util::lock_keys() for an example of its use.
1611 void hv_clear_placeholders(HV* hb)
1619 Deletes a key/value pair in the hash. The value SV is removed from the
1620 hash and returned to the caller. The C<klen> is the length of the key.
1621 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
1624 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
1632 Deletes a key/value pair in the hash. The value SV is removed from the
1633 hash and returned to the caller. The C<flags> value will normally be zero;
1634 if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
1635 precomputed hash value, or 0 to ask for it to be computed.
1637 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
1645 Returns a boolean indicating whether the specified hash key exists. The
1646 C<klen> is the length of the key.
1648 bool hv_exists(HV* tb, const char* key, I32 klen)
1656 Returns a boolean indicating whether the specified hash key exists. C<hash>
1657 can be a valid precomputed hash value, or 0 to ask for it to be
1660 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
1668 Returns the SV which corresponds to the specified key in the hash. The
1669 C<klen> is the length of the key. If C<lval> is set then the fetch will be
1670 part of a store. Check that the return value is non-null before
1671 dereferencing it to an C<SV*>.
1673 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1674 information on how to use this function on tied hashes.
1676 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
1684 Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
1686 SV** hv_fetchs(HV* tb, const char* key, I32 lval)
1689 Found in file handy.h
1694 Returns the hash entry which corresponds to the specified key in the hash.
1695 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
1696 if you want the function to compute it. IF C<lval> is set then the fetch
1697 will be part of a store. Make sure the return value is non-null before
1698 accessing it. The return value when C<tb> is a tied hash is a pointer to a
1699 static location, so be sure to make a copy of the structure if you need to
1702 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1703 information on how to use this function on tied hashes.
1705 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1713 Prepares a starting point to traverse a hash table. Returns the number of
1714 keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
1715 currently only meaningful for hashes without tie magic.
1717 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1718 hash buckets that happen to be in use. If you still need that esoteric
1719 value, you can get it through the macro C<HvFILL(tb)>.
1722 I32 hv_iterinit(HV* tb)
1730 Returns the key from the current position of the hash iterator. See
1733 char* hv_iterkey(HE* entry, I32* retlen)
1741 Returns the key as an C<SV*> from the current position of the hash
1742 iterator. The return value will always be a mortal copy of the key. Also
1745 SV* hv_iterkeysv(HE* entry)
1753 Returns entries from a hash iterator. See C<hv_iterinit>.
1755 You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
1756 iterator currently points to, without losing your place or invalidating your
1757 iterator. Note that in this case the current entry is deleted from the hash
1758 with your iterator holding the last reference to it. Your iterator is flagged
1759 to free the entry on the next call to C<hv_iternext>, so you must not discard
1760 your iterator immediately else the entry will leak - call C<hv_iternext> to
1761 trigger the resource deallocation.
1763 HE* hv_iternext(HV* tb)
1771 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1774 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
1779 =item hv_iternext_flags
1780 X<hv_iternext_flags>
1782 Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
1783 The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
1784 set the placeholders keys (for restricted hashes) will be returned in addition
1785 to normal keys. By default placeholders are automatically skipped over.
1786 Currently a placeholder is implemented with a value that is
1787 C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
1788 restricted hashes may change, and the implementation currently is
1789 insufficiently abstracted for any change to be tidy.
1791 NOTE: this function is experimental and may change or be
1792 removed without notice.
1794 HE* hv_iternext_flags(HV* tb, I32 flags)
1802 Returns the value from the current position of the hash iterator. See
1805 SV* hv_iterval(HV* tb, HE* entry)
1813 Adds magic to a hash. See C<sv_magic>.
1815 void hv_magic(HV* hv, GV* gv, int how)
1823 Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
1825 SV* hv_scalar(HV* hv)
1833 Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1834 the length of the key. The C<hash> parameter is the precomputed hash
1835 value; if it is zero then Perl will compute it. The return value will be
1836 NULL if the operation failed or if the value did not need to be actually
1837 stored within the hash (as in the case of tied hashes). Otherwise it can
1838 be dereferenced to get the original C<SV*>. Note that the caller is
1839 responsible for suitably incrementing the reference count of C<val> before
1840 the call, and decrementing it if the function returned NULL. Effectively
1841 a successful hv_store takes ownership of one reference to C<val>. This is
1842 usually what you want; a newly created SV has a reference count of one, so
1843 if all your code does is create SVs then store them in a hash, hv_store
1844 will own the only reference to the new SV, and your code doesn't need to do
1845 anything further to tidy up. hv_store is not implemented as a call to
1846 hv_store_ent, and does not create a temporary SV for the key, so if your
1847 key data is not already in SV form then use hv_store in preference to
1850 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1851 information on how to use this function on tied hashes.
1853 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
1861 Like C<hv_store>, but takes a literal string instead of a string/length pair
1862 and omits the hash parameter.
1864 SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
1867 Found in file handy.h
1872 Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1873 parameter is the precomputed hash value; if it is zero then Perl will
1874 compute it. The return value is the new hash entry so created. It will be
1875 NULL if the operation failed or if the value did not need to be actually
1876 stored within the hash (as in the case of tied hashes). Otherwise the
1877 contents of the return value can be accessed using the C<He?> macros
1878 described here. Note that the caller is responsible for suitably
1879 incrementing the reference count of C<val> before the call, and
1880 decrementing it if the function returned NULL. Effectively a successful
1881 hv_store_ent takes ownership of one reference to C<val>. This is
1882 usually what you want; a newly created SV has a reference count of one, so
1883 if all your code does is create SVs then store them in a hash, hv_store
1884 will own the only reference to the new SV, and your code doesn't need to do
1885 anything further to tidy up. Note that hv_store_ent only reads the C<key>;
1886 unlike C<val> it does not take ownership of it, so maintaining the correct
1887 reference count on C<key> is entirely the caller's responsibility. hv_store
1888 is not implemented as a call to hv_store_ent, and does not create a temporary
1889 SV for the key, so if your key data is not already in SV form then use
1890 hv_store in preference to hv_store_ent.
1892 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1893 information on how to use this function on tied hashes.
1895 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1905 void hv_undef(HV* tb)
1913 Creates a new HV. The reference count is set to 1.
1923 =head1 Magical Functions
1930 Clear something magical that the SV represents. See C<sv_magic>.
1932 int mg_clear(SV* sv)
1940 Copies the magic from one SV to another. See C<sv_magic>.
1942 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1950 Finds the magic pointer for type matching the SV. See C<sv_magic>.
1952 MAGIC* mg_find(const SV* sv, int type)
1960 Free any magic storage used by the SV. See C<sv_magic>.
1970 Do magic after a value is retrieved from the SV. See C<sv_magic>.
1980 Report on the SV's length. See C<sv_magic>.
1982 U32 mg_length(SV* sv)
1990 Turns on the magical status of an SV. See C<sv_magic>.
1992 void mg_magical(SV* sv)
2000 Do magic after a value is assigned to the SV. See C<sv_magic>.
2010 Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
2011 argument more than once.
2013 void SvGETMAGIC(SV* sv)
2021 Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
2032 Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2033 argument more than once.
2035 void SvSETMAGIC(SV* sv)
2043 Like C<SvSetSV>, but does any set magic required afterwards.
2045 void SvSetMagicSV(SV* dsb, SV* ssv)
2050 =item SvSetMagicSV_nosteal
2051 X<SvSetMagicSV_nosteal>
2053 Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
2055 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2063 Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2066 void SvSetSV(SV* dsb, SV* ssv)
2071 =item SvSetSV_nosteal
2074 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2075 ssv. May evaluate arguments more than once.
2077 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2085 Arranges for sv to be shared between threads if a suitable module
2088 void SvSHARE(SV* sv)
2096 Releases a mutual exclusion lock on sv if a suitable module
2099 void SvUNLOCK(SV* sv)
2107 =head1 Memory Management
2114 The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
2115 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2116 the type. May fail on overlapping copies. See also C<Move>.
2118 void Copy(void* src, void* dest, int nitems, type)
2121 Found in file handy.h
2126 Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
2129 void * CopyD(void* src, void* dest, int nitems, type)
2132 Found in file handy.h
2137 The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
2138 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
2139 the type. Can do overlapping moves. See also C<Copy>.
2141 void Move(void* src, void* dest, int nitems, type)
2144 Found in file handy.h
2149 Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
2152 void * MoveD(void* src, void* dest, int nitems, type)
2155 Found in file handy.h
2160 The XSUB-writer's interface to the C C<malloc> function.
2162 In 5.9.3, Newx() and friends replace the older New() API, and drops
2163 the first parameter, I<x>, a debug aid which allowed callers to identify
2164 themselves. This aid has been superseded by a new build option,
2165 PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>). The older API is still
2166 there for use in XS modules supporting older perls.
2168 void Newx(void* ptr, int nitems, type)
2171 Found in file handy.h
2176 The XSUB-writer's interface to the C C<malloc> function, with
2177 cast. See also C<Newx>.
2179 void Newxc(void* ptr, int nitems, type, cast)
2182 Found in file handy.h
2187 The XSUB-writer's interface to the C C<malloc> function. The allocated
2188 memory is zeroed with C<memzero>. See also C<Newx>.
2190 void Newxz(void* ptr, int nitems, type)
2193 Found in file handy.h
2198 PoisonWith(0xEF) for catching access to freed memory.
2200 void Poison(void* dest, int nitems, type)
2203 Found in file handy.h
2208 PoisonWith(0xEF) for catching access to freed memory.
2210 void PoisonFree(void* dest, int nitems, type)
2213 Found in file handy.h
2218 PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
2220 void PoisonNew(void* dest, int nitems, type)
2223 Found in file handy.h
2228 Fill up memory with a byte pattern (a byte repeated over and over
2229 again) that hopefully catches attempts to access uninitialized memory.
2231 void PoisonWith(void* dest, int nitems, type, U8 byte)
2234 Found in file handy.h
2239 The XSUB-writer's interface to the C C<realloc> function.
2241 void Renew(void* ptr, int nitems, type)
2244 Found in file handy.h
2249 The XSUB-writer's interface to the C C<realloc> function, with
2252 void Renewc(void* ptr, int nitems, type, cast)
2255 Found in file handy.h
2260 The XSUB-writer's interface to the C C<free> function.
2262 void Safefree(void* ptr)
2265 Found in file handy.h
2270 Perl's version of C<strdup()>. Returns a pointer to a newly allocated
2271 string which is a duplicate of C<pv>. The size of the string is
2272 determined by C<strlen()>. The memory allocated for the new string can
2273 be freed with the C<Safefree()> function.
2275 char* savepv(const char* pv)
2278 Found in file util.c
2283 Perl's version of what C<strndup()> would be if it existed. Returns a
2284 pointer to a newly allocated string which is a duplicate of the first
2285 C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
2286 the new string can be freed with the C<Safefree()> function.
2288 char* savepvn(const char* pv, I32 len)
2291 Found in file util.c
2296 Like C<savepvn>, but takes a literal string instead of a string/length pair.
2298 char* savepvs(const char* s)
2301 Found in file handy.h
2306 A version of C<savepv()> which allocates the duplicate string in memory
2307 which is shared between threads.
2309 char* savesharedpv(const char* pv)
2312 Found in file util.c
2317 A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
2318 the passed in SV using C<SvPV()>
2320 char* savesvpv(SV* sv)
2323 Found in file util.c
2328 This is an architecture-independent macro to copy one structure to another.
2330 void StructCopy(type src, type dest, type)
2333 Found in file handy.h
2338 The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
2339 destination, C<nitems> is the number of items, and C<type> is the type.
2341 void Zero(void* dest, int nitems, type)
2344 Found in file handy.h
2349 Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
2352 void * ZeroD(void* dest, int nitems, type)
2355 Found in file handy.h
2360 =head1 Miscellaneous Functions
2367 Analyses the string in order to make fast searches on it using fbm_instr()
2368 -- the Boyer-Moore algorithm.
2370 void fbm_compile(SV* sv, U32 flags)
2373 Found in file util.c
2378 Returns the location of the SV in the string delimited by C<str> and
2379 C<strend>. It returns C<NULL> if the string can't be found. The C<sv>
2380 does not have to be fbm_compiled, but the search will not be as fast
2383 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
2386 Found in file util.c
2391 Takes a sprintf-style format pattern and conventional
2392 (non-SV) arguments and returns the formatted string.
2394 (char *) Perl_form(pTHX_ const char* pat, ...)
2396 can be used any place a string (char *) is required:
2398 char * s = Perl_form("%d.%d",major,minor);
2400 Uses a single private buffer so if you want to format several strings you
2401 must explicitly copy the earlier strings away (and free the copies when you
2404 char* form(const char* pat, ...)
2407 Found in file util.c
2412 Fill the sv with current working directory
2414 int getcwd_sv(SV* sv)
2417 Found in file util.c
2422 The C library C<snprintf> functionality, if available and
2423 standards-compliant (uses C<vsnprintf>, actually). However, if the
2424 C<vsnprintf> is not available, will unfortunately use the unsafe
2425 C<vsprintf> which can overrun the buffer (there is an overrun check,
2426 but that may be too late). Consider using C<sv_vcatpvf> instead, or
2427 getting C<vsnprintf>.
2429 int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
2432 Found in file util.c
2437 The C library C<sprintf>, wrapped if necessary, to ensure that it will return
2438 the length of the string written to the buffer. Only rare pre-ANSI systems
2439 need the wrapper function - usually this is a direct call to C<sprintf>.
2441 int my_sprintf(char *buffer, const char *pat, ...)
2444 Found in file util.c
2449 The C library C<vsnprintf> if available and standards-compliant.
2450 However, if if the C<vsnprintf> is not available, will unfortunately
2451 use the unsafe C<vsprintf> which can overrun the buffer (there is an
2452 overrun check, but that may be too late). Consider using
2453 C<sv_vcatpvf> instead, or getting C<vsnprintf>.
2455 int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
2458 Found in file util.c
2463 Returns a new version object based on the passed in SV:
2465 SV *sv = new_version(SV *ver);
2467 Does not alter the passed in ver SV. See "upg_version" if you
2468 want to upgrade the SV.
2470 SV* new_version(SV *ver)
2473 Found in file util.c
2478 Returns a pointer to the next character after the parsed
2479 version string, as well as upgrading the passed in SV to
2482 Function must be called with an already existing SV like
2485 s = scan_version(s,SV *sv, bool qv);
2487 Performs some preprocessing to the string to ensure that
2488 it has the correct characteristics of a version. Flags the
2489 object if it contains an underscore (which denotes this
2490 is a alpha version). The boolean qv denotes that the version
2491 should be interpreted as if it had multiple decimals, even if
2494 const char* scan_version(const char *vstr, SV *sv, bool qv)
2497 Found in file util.c
2502 Test two strings to see if they are equal. Returns true or false.
2504 bool strEQ(char* s1, char* s2)
2507 Found in file handy.h
2512 Test two strings to see if the first, C<s1>, is greater than or equal to
2513 the second, C<s2>. Returns true or false.
2515 bool strGE(char* s1, char* s2)
2518 Found in file handy.h
2523 Test two strings to see if the first, C<s1>, is greater than the second,
2524 C<s2>. Returns true or false.
2526 bool strGT(char* s1, char* s2)
2529 Found in file handy.h
2534 Test two strings to see if the first, C<s1>, is less than or equal to the
2535 second, C<s2>. Returns true or false.
2537 bool strLE(char* s1, char* s2)
2540 Found in file handy.h
2545 Test two strings to see if the first, C<s1>, is less than the second,
2546 C<s2>. Returns true or false.
2548 bool strLT(char* s1, char* s2)
2551 Found in file handy.h
2556 Test two strings to see if they are different. Returns true or
2559 bool strNE(char* s1, char* s2)
2562 Found in file handy.h
2567 Test two strings to see if they are equal. The C<len> parameter indicates
2568 the number of bytes to compare. Returns true or false. (A wrapper for
2571 bool strnEQ(char* s1, char* s2, STRLEN len)
2574 Found in file handy.h
2579 Test two strings to see if they are different. The C<len> parameter
2580 indicates the number of bytes to compare. Returns true or false. (A
2581 wrapper for C<strncmp>).
2583 bool strnNE(char* s1, char* s2, STRLEN len)
2586 Found in file handy.h
2591 Dummy routine which "shares" an SV when there is no sharing module present.
2592 Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
2593 Exists to avoid test for a NULL function pointer and because it could
2594 potentially warn under some level of strict-ness.
2596 void sv_nosharing(SV *sv)
2599 Found in file util.c
2604 In-place upgrade of the supplied SV to a version object.
2606 SV *sv = upg_version(SV *sv);
2608 Returns a pointer to the upgraded SV.
2610 SV* upg_version(SV *ver)
2613 Found in file util.c
2618 Version object aware cmp. Both operands must already have been
2619 converted into version objects.
2621 int vcmp(SV *lvs, SV *rvs)
2624 Found in file util.c
2629 Accepts a version object and returns the normalized string
2630 representation. Call like:
2634 NOTE: you can pass either the object directly or the SV
2635 contained within the RV.
2640 Found in file util.c
2645 Accepts a version object and returns the normalized floating
2646 point representation. Call like:
2650 NOTE: you can pass either the object directly or the SV
2651 contained within the RV.
2656 Found in file util.c
2661 In order to maintain maximum compatibility with earlier versions
2662 of Perl, this function will return either the floating point
2663 notation or the multiple dotted notation, depending on whether
2664 the original version contained 1 or more dots, respectively
2666 SV* vstringify(SV *vs)
2669 Found in file util.c
2674 Validates that the SV contains a valid version object.
2676 bool vverify(SV *vobj);
2678 Note that it only confirms the bare minimum structure (so as not to get
2679 confused by derived classes which may contain additional hash entries):
2681 bool vverify(SV *vs)
2684 Found in file util.c
2689 =head1 Multicall Functions
2696 Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
2706 Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
2716 Closing bracket for a lightweight callback.
2717 See L<perlcall/Lightweight Callbacks>.
2724 =item PUSH_MULTICALL
2727 Opening bracket for a lightweight callback.
2728 See L<perlcall/Lightweight Callbacks>.
2738 =head1 Numeric functions
2745 converts a string representing a binary number to numeric form.
2747 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2748 conversion flags, and I<result> should be NULL or a pointer to an NV.
2749 The scan stops at the end of the string, or the first invalid character.
2750 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2751 invalid character will also trigger a warning.
2752 On return I<*len> is set to the length of the scanned string,
2753 and I<*flags> gives output flags.
2755 If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
2756 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
2757 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2758 and writes the value to I<*result> (or the value is discarded if I<result>
2761 The binary number may optionally be prefixed with "0b" or "b" unless
2762 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2763 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
2764 number may use '_' characters to separate digits.
2766 UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
2769 Found in file numeric.c
2774 converts a string representing a hex number to numeric form.
2776 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2777 conversion flags, and I<result> should be NULL or a pointer to an NV.
2778 The scan stops at the end of the string, or the first invalid character.
2779 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2780 invalid character will also trigger a warning.
2781 On return I<*len> is set to the length of the scanned string,
2782 and I<*flags> gives output flags.
2784 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2785 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
2786 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2787 and writes the value to I<*result> (or the value is discarded if I<result>
2790 The hex number may optionally be prefixed with "0x" or "x" unless
2791 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
2792 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
2793 number may use '_' characters to separate digits.
2795 UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
2798 Found in file numeric.c
2803 Recognise (or not) a number. The type of the number is returned
2804 (0 if unrecognised), otherwise it is a bit-ORed combination of
2805 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
2806 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
2808 If the value of the number can fit an in UV, it is returned in the *valuep
2809 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
2810 will never be set unless *valuep is valid, but *valuep may have been assigned
2811 to during processing even though IS_NUMBER_IN_UV is not set on return.
2812 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
2813 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
2815 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
2816 seen (in which case *valuep gives the true value truncated to an integer), and
2817 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
2818 absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
2819 number is larger than a UV.
2821 int grok_number(const char *pv, STRLEN len, UV *valuep)
2824 Found in file numeric.c
2826 =item grok_numeric_radix
2827 X<grok_numeric_radix>
2829 Scan and skip for a numeric decimal separator (radix).
2831 bool grok_numeric_radix(const char **sp, const char *send)
2834 Found in file numeric.c
2839 converts a string representing an octal number to numeric form.
2841 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
2842 conversion flags, and I<result> should be NULL or a pointer to an NV.
2843 The scan stops at the end of the string, or the first invalid character.
2844 Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
2845 invalid character will also trigger a warning.
2846 On return I<*len> is set to the length of the scanned string,
2847 and I<*flags> gives output flags.
2849 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
2850 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
2851 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
2852 and writes the value to I<*result> (or the value is discarded if I<result>
2855 If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
2856 number may use '_' characters to separate digits.
2858 UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
2861 Found in file numeric.c
2866 For backwards compatibility. Use C<grok_bin> instead.
2868 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
2871 Found in file numeric.c
2876 For backwards compatibility. Use C<grok_hex> instead.
2878 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
2881 Found in file numeric.c
2886 For backwards compatibility. Use C<grok_oct> instead.
2888 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
2891 Found in file numeric.c
2896 =head1 Optree Manipulation Functions
2903 If C<cv> is a constant sub eligible for inlining. returns the constant
2904 value returned by the sub. Otherwise, returns NULL.
2906 Constant subs can be created with C<newCONSTSUB> or as described in
2907 L<perlsub/"Constant Functions">.
2909 SV* cv_const_sv(CV* cv)
2917 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
2918 eligible for inlining at compile-time.
2920 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
2928 Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
2929 static storage, as it is used directly as CvFILE(), without a copy being made.
2937 =head1 Pad Data Structures
2944 Get the value at offset po in the current pad.
2945 Use macro PAD_SV instead of calling this function directly.
2947 SV* pad_sv(PADOFFSET po)
2955 =head1 Simple Exception Handling Macros
2962 Set up necessary local variables for exception handling.
2963 See L<perlguts/"Exception Handling">.
2968 Found in file XSUB.h
2973 Introduces a catch block. See L<perlguts/"Exception Handling">.
2976 Found in file XSUB.h
2981 Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
2986 Found in file XSUB.h
2991 Ends a try block. See L<perlguts/"Exception Handling">.
2994 Found in file XSUB.h
2996 =item XCPT_TRY_START
2999 Starts a try block. See L<perlguts/"Exception Handling">.
3002 Found in file XSUB.h
3007 =head1 Stack Manipulation Macros
3014 Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
3025 Saves the original stack mark for the XSUB. See C<ORIGMARK>.
3035 Declares a local copy of perl's stack pointer for the XSUB, available via
3036 the C<SP> macro. See C<SP>.
3046 Used to extend the argument stack for an XSUB's return values. Once
3047 used, guarantees that there is room for at least C<nitems> to be pushed
3050 void EXTEND(SP, int nitems)
3058 Stack marker variable for the XSUB. See C<dMARK>.
3066 Push an integer onto the stack. The stack must have room for this element.
3067 Handles 'set' magic. Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi>
3078 Push a double onto the stack. The stack must have room for this element.
3079 Handles 'set' magic. Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn>
3090 Push a string onto the stack. The stack must have room for this element.
3091 The C<len> indicates the length of the string. Handles 'set' magic. Does
3092 not use C<TARG>. See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
3094 void mPUSHp(char* str, STRLEN len)
3102 Push an unsigned integer onto the stack. The stack must have room for this
3103 element. Handles 'set' magic. Does not use C<TARG>. See also C<PUSHu>,
3104 C<mXPUSHu> and C<XPUSHu>.
3114 Push an integer onto the stack, extending the stack if necessary. Handles
3115 'set' magic. Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and
3126 Push a double onto the stack, extending the stack if necessary. Handles
3127 'set' magic. Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and
3138 Push a string onto the stack, extending the stack if necessary. The C<len>
3139 indicates the length of the string. Handles 'set' magic. Does not use
3140 C<TARG>. See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
3142 void mXPUSHp(char* str, STRLEN len)
3150 Push an unsigned integer onto the stack, extending the stack if necessary.
3151 Handles 'set' magic. Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu>
3162 The original stack mark for the XSUB. See C<dORIGMARK>.
3170 Pops an integer off the stack.
3180 Pops a long off the stack.
3190 Pops a double off the stack.
3200 Pops a string off the stack. Deprecated. New code should use POPpx.
3210 Pops a string off the stack which must consist of bytes i.e. characters < 256.
3220 Pops a string off the stack.
3230 Pops an SV off the stack.
3240 Push an integer onto the stack. The stack must have room for this element.
3241 Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3242 called to declare it. Do not call multiple C<TARG>-oriented macros to
3243 return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
3254 Opening bracket for arguments on a callback. See C<PUTBACK> and
3265 Push a new mortal SV onto the stack. The stack must have room for this
3266 element. Does not handle 'set' magic. Does not use C<TARG>. See also
3267 C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
3277 Push a double onto the stack. The stack must have room for this element.
3278 Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3279 called to declare it. Do not call multiple C<TARG>-oriented macros to
3280 return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
3291 Push a string onto the stack. The stack must have room for this element.
3292 The C<len> indicates the length of the string. Handles 'set' magic. Uses
3293 C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
3294 call multiple C<TARG>-oriented macros to return lists from XSUB's - see
3295 C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
3297 void PUSHp(char* str, STRLEN len)
3305 Push an SV onto the stack. The stack must have room for this element.
3306 Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
3307 C<XPUSHs> and C<XPUSHmortal>.
3317 Push an unsigned integer onto the stack. The stack must have room for this
3318 element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
3319 should be called to declare it. Do not call multiple C<TARG>-oriented
3320 macros to return lists from XSUB's - see C<mPUSHu> instead. See also
3321 C<XPUSHu> and C<mXPUSHu>.
3331 Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
3332 See C<PUSHMARK> and L<perlcall> for other uses.
3342 Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
3351 Refetch the stack pointer. Used after a callback. See L<perlcall>.
3361 Push an integer onto the stack, extending the stack if necessary. Handles
3362 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3363 declare it. Do not call multiple C<TARG>-oriented macros to return lists
3364 from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
3374 Push a new mortal SV onto the stack, extending the stack if necessary. Does
3375 not handle 'set' magic. Does not use C<TARG>. See also C<XPUSHs>,
3376 C<PUSHmortal> and C<PUSHs>.
3386 Push a double onto the stack, extending the stack if necessary. Handles
3387 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
3388 declare it. Do not call multiple C<TARG>-oriented macros to return lists
3389 from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
3399 Push a string onto the stack, extending the stack if necessary. The C<len>
3400 indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
3401 C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
3402 multiple C<TARG>-oriented macros to return lists from XSUB's - see
3403 C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
3405 void XPUSHp(char* str, STRLEN len)
3413 Push an SV onto the stack, extending the stack if necessary. Does not
3414 handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
3415 C<PUSHs> and C<PUSHmortal>.
3425 Push an unsigned integer onto the stack, extending the stack if necessary.
3426 Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
3427 called to declare it. Do not call multiple C<TARG>-oriented macros to
3428 return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
3439 Return from XSUB, indicating number of items on the stack. This is usually
3440 handled by C<xsubpp>.
3442 void XSRETURN(int nitems)
3445 Found in file XSUB.h
3447 =item XSRETURN_EMPTY
3450 Return an empty list from an XSUB immediately.
3455 Found in file XSUB.h
3460 Return an integer from an XSUB immediately. Uses C<XST_mIV>.
3462 void XSRETURN_IV(IV iv)
3465 Found in file XSUB.h
3470 Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
3475 Found in file XSUB.h
3480 Return a double from an XSUB immediately. Uses C<XST_mNV>.
3482 void XSRETURN_NV(NV nv)
3485 Found in file XSUB.h
3490 Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
3492 void XSRETURN_PV(char* str)
3495 Found in file XSUB.h
3497 =item XSRETURN_UNDEF
3500 Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
3505 Found in file XSUB.h
3510 Return an integer from an XSUB immediately. Uses C<XST_mUV>.
3512 void XSRETURN_UV(IV uv)
3515 Found in file XSUB.h
3520 Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
3525 Found in file XSUB.h
3530 Place an integer into the specified position C<pos> on the stack. The
3531 value is stored in a new mortal SV.
3533 void XST_mIV(int pos, IV iv)
3536 Found in file XSUB.h
3541 Place C<&PL_sv_no> into the specified position C<pos> on the
3544 void XST_mNO(int pos)
3547 Found in file XSUB.h
3552 Place a double into the specified position C<pos> on the stack. The value
3553 is stored in a new mortal SV.
3555 void XST_mNV(int pos, NV nv)
3558 Found in file XSUB.h
3563 Place a copy of a string into the specified position C<pos> on the stack.
3564 The value is stored in a new mortal SV.
3566 void XST_mPV(int pos, char* str)
3569 Found in file XSUB.h
3574 Place C<&PL_sv_undef> into the specified position C<pos> on the
3577 void XST_mUNDEF(int pos)
3580 Found in file XSUB.h
3585 Place C<&PL_sv_yes> into the specified position C<pos> on the
3588 void XST_mYES(int pos)
3591 Found in file XSUB.h
3603 An enum of flags for Perl types. These are found in the file B<sv.h>
3604 in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
3612 Integer type flag for scalars. See C<svtype>.
3620 Double type flag for scalars. See C<svtype>.
3628 Pointer type flag for scalars. See C<svtype>.
3636 Type flag for arrays. See C<svtype>.
3644 Type flag for code refs. See C<svtype>.
3652 Type flag for hashes. See C<svtype>.
3660 Type flag for blessed scalars. See C<svtype>.
3668 =head1 SV Manipulation Functions
3675 Returns the SV of the specified Perl scalar. If C<create> is set and the
3676 Perl variable does not exist then it will be created. If C<create> is not
3677 set and the variable does not exist then NULL is returned.
3679 NOTE: the perl_ form of this function is deprecated.
3681 SV* get_sv(const char* name, I32 create)
3684 Found in file perl.c
3689 Creates an RV wrapper for an SV. The reference count for the original SV is
3692 SV* newRV_inc(SV* sv)
3700 Returns the length of the string which is in the SV. See C<SvLEN>.
3702 STRLEN SvCUR(SV* sv)
3710 Set the current length of the string which is in the SV. See C<SvCUR>
3713 void SvCUR_set(SV* sv, STRLEN len)
3721 Returns a pointer to the last character in the string which is in the SV.
3722 See C<SvCUR>. Access the character as *(SvEND(sv)).
3732 Returns true if the SV has get magic or overloading. If either is true then
3733 the scalar is active data, and has the potential to return a new value every
3734 time it is accessed. Hence you must be careful to only read it once per user
3735 logical operation and work with that returned value. If neither is true then
3736 the scalar's value cannot change unless written to.
3738 char* SvGAMAGIC(SV* sv)
3746 Expands the character buffer in the SV so that it has room for the
3747 indicated number of bytes (remember to reserve space for an extra trailing
3748 NUL character). Calls C<sv_grow> to perform the expansion if necessary.
3749 Returns a pointer to the character buffer.
3751 char * SvGROW(SV* sv, STRLEN len)
3759 Returns a boolean indicating whether the SV contains an integer.
3769 Returns a boolean indicating whether the SV contains an integer. Checks
3770 the B<private> setting. Use C<SvIOK>.
3780 Returns a boolean indicating whether the SV contains a signed integer.
3782 bool SvIOK_notUV(SV* sv)
3790 Unsets the IV status of an SV.
3792 void SvIOK_off(SV* sv)
3800 Tells an SV that it is an integer.
3802 void SvIOK_on(SV* sv)
3810 Tells an SV that it is an integer and disables all other OK bits.
3812 void SvIOK_only(SV* sv)
3820 Tells and SV that it is an unsigned integer and disables all other OK bits.
3822 void SvIOK_only_UV(SV* sv)
3830 Returns a boolean indicating whether the SV contains an unsigned integer.
3832 bool SvIOK_UV(SV* sv)
3840 Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
3841 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
3844 bool SvIsCOW(SV* sv)
3849 =item SvIsCOW_shared_hash
3850 X<SvIsCOW_shared_hash>
3852 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
3855 bool SvIsCOW_shared_hash(SV* sv)
3863 Coerces the given SV to an integer and returns it. See C<SvIVx> for a
3864 version which guarantees to evaluate sv only once.
3874 Returns the raw value in the SV's IV slot, without checks or conversions.
3875 Only use when you are sure SvIOK is true. See also C<SvIV()>.
3885 Coerces the given SV to an integer and returns it. Guarantees to evaluate
3886 sv only once. Use the more efficient C<SvIV> otherwise.
3896 Like C<SvIV> but doesn't process magic.
3898 IV SvIV_nomg(SV* sv)
3906 Set the value of the IV pointer in sv to val. It is possible to perform
3907 the same function of this macro with an lvalue assignment to C<SvIVX>.
3908 With future Perls, however, it will be more efficient to use
3909 C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
3911 void SvIV_set(SV* sv, IV val)
3919 Returns the size of the string buffer in the SV, not including any part
3920 attributable to C<SvOOK>. See C<SvCUR>.
3922 STRLEN SvLEN(SV* sv)
3930 Set the actual length of the string which is in the SV. See C<SvIV_set>.
3932 void SvLEN_set(SV* sv, STRLEN len)
3940 Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>.
3942 void SvMAGIC_set(SV* sv, MAGIC* val)
3950 Returns a boolean indicating whether the SV contains a number, integer or
3961 Returns a boolean indicating whether the SV contains a number, integer or
3962 double. Checks the B<private> setting. Use C<SvNIOK>.
3964 bool SvNIOKp(SV* sv)
3972 Unsets the NV/IV status of an SV.
3974 void SvNIOK_off(SV* sv)
3982 Returns a boolean indicating whether the SV contains a double.
3992 Returns a boolean indicating whether the SV contains a double. Checks the
3993 B<private> setting. Use C<SvNOK>.
4003 Unsets the NV status of an SV.
4005 void SvNOK_off(SV* sv)
4013 Tells an SV that it is a double.
4015 void SvNOK_on(SV* sv)
4023 Tells an SV that it is a double and disables all other OK bits.
4025 void SvNOK_only(SV* sv)
4033 Coerce the given SV to a double and return it. See C<SvNVx> for a version
4034 which guarantees to evaluate sv only once.
4044 Returns the raw value in the SV's NV slot, without checks or conversions.
4045 Only use when you are sure SvNOK is true. See also C<SvNV()>.
4055 Coerces the given SV to a double and returns it. Guarantees to evaluate
4056 sv only once. Use the more efficient C<SvNV> otherwise.
4066 Set the value of the NV pointer in sv to val. See C<SvIV_set>.
4068 void SvNV_set(SV* sv, NV val)
4076 Returns a boolean indicating whether the value is an SV. It also tells
4077 whether the value is defined or not.
4087 Returns a boolean indicating whether the SvIVX is a valid offset value for
4088 the SvPVX. This hack is used internally to speed up removal of characters
4089 from the beginning of a SvPV. When SvOOK is true, then the start of the
4090 allocated string buffer is really (SvPVX - SvIVX).
4100 Returns a boolean indicating whether the SV contains a character
4111 Returns a boolean indicating whether the SV contains a character string.
4112 Checks the B<private> setting. Use C<SvPOK>.
4122 Unsets the PV status of an SV.
4124 void SvPOK_off(SV* sv)
4132 Tells an SV that it is a string.
4134 void SvPOK_on(SV* sv)
4142 Tells an SV that it is a string and disables all other OK bits.
4143 Will also turn off the UTF-8 status.
4145 void SvPOK_only(SV* sv)
4150 =item SvPOK_only_UTF8
4153 Tells an SV that it is a string and disables all other OK bits,
4154 and leaves the UTF-8 status as it was.
4156 void SvPOK_only_UTF8(SV* sv)
4164 Returns a pointer to the string in the SV, or a stringified form of
4165 the SV if the SV does not contain a string. The SV may cache the
4166 stringified version becoming C<SvPOK>. Handles 'get' magic. See also
4167 C<SvPVx> for a version which guarantees to evaluate sv only once.
4169 char* SvPV(SV* sv, STRLEN len)
4177 Like C<SvPV>, but converts sv to byte representation first if necessary.
4179 char* SvPVbyte(SV* sv, STRLEN len)
4187 Like C<SvPV>, but converts sv to byte representation first if necessary.
4188 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
4191 char* SvPVbytex(SV* sv, STRLEN len)
4196 =item SvPVbytex_force
4199 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4200 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
4203 char* SvPVbytex_force(SV* sv, STRLEN len)
4208 =item SvPVbyte_force
4211 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
4213 char* SvPVbyte_force(SV* sv, STRLEN len)
4218 =item SvPVbyte_nolen
4221 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
4223 char* SvPVbyte_nolen(SV* sv)
4231 Like C<SvPV>, but converts sv to utf8 first if necessary.
4233 char* SvPVutf8(SV* sv, STRLEN len)
4241 Like C<SvPV>, but converts sv to utf8 first if necessary.
4242 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
4245 char* SvPVutf8x(SV* sv, STRLEN len)
4250 =item SvPVutf8x_force
4253 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4254 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
4257 char* SvPVutf8x_force(SV* sv, STRLEN len)
4262 =item SvPVutf8_force
4265 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
4267 char* SvPVutf8_force(SV* sv, STRLEN len)
4272 =item SvPVutf8_nolen
4275 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
4277 char* SvPVutf8_nolen(SV* sv)
4285 Returns a pointer to the physical string in the SV. The SV must contain a
4296 A version of C<SvPV> which guarantees to evaluate sv only once.
4298 char* SvPVx(SV* sv, STRLEN len)
4306 Like C<SvPV> but will force the SV into containing just a string
4307 (C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
4310 char* SvPV_force(SV* sv, STRLEN len)
4315 =item SvPV_force_nomg
4318 Like C<SvPV> but will force the SV into containing just a string
4319 (C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
4320 directly. Doesn't process magic.
4322 char* SvPV_force_nomg(SV* sv, STRLEN len)
4330 Returns a pointer to the string in the SV, or a stringified form of
4331 the SV if the SV does not contain a string. The SV may cache the
4332 stringified form becoming C<SvPOK>. Handles 'get' magic.
4334 char* SvPV_nolen(SV* sv)
4342 Like C<SvPV> but doesn't process magic.
4344 char* SvPV_nomg(SV* sv, STRLEN len)
4352 Set the value of the PV pointer in sv to val. See C<SvIV_set>.
4354 void SvPV_set(SV* sv, char* val)
4362 Returns the value of the object's reference count.
4364 U32 SvREFCNT(SV* sv)
4372 Decrements the reference count of the given SV.
4374 void SvREFCNT_dec(SV* sv)
4382 Increments the reference count of the given SV.
4384 All of the following SvREFCNT_inc* macros are optimized versions of
4385 SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
4387 SV* SvREFCNT_inc(SV* sv)
4392 =item SvREFCNT_inc_NN
4395 Same as SvREFCNT_inc, but can only be used if you know I<sv>
4396 is not NULL. Since we don't have to check the NULLness, it's faster
4399 SV* SvREFCNT_inc_NN(SV* sv)
4404 =item SvREFCNT_inc_simple
4405 X<SvREFCNT_inc_simple>
4407 Same as SvREFCNT_inc, but can only be used with simple variables, not
4408 expressions or pointer dereferences. Since we don't have to store a
4409 temporary value, it's faster.
4411 SV* SvREFCNT_inc_simple(SV* sv)
4416 =item SvREFCNT_inc_simple_NN
4417 X<SvREFCNT_inc_simple_NN>
4419 Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
4420 is not NULL. Since we don't have to check the NULLness, it's faster
4423 SV* SvREFCNT_inc_simple_NN(SV* sv)
4428 =item SvREFCNT_inc_simple_void
4429 X<SvREFCNT_inc_simple_void>
4431 Same as SvREFCNT_inc_simple, but can only be used if you don't need the
4432 return value. The macro doesn't need to return a meaningful value.
4434 void SvREFCNT_inc_simple_void(SV* sv)
4439 =item SvREFCNT_inc_simple_void_NN
4440 X<SvREFCNT_inc_simple_void_NN>
4442 Same as SvREFCNT_inc, but can only be used if you don't need the return
4443 value, and you know that I<sv> is not NULL. The macro doesn't need
4444 to return a meaningful value, or check for NULLness, so it's smaller
4447 void SvREFCNT_inc_simple_void_NN(SV* sv)
4452 =item SvREFCNT_inc_void
4453 X<SvREFCNT_inc_void>
4455 Same as SvREFCNT_inc, but can only be used if you don't need the
4456 return value. The macro doesn't need to return a meaningful value.
4458 void SvREFCNT_inc_void(SV* sv)
4463 =item SvREFCNT_inc_void_NN
4464 X<SvREFCNT_inc_void_NN>
4466 Same as SvREFCNT_inc, but can only be used if you don't need the return
4467 value, and you know that I<sv> is not NULL. The macro doesn't need
4468 to return a meaningful value, or check for NULLness, so it's smaller
4471 void SvREFCNT_inc_void_NN(SV* sv)
4479 Tests if the SV is an RV.
4489 Unsets the RV status of an SV.
4491 void SvROK_off(SV* sv)
4499 Tells an SV that it is an RV.
4501 void SvROK_on(SV* sv)
4509 Dereferences an RV to return the SV.
4519 Set the value of the RV pointer in sv to val. See C<SvIV_set>.
4521 void SvRV_set(SV* sv, SV* val)
4529 Returns the stash of the SV.
4539 Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
4541 void SvSTASH_set(SV* sv, HV* val)
4549 Taints an SV if tainting is enabled.
4551 void SvTAINT(SV* sv)
4559 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
4562 bool SvTAINTED(SV* sv)
4570 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
4571 some of Perl's fundamental security features. XS module authors should not
4572 use this function unless they fully understand all the implications of
4573 unconditionally untainting the value. Untainting should be done in the
4574 standard perl fashion, via a carefully crafted regexp, rather than directly
4575 untainting variables.
4577 void SvTAINTED_off(SV* sv)
4585 Marks an SV as tainted if tainting is enabled.
4587 void SvTAINTED_on(SV* sv)
4595 Returns a boolean indicating whether Perl would evaluate the SV as true or
4596 false, defined or undefined. Does not handle 'get' magic.
4606 Returns the type of the SV. See C<svtype>.
4608 svtype SvTYPE(SV* sv)
4616 Returns a boolean indicating whether the SV contains an unsigned integer.
4626 Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
4627 perform the upgrade if necessary. See C<svtype>.
4629 void SvUPGRADE(SV* sv, svtype type)
4637 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
4638 Call this after SvPV() in case any call to string overloading updates the
4649 Unsets the UTF-8 status of an SV.
4651 void SvUTF8_off(SV *sv)
4659 Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
4660 Do not use frivolously.
4662 void SvUTF8_on(SV *sv)
4670 Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
4671 for a version which guarantees to evaluate sv only once.
4681 Returns the raw value in the SV's UV slot, without checks or conversions.
4682 Only use when you are sure SvIOK is true. See also C<SvUV()>.
4692 Coerces the given SV to an unsigned integer and returns it. Guarantees to
4693 evaluate sv only once. Use the more efficient C<SvUV> otherwise.
4703 Like C<SvUV> but doesn't process magic.
4705 UV SvUV_nomg(SV* sv)
4713 Set the value of the UV pointer in sv to val. See C<SvIV_set>.
4715 void SvUV_set(SV* sv, UV val)
4723 Returns a boolean indicating whether the SV contains a v-string.
4730 =item sv_catpvn_nomg
4733 Like C<sv_catpvn> but doesn't process magic.
4735 void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
4743 Like C<sv_catsv> but doesn't process magic.
4745 void sv_catsv_nomg(SV* dsv, SV* ssv)
4750 =item sv_derived_from
4753 Returns a boolean indicating whether the SV is derived from the specified class
4754 I<at the C level>. To check derivation at the Perl level, call C<isa()> as a
4757 bool sv_derived_from(SV* sv, const char* name)
4760 Found in file universal.c
4765 Returns a boolean indicating whether the SV performs a specific, named role.
4766 The SV can be a Perl object or the name of a Perl class.
4768 bool sv_does(SV* sv, const char* name)
4771 Found in file universal.c
4773 =item sv_report_used
4776 Dump the contents of all SVs not yet freed. (Debugging aid).
4778 void sv_report_used()
4786 Like C<sv_setsv> but doesn't process magic.
4788 void sv_setsv_nomg(SV* dsv, SV* ssv)
4796 =head1 SV-Body Allocation
4800 =item looks_like_number
4801 X<looks_like_number>
4803 Test if the content of an SV looks like a number (or is a number).
4804 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
4805 non-numeric warning), even if your atof() doesn't grok them.
4807 I32 looks_like_number(SV* sv)
4815 Creates an RV wrapper for an SV. The reference count for the original
4816 SV is B<not> incremented.
4818 SV* newRV_noinc(SV* sv)
4826 Creates a new SV. A non-zero C<len> parameter indicates the number of
4827 bytes of preallocated string space the SV should have. An extra byte for a
4828 trailing NUL is also reserved. (SvPOK is not set for the SV even if string
4829 space is allocated.) The reference count for the new SV is set to 1.
4831 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
4832 parameter, I<x>, a debug aid which allowed callers to identify themselves.
4833 This aid has been superseded by a new build option, PERL_MEM_LOG (see
4834 L<perlhack/PERL_MEM_LOG>). The older API is still there for use in XS
4835 modules supporting older perls.
4837 SV* newSV(STRLEN len)
4845 Creates a new SV from the hash key structure. It will generate scalars that
4846 point to the shared string table where possible. Returns a new (undefined)
4847 SV if the hek is NULL.
4849 SV* newSVhek(const HEK *hek)
4857 Creates a new SV and copies an integer into it. The reference count for the
4868 Creates a new SV and copies a floating point value into it.
4869 The reference count for the SV is set to 1.
4879 Creates a new SV and copies a string into it. The reference count for the
4880 SV is set to 1. If C<len> is zero, Perl will compute the length using
4881 strlen(). For efficiency, consider using C<newSVpvn> instead.
4883 SV* newSVpv(const char* s, STRLEN len)
4891 Creates a new SV and initializes it with the string formatted like
4894 SV* newSVpvf(const char* pat, ...)
4902 Creates a new SV and copies a string into it. The reference count for the
4903 SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
4904 string. You are responsible for ensuring that the source string is at least
4905 C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
4907 SV* newSVpvn(const char* s, STRLEN len)
4912 =item newSVpvn_share
4915 Creates a new SV with its SvPVX_const pointing to a shared string in the string
4916 table. If the string does not already exist in the table, it is created
4917 first. Turns on READONLY and FAKE. The string's hash is stored in the UV
4918 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
4919 otherwise the hash is computed. The idea here is that as the string table
4920 is used for shared hash keys these strings will have SvPVX_const == HeKEY and
4921 hash lookup will avoid string compare.
4923 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
4931 Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
4933 SV* newSVpvs(const char* s)
4936 Found in file handy.h
4938 =item newSVpvs_share
4941 Like C<newSVpvn_share>, but takes a literal string instead of a string/length
4942 pair and omits the hash parameter.
4944 SV* newSVpvs_share(const char* s)
4947 Found in file handy.h
4952 Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
4953 it will be upgraded to one. If C<classname> is non-null then the new SV will
4954 be blessed in the specified package. The new SV is returned and its
4955 reference count is 1.
4957 SV* newSVrv(SV* rv, const char* classname)
4965 Creates a new SV which is an exact duplicate of the original SV.
4968 SV* newSVsv(SV* old)
4976 Creates a new SV and copies an unsigned integer into it.
4977 The reference count for the SV is set to 1.
4987 This function is only called on magical items, and is only used by
4988 sv_true() or its macro equivalent.
4990 bool sv_2bool(SV* sv)
4998 Using various gambits, try to get a CV from an SV; in addition, try if
4999 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
5000 The flags in C<lref> are passed to sv_fetchsv.
5002 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
5010 Using various gambits, try to get an IO from an SV: the IO slot if its a
5011 GV; or the recursive result if we're an RV; or the IO slot of the symbol
5012 named after the PV if we're a string.
5022 Return the integer value of an SV, doing any necessary string
5023 conversion. If flags includes SV_GMAGIC, does an mg_get() first.
5024 Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
5026 IV sv_2iv_flags(SV* sv, I32 flags)
5034 Marks an existing SV as mortal. The SV will be destroyed "soon", either
5035 by an explicit call to FREETMPS, or by an implicit call at places such as
5036 statement boundaries. SvTEMP() is turned on which means that the SV's
5037 string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
5038 and C<sv_mortalcopy>.
5040 SV* sv_2mortal(SV* sv)
5048 Return the num value of an SV, doing any necessary string or integer
5049 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
5060 Return a pointer to the byte-encoded representation of the SV, and set *lp
5061 to its length. May cause the SV to be downgraded from UTF-8 as a
5064 Usually accessed via the C<SvPVbyte> macro.
5066 char* sv_2pvbyte(SV* sv, STRLEN* lp)
5074 Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
5075 to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.
5077 Usually accessed via the C<SvPVutf8> macro.
5079 char* sv_2pvutf8(SV* sv, STRLEN* lp)
5087 Returns a pointer to the string value of an SV, and sets *lp to its length.
5088 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
5090 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
5091 usually end up here too.
5093 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
5101 Return the unsigned integer value of an SV, doing any necessary string
5102 conversion. If flags includes SV_GMAGIC, does an mg_get() first.
5103 Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
5105 UV sv_2uv_flags(SV* sv, I32 flags)
5113 Remove any string offset. You should normally use the C<SvOOK_off> macro
5116 int sv_backoff(SV* sv)
5124 Blesses an SV into a specified package. The SV must be an RV. The package
5125 must be designated by its stash (see C<gv_stashpv()>). The reference count
5126 of the SV is unaffected.
5128 SV* sv_bless(SV* sv, HV* stash)
5136 Concatenates the string onto the end of the string which is in the SV.
5137 If the SV has the UTF-8 status set, then the bytes appended should be
5138 valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
5140 void sv_catpv(SV* sv, const char* ptr)
5148 Processes its arguments like C<sprintf> and appends the formatted
5149 output to an SV. If the appended data contains "wide" characters
5150 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
5151 and characters >255 formatted with %c), the original SV might get
5152 upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See
5153 C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
5154 valid UTF-8; if the original SV was bytes, the pattern should be too.
5156 void sv_catpvf(SV* sv, const char* pat, ...)
5164 Like C<sv_catpvf>, but also handles 'set' magic.
5166 void sv_catpvf_mg(SV *sv, const char* pat, ...)
5174 Concatenates the string onto the end of the string which is in the SV. The
5175 C<len> indicates number of bytes to copy. If the SV has the UTF-8
5176 status set, then the bytes appended should be valid UTF-8.
5177 Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
5179 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
5184 =item sv_catpvn_flags
5187 Concatenates the string onto the end of the string which is in the SV. The
5188 C<len> indicates number of bytes to copy. If the SV has the UTF-8
5189 status set, then the bytes appended should be valid UTF-8.
5190 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
5191 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
5192 in terms of this function.
5194 void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
5202 Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
5204 void sv_catpvs(SV* sv, const char* s)
5207 Found in file handy.h
5212 Like C<sv_catpv>, but also handles 'set' magic.
5214 void sv_catpv_mg(SV *sv, const char *ptr)
5222 Concatenates the string from SV C<ssv> onto the end of the string in
5223 SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
5224 not 'set' magic. See C<sv_catsv_mg>.
5226 void sv_catsv(SV* dsv, SV* ssv)
5231 =item sv_catsv_flags
5234 Concatenates the string from SV C<ssv> onto the end of the string in
5235 SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
5236 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
5237 and C<sv_catsv_nomg> are implemented in terms of this function.
5239 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
5247 Efficient removal of characters from the beginning of the string buffer.
5248 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
5249 the string buffer. The C<ptr> becomes the first character of the adjusted
5250 string. Uses the "OOK hack".
5251 Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
5252 refer to the same chunk of data.
5254 void sv_chop(SV* sv, const char* ptr)
5262 Clear an SV: call any destructors, free up any memory used by the body,
5263 and free the body itself. The SV's head is I<not> freed, although
5264 its type is set to all 1's so that it won't inadvertently be assumed
5265 to be live during global destruction etc.
5266 This function should only be called when REFCNT is zero. Most of the time
5267 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
5270 void sv_clear(SV* sv)
5278 Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
5279 string in C<sv1> is less than, equal to, or greater than the string in
5280 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5281 coerce its args to strings if necessary. See also C<sv_cmp_locale>.
5283 I32 sv_cmp(SV* sv1, SV* sv2)
5291 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
5292 'use bytes' aware, handles get magic, and will coerce its args to strings
5293 if necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>.
5295 I32 sv_cmp_locale(SV* sv1, SV* sv2)
5303 Add Collate Transform magic to an SV if it doesn't already have it.
5305 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
5306 scalar data of the variable, but transformed to such a format that a normal
5307 memory comparison can be used to compare the data according to the locale
5310 char* sv_collxfrm(SV* sv, STRLEN* nxp)
5318 Copies a stringified representation of the source SV into the
5319 destination SV. Automatically performs any necessary mg_get and
5320 coercion of numeric values into strings. Guaranteed to preserve
5321 UTF-8 flag even from overloaded objects. Similar in nature to
5322 sv_2pv[_flags] but operates directly on an SV instead of just the
5323 string. Mostly uses sv_2pv_flags to do its work, except when that
5324 would lose the UTF-8'ness of the PV.
5326 void sv_copypv(SV* dsv, SV* ssv)
5334 Auto-decrement of the value in the SV, doing string to numeric conversion
5335 if necessary. Handles 'get' magic.
5345 Returns a boolean indicating whether the strings in the two SVs are
5346 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
5347 coerce its args to strings if necessary.
5349 I32 sv_eq(SV* sv1, SV* sv2)
5354 =item sv_force_normal_flags
5355 X<sv_force_normal_flags>
5357 Undo various types of fakery on an SV: if the PV is a shared string, make
5358 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
5359 an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
5360 we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
5361 then a copy-on-write scalar drops its PV buffer (if any) and becomes
5362 SvPOK_off rather than making a copy. (Used where this scalar is about to be
5363 set to some other value.) In addition, the C<flags> parameter gets passed to
5364 C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
5365 with flags set to 0.
5367 void sv_force_normal_flags(SV *sv, U32 flags)
5375 Decrement an SV's reference count, and if it drops to zero, call
5376 C<sv_clear> to invoke destructors and free up any memory used by
5377 the body; finally, deallocate the SV's head itself.
5378 Normally called via a wrapper macro C<SvREFCNT_dec>.
5380 void sv_free(SV* sv)
5388 Get a line from the filehandle and store it into the SV, optionally
5389 appending to the currently-stored string.
5391 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
5399 Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
5400 upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
5401 Use the C<SvGROW> wrapper instead.
5403 char* sv_grow(SV* sv, STRLEN newlen)
5411 Auto-increment of the value in the SV, doing string to numeric conversion
5412 if necessary. Handles 'get' magic.
5422 Inserts a string at the specified offset/length within the SV. Similar to
5423 the Perl substr() function.
5425 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, const char* little, STRLEN littlelen)
5433 Returns a boolean indicating whether the SV is blessed into the specified
5434 class. This does not check for subtypes; use C<sv_derived_from> to verify
5435 an inheritance relationship.
5437 int sv_isa(SV* sv, const char* name)
5445 Returns a boolean indicating whether the SV is an RV pointing to a blessed
5446 object. If the SV is not an RV, or if the object is not blessed, then this
5449 int sv_isobject(SV* sv)
5457 Returns the length of the string in the SV. Handles magic and type
5458 coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
5460 STRLEN sv_len(SV* sv)
5468 Returns the number of characters in the string in an SV, counting wide
5469 UTF-8 bytes as a single character. Handles magic and type coercion.
5471 STRLEN sv_len_utf8(SV* sv)
5479 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
5480 then adds a new magic item of type C<how> to the head of the magic list.
5482 See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
5483 handling of the C<name> and C<namlen> arguments.
5485 You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
5486 to add more than one instance of the same 'how'.
5488 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
5496 Adds magic to an SV, upgrading it if necessary. Applies the
5497 supplied vtable and returns a pointer to the magic added.
5499 Note that C<sv_magicext> will allow things that C<sv_magic> will not.
5500 In particular, you can add magic to SvREADONLY SVs, and add more than
5501 one instance of the same 'how'.
5503 If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
5504 stored, if C<namlen> is zero then C<name> is stored as-is and - as another
5505 special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
5506 to contain an C<SV*> and is stored as-is with its REFCNT incremented.
5508 (This is now used as a subroutine by C<sv_magic>.)
5510 MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen)
5518 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
5519 The new SV is marked as mortal. It will be destroyed "soon", either by an
5520 explicit call to FREETMPS, or by an implicit call at places such as
5521 statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
5523 SV* sv_mortalcopy(SV* oldsv)
5531 Creates a new null SV which is mortal. The reference count of the SV is
5532 set to 1. It will be destroyed "soon", either by an explicit call to
5533 FREETMPS, or by an implicit call at places such as statement boundaries.
5534 See also C<sv_mortalcopy> and C<sv_2mortal>.
5544 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
5547 SV* sv_newref(SV* sv)
5555 Converts the value pointed to by offsetp from a count of bytes from the
5556 start of the string, to a count of the equivalent number of UTF-8 chars.
5557 Handles magic and type coercion.
5559 void sv_pos_b2u(SV* sv, I32* offsetp)
5567 Converts the value pointed to by offsetp from a count of UTF-8 chars from
5568 the start of the string, to a count of the equivalent number of bytes; if
5569 lenp is non-zero, it does the same to lenp, but this time starting from
5570 the offset, rather than from the start of the string. Handles magic and
5573 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
5578 =item sv_pvbyten_force
5581 The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
5583 char* sv_pvbyten_force(SV* sv, STRLEN* lp)
5591 Get a sensible string out of the SV somehow.
5592 A private implementation of the C<SvPV_force> macro for compilers which
5593 can't cope with complex macro expressions. Always use the macro instead.
5595 char* sv_pvn_force(SV* sv, STRLEN* lp)
5600 =item sv_pvn_force_flags
5601 X<sv_pvn_force_flags>
5603 Get a sensible string out of the SV somehow.
5604 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
5605 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
5606 implemented in terms of this function.
5607 You normally want to use the various wrapper macros instead: see
5608 C<SvPV_force> and C<SvPV_force_nomg>
5610 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
5615 =item sv_pvutf8n_force
5618 The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
5620 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
5628 Returns a string describing what the SV is a reference to.
5630 const char* sv_reftype(const SV* sv, int ob)
5638 Make the first argument a copy of the second, then delete the original.
5639 The target SV physically takes over ownership of the body of the source SV
5640 and inherits its flags; however, the target keeps any magic it owns,
5641 and any magic in the source is discarded.
5642 Note that this is a rather specialist SV copying operation; most of the
5643 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
5645 void sv_replace(SV* sv, SV* nsv)
5653 Underlying implementation for the C<reset> Perl function.
5654 Note that the perl-level function is vaguely deprecated.
5656 void sv_reset(const char* s, HV* stash)
5664 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
5665 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
5666 push a back-reference to this RV onto the array of backreferences
5667 associated with that magic. If the RV is magical, set magic will be
5668 called after the RV is cleared.
5670 SV* sv_rvweaken(SV *sv)
5678 Copies an integer into the given SV, upgrading first if necessary.
5679 Does not handle 'set' magic. See also C<sv_setiv_mg>.
5681 void sv_setiv(SV* sv, IV num)
5689 Like C<sv_setiv>, but also handles 'set' magic.
5691 void sv_setiv_mg(SV *sv, IV i)
5699 Copies a double into the given SV, upgrading first if necessary.
5700 Does not handle 'set' magic. See also C<sv_setnv_mg>.
5702 void sv_setnv(SV* sv, NV num)
5710 Like C<sv_setnv>, but also handles 'set' magic.
5712 void sv_setnv_mg(SV *sv, NV num)
5720 Copies a string into an SV. The string must be null-terminated. Does not
5721 handle 'set' magic. See C<sv_setpv_mg>.
5723 void sv_setpv(SV* sv, const char* ptr)
5731 Works like C<sv_catpvf> but copies the text into the SV instead of
5732 appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>.
5734 void sv_setpvf(SV* sv, const char* pat, ...)
5742 Like C<sv_setpvf>, but also handles 'set' magic.
5744 void sv_setpvf_mg(SV *sv, const char* pat, ...)
5752 Copies an integer into the given SV, also updating its string value.
5753 Does not handle 'set' magic. See C<sv_setpviv_mg>.
5755 void sv_setpviv(SV* sv, IV num)
5763 Like C<sv_setpviv>, but also handles 'set' magic.
5765 void sv_setpviv_mg(SV *sv, IV iv)
5773 Copies a string into an SV. The C<len> parameter indicates the number of
5774 bytes to be copied. If the C<ptr> argument is NULL the SV will become
5775 undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>.
5777 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
5785 Like C<sv_setpvn>, but also handles 'set' magic.
5787 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
5795 Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
5797 void sv_setpvs(SV* sv, const char* s)
5800 Found in file handy.h
5805 Like C<sv_setpv>, but also handles 'set' magic.
5807 void sv_setpv_mg(SV *sv, const char *ptr)
5815 Copies an integer into a new SV, optionally blessing the SV. The C<rv>
5816 argument will be upgraded to an RV. That RV will be modified to point to
5817 the new SV. The C<classname> argument indicates the package for the
5818 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
5819 will have a reference count of 1, and the RV will be returned.
5821 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
5829 Copies a double into a new SV, optionally blessing the SV. The C<rv>
5830 argument will be upgraded to an RV. That RV will be modified to point to
5831 the new SV. The C<classname> argument indicates the package for the
5832 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
5833 will have a reference count of 1, and the RV will be returned.
5835 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
5843 Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
5844 argument will be upgraded to an RV. That RV will be modified to point to
5845 the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
5846 into the SV. The C<classname> argument indicates the package for the
5847 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
5848 will have a reference count of 1, and the RV will be returned.
5850 Do not use with other Perl types such as HV, AV, SV, CV, because those
5851 objects will become corrupted by the pointer copy process.
5853 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
5855 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
5863 Copies a string into a new SV, optionally blessing the SV. The length of the
5864 string must be specified with C<n>. The C<rv> argument will be upgraded to
5865 an RV. That RV will be modified to point to the new SV. The C<classname>
5866 argument indicates the package for the blessing. Set C<classname> to
5867 C<NULL> to avoid the blessing. The new SV will have a reference count
5868 of 1, and the RV will be returned.
5870 Note that C<sv_setref_pv> copies the pointer while this copies the string.
5872 SV* sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n)
5880 Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
5881 argument will be upgraded to an RV. That RV will be modified to point to
5882 the new SV. The C<classname> argument indicates the package for the
5883 blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
5884 will have a reference count of 1, and the RV will be returned.
5886 SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
5894 Copies the contents of the source SV C<ssv> into the destination SV
5895 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
5896 function if the source SV needs to be reused. Does not handle 'set' magic.
5897 Loosely speaking, it performs a copy-by-value, obliterating any previous
5898 content of the destination.
5900 You probably want to use one of the assortment of wrappers, such as
5901 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
5902 C<SvSetMagicSV_nosteal>.
5904 void sv_setsv(SV* dsv, SV* ssv)
5909 =item sv_setsv_flags
5912 Copies the contents of the source SV C<ssv> into the destination SV
5913 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
5914 function if the source SV needs to be reused. Does not handle 'set' magic.
5915 Loosely speaking, it performs a copy-by-value, obliterating any previous
5916 content of the destination.
5917 If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
5918 C<ssv> if appropriate, else not. If the C<flags> parameter has the
5919 C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv>
5920 and C<sv_setsv_nomg> are implemented in terms of this function.
5922 You probably want to use one of the assortment of wrappers, such as
5923 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
5924 C<SvSetMagicSV_nosteal>.
5926 This is the primary function for copying scalars, and most other
5927 copy-ish functions and macros use this underneath.
5929 void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
5937 Like C<sv_setsv>, but also handles 'set' magic.
5939 void sv_setsv_mg(SV *dstr, SV *sstr)
5947 Copies an unsigned integer into the given SV, upgrading first if necessary.
5948 Does not handle 'set' magic. See also C<sv_setuv_mg>.
5950 void sv_setuv(SV* sv, UV num)
5958 Like C<sv_setuv>, but also handles 'set' magic.
5960 void sv_setuv_mg(SV *sv, UV u)
5968 Test an SV for taintedness. Use C<SvTAINTED> instead.
5969 bool sv_tainted(SV* sv)
5977 Returns true if the SV has a true value by Perl's rules.
5978 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
5979 instead use an in-line version.
5989 Removes all magic of type C<type> from an SV.
5991 int sv_unmagic(SV* sv, int type)
5996 =item sv_unref_flags
5999 Unsets the RV status of the SV, and decrements the reference count of
6000 whatever was being referenced by the RV. This can almost be thought of
6001 as a reversal of C<newSVrv>. The C<cflags> argument can contain
6002 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
6003 (otherwise the decrementing is conditional on the reference count being
6004 different from one or the reference being a readonly SV).
6007 void sv_unref_flags(SV* sv, U32 flags)
6015 Untaint an SV. Use C<SvTAINTED_off> instead.
6016 void sv_untaint(SV* sv)
6024 Upgrade an SV to a more complex form. Generally adds a new body type to the
6025 SV, then copies across as much information as possible from the old body.
6026 You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
6028 void sv_upgrade(SV* sv, svtype new_type)
6033 =item sv_usepvn_flags
6036 Tells an SV to use C<ptr> to find its string value. Normally the
6037 string is stored inside the SV but sv_usepvn allows the SV to use an
6038 outside string. The C<ptr> should point to memory that was allocated
6039 by C<malloc>. The string length, C<len>, must be supplied. By default
6040 this function will realloc (i.e. move) the memory pointed to by C<ptr>,
6041 so that pointer should not be freed or used by the programmer after
6042 giving it to sv_usepvn, and neither should any pointers from "behind"
6043 that pointer (e.g. ptr + 1) be used.
6045 If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
6046 SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
6047 will be skipped. (i.e. the buffer is actually at least 1 byte longer than
6048 C<len>, and already meets the requirements for storing in C<SvPVX>)
6050 void sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
6055 =item sv_utf8_decode
6058 If the PV of the SV is an octet sequence in UTF-8
6059 and contains a multiple-byte character, the C<SvUTF8> flag is turned on
6060 so that it looks like a character. If the PV contains only single-byte
6061 characters, the C<SvUTF8> flag stays being off.
6062 Scans PV for validity and returns false if the PV is invalid UTF-8.
6064 NOTE: this function is experimental and may change or be
6065 removed without notice.
6067 bool sv_utf8_decode(SV *sv)
6072 =item sv_utf8_downgrade
6073 X<sv_utf8_downgrade>
6075 Attempts to convert the PV of an SV from characters to bytes.
6076 If the PV contains a character beyond byte, this conversion will fail;
6077 in this case, either returns false or, if C<fail_ok> is not
6080 This is not as a general purpose Unicode to byte encoding interface:
6081 use the Encode extension for that.
6083 NOTE: this function is experimental and may change or be
6084 removed without notice.
6086 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
6091 =item sv_utf8_encode
6094 Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
6095 flag off so that it looks like octets again.
6097 void sv_utf8_encode(SV *sv)
6102 =item sv_utf8_upgrade
6105 Converts the PV of an SV to its UTF-8-encoded form.
6106 Forces the SV to string form if it is not already.
6107 Always sets the SvUTF8 flag to avoid future validity checks even
6108 if all the bytes have hibit clear.
6110 This is not as a general purpose byte encoding to Unicode interface:
6111 use the Encode extension for that.
6113 STRLEN sv_utf8_upgrade(SV *sv)
6118 =item sv_utf8_upgrade_flags
6119 X<sv_utf8_upgrade_flags>
6121 Converts the PV of an SV to its UTF-8-encoded form.
6122 Forces the SV to string form if it is not already.
6123 Always sets the SvUTF8 flag to avoid future validity checks even
6124 if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
6125 will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
6126 C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
6128 This is not as a general purpose byte encoding to Unicode interface:
6129 use the Encode extension for that.
6131 STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
6139 Processes its arguments like C<vsprintf> and appends the formatted output
6140 to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>.
6142 Usually used via its frontend C<sv_catpvf>.
6144 void sv_vcatpvf(SV* sv, const char* pat, va_list* args)
6152 Processes its arguments like C<vsprintf> and appends the formatted output
6153 to an SV. Uses an array of SVs if the C style variable argument list is
6154 missing (NULL). When running with taint checks enabled, indicates via
6155 C<maybe_tainted> if results are untrustworthy (often due to the use of
6158 Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
6160 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
6168 Like C<sv_vcatpvf>, but also handles 'set' magic.
6170 Usually used via its frontend C<sv_catpvf_mg>.
6172 void sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
6180 Works like C<sv_vcatpvf> but copies the text into the SV instead of
6181 appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>.
6183 Usually used via its frontend C<sv_setpvf>.
6185 void sv_vsetpvf(SV* sv, const char* pat, va_list* args)
6193 Works like C<sv_vcatpvfn> but copies the text into the SV instead of
6196 Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
6198 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
6206 Like C<sv_vsetpvf>, but also handles 'set' magic.
6208 Usually used via its frontend C<sv_setpvf_mg>.
6210 void sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
6218 =head1 Unicode Support
6222 =item bytes_from_utf8
6225 Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
6226 Unlike C<utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
6227 the newly-created string, and updates C<len> to contain the new
6228 length. Returns the original string if no conversion occurs, C<len>
6229 is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
6230 0 if C<s> is converted or contains all 7bit characters.
6232 NOTE: this function is experimental and may change or be
6233 removed without notice.
6235 U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
6238 Found in file utf8.c
6243 Converts a string C<s> of length C<len> from ASCII into UTF-8 encoding.
6244 Returns a pointer to the newly-created string, and sets C<len> to
6245 reflect the new length.
6247 If you want to convert to UTF-8 from other encodings than ASCII,
6248 see sv_recode_to_utf8().
6250 NOTE: this function is experimental and may change or be
6251 removed without notice.
6253 U8* bytes_to_utf8(const U8 *s, STRLEN *len)
6256 Found in file utf8.c
6261 Return true if the strings s1 and s2 differ case-insensitively, false
6262 if not (if they are equal case-insensitively). If u1 is true, the
6263 string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
6264 the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2
6265 are false, the respective string is assumed to be in native 8-bit
6268 If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
6269 in there (they will point at the beginning of the I<next> character).
6270 If the pointers behind pe1 or pe2 are non-NULL, they are the end
6271 pointers beyond which scanning will not continue under any
6272 circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
6273 s2+l2 will be used as goal end pointers that will also stop the scan,
6274 and which qualify towards defining a successful match: all the scans
6275 that define an explicit length must reach their goal pointers for
6276 a match to succeed).
6278 For case-insensitiveness, the "casefolding" of Unicode is used
6279 instead of upper/lowercasing both the characters, see
6280 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
6282 I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
6285 Found in file utf8.c
6290 Tests if some arbitrary number of bytes begins in a valid UTF-8
6291 character. Note that an INVARIANT (i.e. ASCII) character is a valid
6292 UTF-8 character. The actual number of bytes in the UTF-8 character
6293 will be returned if it is valid, otherwise 0.
6295 STRLEN is_utf8_char(const U8 *p)
6298 Found in file utf8.c
6300 =item is_utf8_string
6303 Returns true if first C<len> bytes of the given string form a valid
6304 UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does
6305 not mean 'a string that contains code points above 0x7F encoded in UTF-8'
6306 because a valid ASCII string is a valid UTF-8 string.
6308 See also is_utf8_string_loclen() and is_utf8_string_loc().
6310 bool is_utf8_string(const U8 *s, STRLEN len)
6313 Found in file utf8.c
6315 =item is_utf8_string_loc
6316 X<is_utf8_string_loc>
6318 Like is_utf8_string() but stores the location of the failure (in the
6319 case of "utf8ness failure") or the location s+len (in the case of
6320 "utf8ness success") in the C<ep>.
6322 See also is_utf8_string_loclen() and is_utf8_string().
6324 bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
6327 Found in file utf8.c
6329 =item is_utf8_string_loclen
6330 X<is_utf8_string_loclen>
6332 Like is_utf8_string() but stores the location of the failure (in the
6333 case of "utf8ness failure") or the location s+len (in the case of
6334 "utf8ness success") in the C<ep>, and the number of UTF-8
6335 encoded characters in the C<el>.
6337 See also is_utf8_string_loc() and is_utf8_string().
6339 bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
6342 Found in file utf8.c
6344 =item pv_uni_display
6347 Build to the scalar dsv a displayable version of the string spv,
6348 length len, the displayable version being at most pvlim bytes long
6349 (if longer, the rest is truncated and "..." will be appended).
6351 The flags argument can have UNI_DISPLAY_ISPRINT set to display
6352 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
6353 to display the \\[nrfta\\] as the backslashed versions (like '\n')
6354 (UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
6355 UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
6356 UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
6358 The pointer to the PV of the dsv is returned.
6360 char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
6363 Found in file utf8.c
6368 The encoding is assumed to be an Encode object, the PV of the ssv is
6369 assumed to be octets in that encoding and decoding the input starts
6370 from the position which (PV + *offset) pointed to. The dsv will be
6371 concatenated the decoded UTF-8 string from ssv. Decoding will terminate
6372 when the string tstr appears in decoding output or the input ends on
6373 the PV of the ssv. The value which the offset points will be modified
6374 to the last input position on the ssv.
6376 Returns TRUE if the terminator was found, else returns FALSE.
6378 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
6383 =item sv_recode_to_utf8
6384 X<sv_recode_to_utf8>
6386 The encoding is assumed to be an Encode object, on entry the PV
6387 of the sv is assumed to be octets in that encoding, and the sv
6388 will be converted into Unicode (and UTF-8).
6390 If the sv already is UTF-8 (or if it is not POK), or if the encoding
6391 is not a reference, nothing is done to the sv. If the encoding is not
6392 an C<Encode::XS> Encoding object, bad things will happen.
6393 (See F<lib/encoding.pm> and L<Encode>).
6395 The PV of the sv is returned.
6397 char* sv_recode_to_utf8(SV* sv, SV *encoding)
6402 =item sv_uni_display
6405 Build to the scalar dsv a displayable version of the scalar sv,
6406 the displayable version being at most pvlim bytes long
6407 (if longer, the rest is truncated and "..." will be appended).
6409 The flags argument is as in pv_uni_display().
6411 The pointer to the PV of the dsv is returned.
6413 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
6416 Found in file utf8.c
6421 The "p" contains the pointer to the UTF-8 string encoding
6422 the character that is being converted.
6424 The "ustrp" is a pointer to the character buffer to put the
6425 conversion result to. The "lenp" is a pointer to the length
6428 The "swashp" is a pointer to the swash to use.
6430 Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
6431 and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually,
6432 but not always, a multicharacter mapping), is tried first.
6434 The "special" is a string like "utf8::ToSpecLower", which means the
6435 hash %utf8::ToSpecLower. The access to the hash is through
6436 Perl_to_utf8_case().
6438 The "normal" is a string like "ToLower" which means the swash
6441 UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
6444 Found in file utf8.c
6449 Convert the UTF-8 encoded character at p to its foldcase version and
6450 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6451 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6452 foldcase version may be longer than the original character (up to
6455 The first character of the foldcased version is returned
6456 (but note, as explained above, that there may be more.)
6458 UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
6461 Found in file utf8.c
6466 Convert the UTF-8 encoded character at p to its lowercase version and
6467 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6468 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6469 lowercase version may be longer than the original character.
6471 The first character of the lowercased version is returned
6472 (but note, as explained above, that there may be more.)
6474 UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
6477 Found in file utf8.c
6482 Convert the UTF-8 encoded character at p to its titlecase version and
6483 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6484 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
6485 titlecase version may be longer than the original character.
6487 The first character of the titlecased version is returned
6488 (but note, as explained above, that there may be more.)
6490 UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
6493 Found in file utf8.c
6498 Convert the UTF-8 encoded character at p to its uppercase version and
6499 store that in UTF-8 in ustrp and its length in bytes in lenp. Note
6500 that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
6501 the uppercase version may be longer than the original character.
6503 The first character of the uppercased version is returned
6504 (but note, as explained above, that there may be more.)
6506 UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
6509 Found in file utf8.c
6511 =item utf8n_to_uvchr
6516 Returns the native character value of the first character in the string
6518 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6519 length, in bytes, of that character.
6521 Allows length and flags to be passed to low level routine.
6523 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
6526 Found in file utf8.c
6528 =item utf8n_to_uvuni
6531 Bottom level UTF-8 decode routine.
6532 Returns the unicode code point value of the first character in the string C<s>
6533 which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
6534 C<retlen> will be set to the length, in bytes, of that character.
6536 If C<s> does not point to a well-formed UTF-8 character, the behaviour
6537 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
6538 it is assumed that the caller will raise a warning, and this function
6539 will silently just set C<retlen> to C<-1> and return zero. If the
6540 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
6541 malformations will be given, C<retlen> will be set to the expected
6542 length of the UTF-8 character in bytes, and zero will be returned.
6544 The C<flags> can also contain various flags to allow deviations from
6545 the strict UTF-8 encoding (see F<utf8.h>).
6547 Most code should use utf8_to_uvchr() rather than call this directly.
6549 UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
6552 Found in file utf8.c
6557 Returns the number of UTF-8 characters between the UTF-8 pointers C<a>
6560 WARNING: use only if you *know* that the pointers point inside the
6563 IV utf8_distance(const U8 *a, const U8 *b)
6566 Found in file utf8.c
6571 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
6572 forward or backward.
6574 WARNING: do not use the following unless you *know* C<off> is within
6575 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
6576 on the first byte of character or just after the last byte of a character.
6578 U8* utf8_hop(const U8 *s, I32 off)
6581 Found in file utf8.c
6586 Return the length of the UTF-8 char encoded string C<s> in characters.
6587 Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
6588 up past C<e>, croaks.
6590 STRLEN utf8_length(const U8* s, const U8 *e)
6593 Found in file utf8.c
6598 Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
6599 Unlike C<bytes_to_utf8>, this over-writes the original string, and
6600 updates len to contain the new length.
6601 Returns zero on failure, setting C<len> to -1.
6603 If you need a copy of the string, see C<bytes_from_utf8>.
6605 NOTE: this function is experimental and may change or be
6606 removed without notice.
6608 U8* utf8_to_bytes(U8 *s, STRLEN *len)
6611 Found in file utf8.c
6616 Returns the native character value of the first character in the string C<s>
6617 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6618 length, in bytes, of that character.
6620 If C<s> does not point to a well-formed UTF-8 character, zero is
6621 returned and retlen is set, if possible, to -1.
6623 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
6626 Found in file utf8.c
6631 Returns the Unicode code point of the first character in the string C<s>
6632 which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
6633 length, in bytes, of that character.
6635 This function should only be used when returned UV is considered
6636 an index into the Unicode semantic tables (e.g. swashes).
6638 If C<s> does not point to a well-formed UTF-8 character, zero is
6639 returned and retlen is set, if possible, to -1.
6641 UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
6644 Found in file utf8.c
6649 Adds the UTF-8 representation of the Native codepoint C<uv> to the end
6650 of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
6651 bytes available. The return value is the pointer to the byte after the
6652 end of the new character. In other words,
6654 d = uvchr_to_utf8(d, uv);
6656 is the recommended wide native character-aware way of saying
6660 U8* uvchr_to_utf8(U8 *d, UV uv)
6663 Found in file utf8.c
6665 =item uvuni_to_utf8_flags
6666 X<uvuni_to_utf8_flags>
6668 Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
6669 of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
6670 bytes available. The return value is the pointer to the byte after the
6671 end of the new character. In other words,
6673 d = uvuni_to_utf8_flags(d, uv, flags);
6677 d = uvuni_to_utf8(d, uv);
6679 (which is equivalent to)
6681 d = uvuni_to_utf8_flags(d, uv, 0);
6683 is the recommended Unicode-aware way of saying
6687 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
6690 Found in file utf8.c
6695 =head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
6702 Variable which is setup by C<xsubpp> to indicate the stack base offset,
6703 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
6704 must be called prior to setup the C<MARK> variable.
6709 Found in file XSUB.h
6714 Variable which is setup by C<xsubpp> to indicate the
6715 class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
6720 Found in file XSUB.h
6725 Sets up the C<ax> variable.
6726 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
6731 Found in file XSUB.h
6736 Sets up the C<ax> variable and stack marker variable C<mark>.
6737 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
6742 Found in file XSUB.h
6747 Sets up the C<items> variable.
6748 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
6753 Found in file XSUB.h
6758 Sets up the C<padoff_du> variable for an XSUB that wishes to use
6764 Found in file XSUB.h
6769 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
6770 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
6771 This is usually handled automatically by C<xsubpp>.
6776 Found in file XSUB.h
6781 Sets up the C<ix> variable for an XSUB which has aliases. This is usually
6782 handled automatically by C<xsubpp>.
6787 Found in file XSUB.h
6792 Variable which is setup by C<xsubpp> to indicate the number of
6793 items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
6798 Found in file XSUB.h
6803 Variable which is setup by C<xsubpp> to indicate which of an
6804 XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
6809 Found in file XSUB.h
6814 Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
6818 Found in file XSUB.h
6823 Variable which is setup by C<xsubpp> to hold the return value for an
6824 XSUB. This is always the proper type for the XSUB. See
6825 L<perlxs/"The RETVAL Variable">.
6830 Found in file XSUB.h
6835 Used to access elements on the XSUB's stack.
6840 Found in file XSUB.h
6845 Variable which is setup by C<xsubpp> to designate the object in a C++
6846 XSUB. This is always the proper type for the C++ object. See C<CLASS> and
6847 L<perlxs/"Using XS With C++">.
6852 Found in file XSUB.h
6857 The SV* corresponding to the $_ variable. Works even if there
6858 is a lexical $_ in scope.
6861 Found in file XSUB.h
6866 Macro to declare an XSUB and its C parameter list. This is handled by
6870 Found in file XSUB.h
6875 The version identifier for an XS module. This is usually
6876 handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
6879 Found in file XSUB.h
6881 =item XS_VERSION_BOOTCHECK
6882 X<XS_VERSION_BOOTCHECK>
6884 Macro to verify that a PM module's $VERSION variable matches the XS
6885 module's C<XS_VERSION> variable. This is usually handled automatically by
6886 C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
6888 XS_VERSION_BOOTCHECK;
6891 Found in file XSUB.h
6896 =head1 Warning and Dieing
6903 This is the XSUB-writer's interface to Perl's C<die> function.
6904 Normally call this function the same way you call the C C<printf>
6905 function. Calling C<croak> returns control directly to Perl,
6906 sidestepping the normal C order of execution. See C<warn>.
6908 If you want to throw an exception object, assign the object to
6909 C<$@> and then pass C<NULL> to croak():
6911 errsv = get_sv("@", TRUE);
6912 sv_setsv(errsv, exception_object);
6915 void croak(const char* pat, ...)
6918 Found in file util.c
6923 This is the XSUB-writer's interface to Perl's C<warn> function. Call this
6924 function the same way you call the C C<printf> function. See C<croak>.
6926 void warn(const char* pat, ...)
6929 Found in file util.c
6936 Until May 1997, this document was maintained by Jeff Okamoto
6937 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
6939 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
6940 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
6941 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
6942 Stephen McCamant, and Gurusamy Sarathy.
6944 API Listing originally by Dean Roehrich <roehrich@cray.com>.
6946 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
6950 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
projects / p5sagit/p5-mst-13.2.git / blob