3 perlapi - autogenerated documentation for the perl public API
7 This file contains the documentation of the perl public API generated by
8 embed.pl, specifically a listing of functions, macros, flags, and variables
9 that may be used by extension writers. The interfaces of any functions that
10 are not listed here are subject to change without notice. For this reason,
11 blindly using functions listed in proto.h is to be avoided when writing
14 Note that all Perl API global variables must be referenced with the C<PL_>
15 prefix. Some macros are provided for compatibility with the older,
16 unadorned names, but this support may be disabled in a future release.
18 The listing is alphabetical, case insensitive.
24 Same as C<av_len()>. Deprecated, use C<av_len()> instead.
33 Clears an array, making it empty. Does not free the memory used by the
43 Deletes the element indexed by C<key> from the array. Returns the
44 deleted element. C<flags> is currently ignored.
46 SV* av_delete(AV* ar, I32 key, I32 flags)
53 Returns true if the element indexed by C<key> has been initialized.
55 This relies on the fact that uninitialized array elements are set to
58 bool av_exists(AV* ar, I32 key)
65 Pre-extend an array. The C<key> is the index to which the array should be
68 void av_extend(AV* ar, I32 key)
75 Returns the SV at the specified index in the array. The C<key> is the
76 index. If C<lval> is set then the fetch will be part of a store. Check
77 that the return value is non-null before dereferencing it to a C<SV*>.
79 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
80 more information on how to use this function on tied arrays.
82 SV** av_fetch(AV* ar, I32 key, I32 lval)
89 Ensure than an array has a given number of elements, equivalent to
90 Perl's C<$#array = $fill;>.
92 void av_fill(AV* ar, I32 fill)
99 Returns the highest index in the array. Returns -1 if the array is
109 Creates a new AV and populates it with a list of SVs. The SVs are copied
110 into the array, so they may be freed after the call to av_make. The new AV
111 will have a reference count of 1.
113 AV* av_make(I32 size, SV** svp)
120 Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
130 Pushes an SV onto the end of the array. The array will grow automatically
131 to accommodate the addition.
133 void av_push(AV* ar, SV* val)
140 Shifts an SV off the beginning of the array.
149 Stores an SV in an array. The array index is specified as C<key>. The
150 return value will be NULL if the operation failed or if the value did not
151 need to be actually stored within the array (as in the case of tied
152 arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
153 that the caller is responsible for suitably incrementing the reference
154 count of C<val> before the call, and decrementing it if the function
157 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
158 more information on how to use this function on tied arrays.
160 SV** av_store(AV* ar, I32 key, SV* val)
167 Undefines the array. Frees the memory used by the array itself.
169 void av_undef(AV* ar)
176 Unshift the given number of C<undef> values onto the beginning of the
177 array. The array will grow automatically to accommodate the addition. You
178 must then use C<av_store> to assign values to these new elements.
180 void av_unshift(AV* ar, I32 num)
187 Variable which is setup by C<xsubpp> to indicate the stack base offset,
188 used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
189 must be called prior to setup the C<MARK> variable.
196 =item bytes_from_utf8
198 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
199 Unlike <utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
200 the newly-created string, and updates C<len> to contain the new
201 length. Returns the original string if no conversion occurs, C<len>
202 is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
203 0 if C<s> is converted or contains all 7bit characters.
205 NOTE: this function is experimental and may change or be
206 removed without notice.
208 U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
215 Converts a string C<s> of length C<len> from ASCII into UTF8 encoding.
216 Returns a pointer to the newly-created string, and sets C<len> to
217 reflect the new length.
219 NOTE: this function is experimental and may change or be
220 removed without notice.
222 U8* bytes_to_utf8(U8 *s, STRLEN *len)
229 Performs a callback to the specified Perl sub. See L<perlcall>.
231 NOTE: the perl_ form of this function is deprecated.
233 I32 call_argv(const char* sub_name, I32 flags, char** argv)
240 Performs a callback to the specified Perl method. The blessed object must
241 be on the stack. See L<perlcall>.
243 NOTE: the perl_ form of this function is deprecated.
245 I32 call_method(const char* methname, I32 flags)
252 Performs a callback to the specified Perl sub. See L<perlcall>.
254 NOTE: the perl_ form of this function is deprecated.
256 I32 call_pv(const char* sub_name, I32 flags)
263 Performs a callback to the Perl sub whose name is in the SV. See
266 NOTE: the perl_ form of this function is deprecated.
268 I32 call_sv(SV* sv, I32 flags)
275 Variable which is setup by C<xsubpp> to indicate the
276 class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
285 The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
286 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
287 the type. May fail on overlapping copies. See also C<Move>.
289 void Copy(void* src, void* dest, int nitems, type)
292 Found in file handy.h
296 This is the XSUB-writer's interface to Perl's C<die> function.
297 Normally use this function the same way you use the C C<printf>
298 function. See C<warn>.
300 If you want to throw an exception object, assign the object to
301 C<$@> and then pass C<Nullch> to croak():
303 errsv = get_sv("@", TRUE);
304 sv_setsv(errsv, exception_object);
307 void croak(const char* pat, ...)
314 Returns the stash of the CV.
323 If C<cv> is a constant sub eligible for inlining. returns the constant
324 value returned by the sub. Otherwise, returns NULL.
326 Constant subs can be created with C<newCONSTSUB> or as described in
327 L<perlsub/"Constant Functions">.
329 SV* cv_const_sv(CV* cv)
336 Sets up the C<ax> variable.
337 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
346 Sets up the C<items> variable.
347 This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
356 Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
366 Saves the original stack mark for the XSUB. See C<ORIGMARK>.
375 Declares a local copy of perl's stack pointer for the XSUB, available via
376 the C<SP> macro. See C<SP>.
385 Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
386 Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
387 This is usually handled automatically by C<xsubpp>.
396 Sets up the C<ix> variable for an XSUB which has aliases. This is usually
397 handled automatically by C<xsubpp>.
406 Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
411 Found in file scope.h
415 Tells Perl to C<eval> the given string and return an SV* result.
417 NOTE: the perl_ form of this function is deprecated.
419 SV* eval_pv(const char* p, I32 croak_on_error)
426 Tells Perl to C<eval> the string in the SV.
428 NOTE: the perl_ form of this function is deprecated.
430 I32 eval_sv(SV* sv, I32 flags)
437 Used to extend the argument stack for an XSUB's return values. Once
438 used, guarantees that there is room for at least C<nitems> to be pushed
441 void EXTEND(SP, int nitems)
448 Analyses the string in order to make fast searches on it using fbm_instr()
449 -- the Boyer-Moore algorithm.
451 void fbm_compile(SV* sv, U32 flags)
458 Returns the location of the SV in the string delimited by C<str> and
459 C<strend>. It returns C<Nullch> if the string can't be found. The C<sv>
460 does not have to be fbm_compiled, but the search will not be as fast
463 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
470 Takes a sprintf-style format pattern and conventional
471 (non-SV) arguments and returns the formatted string.
473 (char *) Perl_form(pTHX_ const char* pat, ...)
475 can be used any place a string (char *) is required:
477 char * s = Perl_form("%d.%d",major,minor);
479 Uses a single private buffer so if you want to format several strings you
480 must explicitly copy the earlier strings away (and free the copies when you
483 char* form(const char* pat, ...)
490 Closing bracket for temporaries on a callback. See C<SAVETMPS> and
496 Found in file scope.h
500 Fill the sv with current working directory
502 int getcwd_sv(SV* sv)
509 Returns the AV of the specified Perl array. If C<create> is set and the
510 Perl variable does not exist then it will be created. If C<create> is not
511 set and the variable does not exist then NULL is returned.
513 NOTE: the perl_ form of this function is deprecated.
515 AV* get_av(const char* name, I32 create)
522 Returns the CV of the specified Perl subroutine. If C<create> is set and
523 the Perl subroutine does not exist then it will be declared (which has the
524 same effect as saying C<sub name;>). If C<create> is not set and the
525 subroutine does not exist then NULL is returned.
527 NOTE: the perl_ form of this function is deprecated.
529 CV* get_cv(const char* name, I32 create)
536 Returns the HV of the specified Perl hash. If C<create> is set and the
537 Perl variable does not exist then it will be created. If C<create> is not
538 set and the variable does not exist then NULL is returned.
540 NOTE: the perl_ form of this function is deprecated.
542 HV* get_hv(const char* name, I32 create)
549 Returns the SV of the specified Perl scalar. If C<create> is set and the
550 Perl variable does not exist then it will be created. If C<create> is not
551 set and the variable does not exist then NULL is returned.
553 NOTE: the perl_ form of this function is deprecated.
555 SV* get_sv(const char* name, I32 create)
562 A backward-compatible version of C<GIMME_V> which can only return
563 C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
564 Deprecated. Use C<GIMME_V> instead.
573 The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
574 C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
584 converts a string representing a binary number to numeric form.
586 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
587 conversion flags, and I<result> should be NULL or a pointer to an NV.
588 The scan stops at the end of the string, or the first invalid character.
589 On return I<*len> is set to the length scanned string, and I<*flags> gives
592 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
593 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
594 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
595 and writes the value to I<*result> (or the value is discarded if I<result>
598 The hex number may optionally be prefixed with "0b" or "b" unless
599 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
600 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
601 number may use '_' characters to separate digits.
603 UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
606 Found in file numeric.c
610 converts a string representing a hex number to numeric form.
612 On entry I<start> and I<*len> give the string to scan, I<*flags> gives
613 conversion flags, and I<result> should be NULL or a pointer to an NV.
614 The scan stops at the end of the string, or the first non-hex-digit character.
615 On return I<*len> is set to the length scanned string, and I<*flags> gives
618 If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
619 and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
620 returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
621 and writes the value to I<*result> (or the value is discarded if I<result>
624 The hex number may optionally be prefixed with "0x" or "x" unless
625 C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
626 C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
627 number may use '_' characters to separate digits.
629 UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
632 Found in file numeric.c
636 Recognise (or not) a number. The type of the number is returned
637 (0 if unrecognised), otherwise it is a bit-ORed combination of
638 IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
639 IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
641 If the value of the number can fit an in UV, it is returned in the *valuep
642 IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
643 will never be set unless *valuep is valid, but *valuep may have been assigned
644 to during processing even though IS_NUMBER_IN_UV is not set on return.
645 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
646 valuep is non-NULL, but no actual assignment (or SEGV) will occur.
648 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
649 seen (in which case *valuep gives the true value truncated to an integer), and
650 IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
651 absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
652 number is larger than a UV.
654 int grok_number(const char *pv, STRLEN len, UV *valuep)
657 Found in file numeric.c
659 =item grok_numeric_radix
661 Scan and skip for a numeric decimal separator (radix).
663 bool grok_numeric_radix(const char **sp, const char *send)
666 Found in file numeric.c
671 UV grok_oct(char* start, STRLEN* len, I32* flags, NV *result)
674 Found in file numeric.c
678 Return the SV from the GV.
687 Returns the glob with the given C<name> and a defined subroutine or
688 C<NULL>. The glob lives in the given C<stash>, or in the stashes
689 accessible via @ISA and UNIVERSAL::.
691 The argument C<level> should be either 0 or -1. If C<level==0>, as a
692 side-effect creates a glob with the given C<name> in the given C<stash>
693 which in the case of success contains an alias for the subroutine, and sets
694 up caching info for this glob. Similarly for all the searched stashes.
696 This function grants C<"SUPER"> token as a postfix of the stash name. The
697 GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
698 visible to Perl code. So when calling C<call_sv>, you should not use
699 the GV directly; instead, you should use the method's CV, which can be
700 obtained from the GV with the C<GvCV> macro.
702 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
709 See L<gv_fetchmethod_autoload>.
711 GV* gv_fetchmethod(HV* stash, const char* name)
716 =item gv_fetchmethod_autoload
718 Returns the glob which contains the subroutine to call to invoke the method
719 on the C<stash>. In fact in the presence of autoloading this may be the
720 glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
723 The third parameter of C<gv_fetchmethod_autoload> determines whether
724 AUTOLOAD lookup is performed if the given method is not present: non-zero
725 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
726 Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
727 with a non-zero C<autoload> parameter.
729 These functions grant C<"SUPER"> token as a prefix of the method name. Note
730 that if you want to keep the returned glob for a long time, you need to
731 check for it being "AUTOLOAD", since at the later time the call may load a
732 different subroutine due to $AUTOLOAD changing its value. Use the glob
733 created via a side effect to do this.
735 These functions have the same side-effects and as C<gv_fetchmeth> with
736 C<level==0>. C<name> should be writable if contains C<':'> or C<'
737 ''>. The warning against passing the GV returned by C<gv_fetchmeth> to
738 C<call_sv> apply equally to these functions.
740 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
747 Returns a pointer to the stash for a specified package. C<name> should
748 be a valid UTF-8 string. If C<create> is set then the package will be
749 created if it does not already exist. If C<create> is not set and the
750 package does not exist then NULL is returned.
752 HV* gv_stashpv(const char* name, I32 create)
759 Returns a pointer to the stash for a specified package, which must be a
760 valid UTF-8 string. See C<gv_stashpv>.
762 HV* gv_stashsv(SV* sv, I32 create)
769 Used to indicate list context. See C<GIMME_V>, C<GIMME> and
777 Indicates that arguments returned from a callback should be discarded. See
785 Used to force a Perl C<eval> wrapper around a callback. See
793 Indicates that no arguments are being sent to a callback. See
801 Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
809 Used to indicate void context. See C<GIMME_V> and L<perlcall>.
816 This flag, used in the length slot of hash entries and magic structures,
817 specifies the structure contains an C<SV*> pointer where a C<char*> pointer
818 is to be expected. (For information only--not to be used).
825 Returns the computed hash stored in the hash entry.
834 Returns the actual pointer stored in the key slot of the hash entry. The
835 pointer may be either C<char*> or C<SV*>, depending on the value of
836 C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
837 usually preferable for finding the value of a key.
846 If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
847 holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
848 be assigned to. The C<HePV()> macro is usually preferable for finding key
851 STRLEN HeKLEN(HE* he)
858 Returns the key slot of the hash entry as a C<char*> value, doing any
859 necessary dereferencing of possibly C<SV*> keys. The length of the string
860 is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
861 not care about what the length of the key is, you may use the global
862 variable C<PL_na>, though this is rather less efficient than using a local
863 variable. Remember though, that hash keys in perl are free to contain
864 embedded nulls, so using C<strlen()> or similar is not a good way to find
865 the length of hash keys. This is very similar to the C<SvPV()> macro
866 described elsewhere in this document.
868 char* HePV(HE* he, STRLEN len)
875 Returns the key as an C<SV*>, or C<Nullsv> if the hash entry does not
876 contain an C<SV*> key.
885 Returns the key as an C<SV*>. Will create and return a temporary mortal
886 C<SV*> if the hash entry contains only a C<char*> key.
888 SV* HeSVKEY_force(HE* he)
895 Sets the key to a given C<SV*>, taking care to set the appropriate flags to
896 indicate the presence of an C<SV*> key, and returns the same
899 SV* HeSVKEY_set(HE* he, SV* sv)
906 Returns the value slot (type C<SV*>) stored in the hash entry.
915 Returns the package name of a stash. See C<SvSTASH>, C<CvSTASH>.
917 char* HvNAME(HV* stash)
924 Clears a hash, making it empty.
926 void hv_clear(HV* tb)
933 Deletes a key/value pair in the hash. The value SV is removed from the
934 hash and returned to the caller. The C<klen> is the length of the key.
935 The C<flags> value will normally be zero; if set to G_DISCARD then NULL
938 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
945 Deletes a key/value pair in the hash. The value SV is removed from the
946 hash and returned to the caller. The C<flags> value will normally be zero;
947 if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
948 precomputed hash value, or 0 to ask for it to be computed.
950 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
957 Returns a boolean indicating whether the specified hash key exists. The
958 C<klen> is the length of the key.
960 bool hv_exists(HV* tb, const char* key, I32 klen)
967 Returns a boolean indicating whether the specified hash key exists. C<hash>
968 can be a valid precomputed hash value, or 0 to ask for it to be
971 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
978 Returns the SV which corresponds to the specified key in the hash. The
979 C<klen> is the length of the key. If C<lval> is set then the fetch will be
980 part of a store. Check that the return value is non-null before
981 dereferencing it to an C<SV*>.
983 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
984 information on how to use this function on tied hashes.
986 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
993 Returns the hash entry which corresponds to the specified key in the hash.
994 C<hash> must be a valid precomputed hash number for the given C<key>, or 0
995 if you want the function to compute it. IF C<lval> is set then the fetch
996 will be part of a store. Make sure the return value is non-null before
997 accessing it. The return value when C<tb> is a tied hash is a pointer to a
998 static location, so be sure to make a copy of the structure if you need to
1001 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1002 information on how to use this function on tied hashes.
1004 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
1011 Prepares a starting point to traverse a hash table. Returns the number of
1012 keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
1013 currently only meaningful for hashes without tie magic.
1015 NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
1016 hash buckets that happen to be in use. If you still need that esoteric
1017 value, you can get it through the macro C<HvFILL(tb)>.
1019 I32 hv_iterinit(HV* tb)
1026 Returns the key from the current position of the hash iterator. See
1029 char* hv_iterkey(HE* entry, I32* retlen)
1036 Returns the key as an C<SV*> from the current position of the hash
1037 iterator. The return value will always be a mortal copy of the key. Also
1040 SV* hv_iterkeysv(HE* entry)
1047 Returns entries from a hash iterator. See C<hv_iterinit>.
1049 HE* hv_iternext(HV* tb)
1056 Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
1059 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
1066 Returns the value from the current position of the hash iterator. See
1069 SV* hv_iterval(HV* tb, HE* entry)
1076 Adds magic to a hash. See C<sv_magic>.
1078 void hv_magic(HV* hv, GV* gv, int how)
1085 Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
1086 the length of the key. The C<hash> parameter is the precomputed hash
1087 value; if it is zero then Perl will compute it. The return value will be
1088 NULL if the operation failed or if the value did not need to be actually
1089 stored within the hash (as in the case of tied hashes). Otherwise it can
1090 be dereferenced to get the original C<SV*>. Note that the caller is
1091 responsible for suitably incrementing the reference count of C<val> before
1092 the call, and decrementing it if the function returned NULL.
1094 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1095 information on how to use this function on tied hashes.
1097 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
1104 Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
1105 parameter is the precomputed hash value; if it is zero then Perl will
1106 compute it. The return value is the new hash entry so created. It will be
1107 NULL if the operation failed or if the value did not need to be actually
1108 stored within the hash (as in the case of tied hashes). Otherwise the
1109 contents of the return value can be accessed using the C<He?> macros
1110 described here. Note that the caller is responsible for suitably
1111 incrementing the reference count of C<val> before the call, and
1112 decrementing it if the function returned NULL.
1114 See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
1115 information on how to use this function on tied hashes.
1117 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
1126 void hv_undef(HV* tb)
1133 Return true if the strings s1 and s2 differ case-insensitively, false
1134 if not (if they are equal case-insensitively). If u1 is true, the
1135 string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
1136 the string s2 is assumed to be in UTF-8-encoded Unicode.
1138 For case-insensitiveness, the "casefolding" of Unicode is used
1139 instead of upper/lowercasing both the characters, see
1140 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
1142 I32 ibcmp_utf8(const char* a, bool ua, I32 len1, const char* b, bool ub, I32 len2)
1145 Found in file utf8.c
1149 Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
1150 character (including underscore) or digit.
1152 bool isALNUM(char ch)
1155 Found in file handy.h
1159 Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
1162 bool isALPHA(char ch)
1165 Found in file handy.h
1169 Returns a boolean indicating whether the C C<char> is an ASCII
1172 bool isDIGIT(char ch)
1175 Found in file handy.h
1179 Returns a boolean indicating whether the C C<char> is a lowercase
1182 bool isLOWER(char ch)
1185 Found in file handy.h
1189 Returns a boolean indicating whether the C C<char> is whitespace.
1191 bool isSPACE(char ch)
1194 Found in file handy.h
1198 Returns a boolean indicating whether the C C<char> is an uppercase
1201 bool isUPPER(char ch)
1204 Found in file handy.h
1208 Tests if some arbitrary number of bytes begins in a valid UTF-8
1209 character. Note that an INVARIANT (i.e. ASCII) character is a valid UTF-8 character.
1210 The actual number of bytes in the UTF-8 character will be returned if
1211 it is valid, otherwise 0.
1213 STRLEN is_utf8_char(U8 *p)
1216 Found in file utf8.c
1218 =item is_utf8_string
1220 Returns true if first C<len> bytes of the given string form a valid UTF8
1221 string, false otherwise. Note that 'a valid UTF8 string' does not mean
1222 'a string that contains UTF8' because a valid ASCII string is a valid
1225 bool is_utf8_string(U8 *s, STRLEN len)
1228 Found in file utf8.c
1232 Variable which is setup by C<xsubpp> to indicate the number of
1233 items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
1238 Found in file XSUB.h
1242 Variable which is setup by C<xsubpp> to indicate which of an
1243 XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
1248 Found in file XSUB.h
1252 Closing bracket on a callback. See C<ENTER> and L<perlcall>.
1257 Found in file scope.h
1261 Loads the module whose name is pointed to by the string part of name.
1262 Note that the actual module name, not its filename, should be given.
1263 Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
1264 PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
1265 (or 0 for no flags). ver, if specified, provides version semantics
1266 similar to C<use Foo::Bar VERSION>. The optional trailing SV*
1267 arguments can be used to specify arguments to the module's import()
1268 method, similar to C<use Foo::Bar VERSION LIST>.
1270 void load_module(U32 flags, SV* name, SV* ver, ...)
1275 =item looks_like_number
1277 Test if the content of an SV looks like a number (or is a number).
1278 C<Inf> and C<Infinity> are treated as numbers (so will not issue a
1279 non-numeric warning), even if your atof() doesn't grok them.
1281 I32 looks_like_number(SV* sv)
1288 Stack marker variable for the XSUB. See C<dMARK>.
1295 Clear something magical that the SV represents. See C<sv_magic>.
1297 int mg_clear(SV* sv)
1304 Copies the magic from one SV to another. See C<sv_magic>.
1306 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
1313 Finds the magic pointer for type matching the SV. See C<sv_magic>.
1315 MAGIC* mg_find(SV* sv, int type)
1322 Free any magic storage used by the SV. See C<sv_magic>.
1331 Do magic after a value is retrieved from the SV. See C<sv_magic>.
1340 Report on the SV's length. See C<sv_magic>.
1342 U32 mg_length(SV* sv)
1349 Turns on the magical status of an SV. See C<sv_magic>.
1351 void mg_magical(SV* sv)
1358 Do magic after a value is assigned to the SV. See C<sv_magic>.
1367 The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
1368 source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
1369 the type. Can do overlapping moves. See also C<Copy>.
1371 void Move(void* src, void* dest, int nitems, type)
1374 Found in file handy.h
1378 The XSUB-writer's interface to the C C<malloc> function.
1380 void New(int id, void* ptr, int nitems, type)
1383 Found in file handy.h
1387 Creates a new AV. The reference count is set to 1.
1396 The XSUB-writer's interface to the C C<malloc> function, with
1399 void Newc(int id, void* ptr, int nitems, type, cast)
1402 Found in file handy.h
1406 Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
1407 eligible for inlining at compile-time.
1409 CV* newCONSTSUB(HV* stash, char* name, SV* sv)
1416 Creates a new HV. The reference count is set to 1.
1425 Creates an RV wrapper for an SV. The reference count for the original SV is
1428 SV* newRV_inc(SV* sv)
1435 Creates an RV wrapper for an SV. The reference count for the original
1436 SV is B<not> incremented.
1438 SV* newRV_noinc(SV *sv)
1445 Creates a new SV. A non-zero C<len> parameter indicates the number of
1446 bytes of preallocated string space the SV should have. An extra byte for a
1447 tailing NUL is also reserved. (SvPOK is not set for the SV even if string
1448 space is allocated.) The reference count for the new SV is set to 1.
1449 C<id> is an integer id between 0 and 1299 (used to identify leaks).
1451 SV* NEWSV(int id, STRLEN len)
1454 Found in file handy.h
1458 Create a new null SV, or if len > 0, create a new empty SVt_PV type SV
1459 with an initial PV allocation of len+1. Normally accessed via the C<NEWSV>
1462 SV* newSV(STRLEN len)
1469 Creates a new SV and copies an integer into it. The reference count for the
1479 Creates a new SV and copies a floating point value into it.
1480 The reference count for the SV is set to 1.
1489 Creates a new SV and copies a string into it. The reference count for the
1490 SV is set to 1. If C<len> is zero, Perl will compute the length using
1491 strlen(). For efficiency, consider using C<newSVpvn> instead.
1493 SV* newSVpv(const char* s, STRLEN len)
1500 Creates a new SV and initializes it with the string formatted like
1503 SV* newSVpvf(const char* pat, ...)
1510 Creates a new SV and copies a string into it. The reference count for the
1511 SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
1512 string. You are responsible for ensuring that the source string is at least
1515 SV* newSVpvn(const char* s, STRLEN len)
1520 =item newSVpvn_share
1522 Creates a new SV with its SvPVX pointing to a shared string in the string
1523 table. If the string does not already exist in the table, it is created
1524 first. Turns on READONLY and FAKE. The string's hash is stored in the UV
1525 slot of the SV; if the C<hash> parameter is non-zero, that value is used;
1526 otherwise the hash is computed. The idea here is that as the string table
1527 is used for shared hash keys these strings will have SvPVX == HeKEY and
1528 hash lookup will avoid string compare.
1530 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
1537 Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
1538 it will be upgraded to one. If C<classname> is non-null then the new SV will
1539 be blessed in the specified package. The new SV is returned and its
1540 reference count is 1.
1542 SV* newSVrv(SV* rv, const char* classname)
1549 Creates a new SV which is an exact duplicate of the original SV.
1552 SV* newSVsv(SV* old)
1559 Creates a new SV and copies an unsigned integer into it.
1560 The reference count for the SV is set to 1.
1569 Used by C<xsubpp> to hook up XSUBs as Perl subs.
1576 Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
1580 Found in file XSUB.h
1584 The XSUB-writer's interface to the C C<malloc> function. The allocated
1585 memory is zeroed with C<memzero>.
1587 void Newz(int id, void* ptr, int nitems, type)
1590 Found in file handy.h
1594 Returns a pointer to the next character after the parsed
1595 vstring, as well as updating the passed in sv.
1597 Function must be called like
1600 s = new_vstring(s,sv);
1602 The sv must already be large enough to store the vstring
1605 char* new_vstring(char *vstr, SV *sv)
1608 Found in file util.c
1619 Null character pointer.
1622 Found in file handy.h
1643 Found in file handy.h
1647 The original stack mark for the XSUB. See C<dORIGMARK>.
1654 Allocates a new Perl interpreter. See L<perlembed>.
1656 PerlInterpreter* perl_alloc()
1659 Found in file perl.c
1663 Create and return a new interpreter by cloning the current one.
1665 PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
1670 =item perl_construct
1672 Initializes a new Perl interpreter. See L<perlembed>.
1674 void perl_construct(PerlInterpreter* interp)
1677 Found in file perl.c
1681 Shuts down a Perl interpreter. See L<perlembed>.
1683 int perl_destruct(PerlInterpreter* interp)
1686 Found in file perl.c
1690 Releases a Perl interpreter. See L<perlembed>.
1692 void perl_free(PerlInterpreter* interp)
1695 Found in file perl.c
1699 Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
1701 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
1704 Found in file perl.c
1708 Tells a Perl interpreter to run. See L<perlembed>.
1710 int perl_run(PerlInterpreter* interp)
1713 Found in file perl.c
1717 C<PL_modglobal> is a general purpose, interpreter global HV for use by
1718 extensions that need to keep information on a per-interpreter basis.
1719 In a pinch, it can also be used as a symbol table for extensions
1720 to share data among each other. It is a good idea to use keys
1721 prefixed by the package name of the extension that owns the data.
1726 Found in file intrpvar.h
1730 A convenience variable which is typically used with C<SvPV> when one
1731 doesn't care about the length of the string. It is usually more efficient
1732 to either declare a local variable and use that instead or to use the
1733 C<SvPV_nolen> macro.
1738 Found in file thrdvar.h
1742 This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
1748 Found in file intrpvar.h
1752 This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
1757 Found in file intrpvar.h
1761 This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
1767 Found in file intrpvar.h
1771 Pops an integer off the stack.
1780 Pops a long off the stack.
1789 Pops a double off the stack.
1798 Pops a string off the stack. Deprecated. New code should provide
1799 a STRLEN n_a and use POPpx.
1808 Pops a string off the stack which must consist of bytes i.e. characters < 256.
1809 Requires a variable STRLEN n_a in scope.
1818 Pops a string off the stack.
1819 Requires a variable STRLEN n_a in scope.
1828 Pops an SV off the stack.
1837 Push an integer onto the stack. The stack must have room for this element.
1838 Handles 'set' magic. See C<XPUSHi>.
1847 Opening bracket for arguments on a callback. See C<PUTBACK> and
1857 Push a double onto the stack. The stack must have room for this element.
1858 Handles 'set' magic. See C<XPUSHn>.
1867 Push a string onto the stack. The stack must have room for this element.
1868 The C<len> indicates the length of the string. Handles 'set' magic. See
1871 void PUSHp(char* str, STRLEN len)
1878 Push an SV onto the stack. The stack must have room for this element.
1879 Does not handle 'set' magic. See C<XPUSHs>.
1888 Push an unsigned integer onto the stack. The stack must have room for this
1889 element. See C<XPUSHu>.
1898 Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
1899 See C<PUSHMARK> and L<perlcall> for other uses.
1906 =item pv_uni_display
1908 Build to the scalar dsv a displayable version of the string spv,
1909 length len, the displayable version being at most pvlim bytes long
1910 (if longer, the rest is truncated and "..." will be appended).
1911 The flags argument is currently unused but available for future extensions.
1912 The pointer to the PV of the dsv is returned.
1914 char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
1917 Found in file utf8.c
1921 The XSUB-writer's interface to the C C<realloc> function.
1923 void Renew(void* ptr, int nitems, type)
1926 Found in file handy.h
1930 The XSUB-writer's interface to the C C<realloc> function, with
1933 void Renewc(void* ptr, int nitems, type, cast)
1936 Found in file handy.h
1940 Tells Perl to C<require> the file named by the string argument. It is
1941 analogous to the Perl code C<eval "require '$file'">. It's even
1942 implemented that way; consider using Perl_load_module instead.
1944 NOTE: the perl_ form of this function is deprecated.
1946 void require_pv(const char* pv)
1949 Found in file perl.c
1953 Variable which is setup by C<xsubpp> to hold the return value for an
1954 XSUB. This is always the proper type for the XSUB. See
1955 L<perlxs/"The RETVAL Variable">.
1960 Found in file XSUB.h
1964 The XSUB-writer's interface to the C C<free> function.
1966 void Safefree(void* ptr)
1969 Found in file handy.h
1973 Copy a string to a safe spot. This does not use an SV.
1975 char* savepv(const char* sv)
1978 Found in file util.c
1982 Copy a string to a safe spot. The C<len> indicates number of bytes to
1983 copy. This does not use an SV.
1985 char* savepvn(const char* sv, I32 len)
1988 Found in file util.c
1992 Opening bracket for temporaries on a callback. See C<FREETMPS> and
1998 Found in file scope.h
2002 For backwards compatibility. Use C<grok_bin> instead.
2004 NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
2007 Found in file numeric.c
2011 For backwards compatibility. Use C<grok_hex> instead.
2013 NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
2016 Found in file numeric.c
2020 For backwards compatibility. Use C<grok_oct> instead.
2022 NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
2025 Found in file numeric.c
2029 Tries to find if a given SV has a shared backend, either by
2030 looking at magic, or by checking if it is tied again threads::shared.
2032 shared_sv* sharedsv_find(SV* sv)
2035 Found in file sharedsv.c
2039 Saves a space for keeping SVs wider than an interpreter,
2040 currently only stores a pointer to the first interpreter.
2042 void sharedsv_init()
2045 Found in file sharedsv.c
2049 Recursive locks on a sharedsv.
2050 Locks are dynamically scoped at the level of the first lock.
2051 void sharedsv_lock(shared_sv* ssv)
2054 Found in file sharedsv.c
2058 Allocates a new shared sv struct, you must yourself create the SV/AV/HV.
2059 shared_sv* sharedsv_new()
2062 Found in file sharedsv.c
2064 =item sharedsv_thrcnt_dec
2066 Decrements the threadcount of a shared sv. When a threads frontend is freed
2067 this function should be called.
2069 void sharedsv_thrcnt_dec(shared_sv* ssv)
2072 Found in file sharedsv.c
2074 =item sharedsv_thrcnt_inc
2076 Increments the threadcount of a sharedsv.
2077 void sharedsv_thrcnt_inc(shared_sv* ssv)
2080 Found in file sharedsv.c
2082 =item sharedsv_unlock
2084 Recursively unlocks a shared sv.
2086 void sharedsv_unlock(shared_sv* ssv)
2089 Found in file sharedsv.c
2093 Sort an array. Here is an example:
2095 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
2097 void sortsv(SV ** array, size_t num_elts, SVCOMPARE_t cmp)
2100 Found in file pp_sort.c
2104 Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
2112 Refetch the stack pointer. Used after a callback. See L<perlcall>.
2121 Used to access elements on the XSUB's stack.
2126 Found in file XSUB.h
2130 Test two strings to see if they are equal. Returns true or false.
2132 bool strEQ(char* s1, char* s2)
2135 Found in file handy.h
2139 Test two strings to see if the first, C<s1>, is greater than or equal to
2140 the second, C<s2>. Returns true or false.
2142 bool strGE(char* s1, char* s2)
2145 Found in file handy.h
2149 Test two strings to see if the first, C<s1>, is greater than the second,
2150 C<s2>. Returns true or false.
2152 bool strGT(char* s1, char* s2)
2155 Found in file handy.h
2159 Test two strings to see if the first, C<s1>, is less than or equal to the
2160 second, C<s2>. Returns true or false.
2162 bool strLE(char* s1, char* s2)
2165 Found in file handy.h
2169 Test two strings to see if the first, C<s1>, is less than the second,
2170 C<s2>. Returns true or false.
2172 bool strLT(char* s1, char* s2)
2175 Found in file handy.h
2179 Test two strings to see if they are different. Returns true or
2182 bool strNE(char* s1, char* s2)
2185 Found in file handy.h
2189 Test two strings to see if they are equal. The C<len> parameter indicates
2190 the number of bytes to compare. Returns true or false. (A wrapper for
2193 bool strnEQ(char* s1, char* s2, STRLEN len)
2196 Found in file handy.h
2200 Test two strings to see if they are different. The C<len> parameter
2201 indicates the number of bytes to compare. Returns true or false. (A
2202 wrapper for C<strncmp>).
2204 bool strnNE(char* s1, char* s2, STRLEN len)
2207 Found in file handy.h
2211 This is an architecture-independent macro to copy one structure to another.
2213 void StructCopy(type src, type dest, type)
2216 Found in file handy.h
2220 Returns the length of the string which is in the SV. See C<SvLEN>.
2222 STRLEN SvCUR(SV* sv)
2229 Set the length of the string which is in the SV. See C<SvCUR>.
2231 void SvCUR_set(SV* sv, STRLEN len)
2238 Returns a pointer to the last character in the string which is in the SV.
2239 See C<SvCUR>. Access the character as *(SvEND(sv)).
2248 Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
2249 argument more than once.
2251 void SvGETMAGIC(SV* sv)
2258 Expands the character buffer in the SV so that it has room for the
2259 indicated number of bytes (remember to reserve space for an extra trailing
2260 NUL character). Calls C<sv_grow> to perform the expansion if necessary.
2261 Returns a pointer to the character buffer.
2263 char * SvGROW(SV* sv, STRLEN len)
2270 Returns a boolean indicating whether the SV contains an integer.
2279 Returns a boolean indicating whether the SV contains an integer. Checks
2280 the B<private> setting. Use C<SvIOK>.
2289 Returns a boolean indicating whether the SV contains a signed integer.
2291 void SvIOK_notUV(SV* sv)
2298 Unsets the IV status of an SV.
2300 void SvIOK_off(SV* sv)
2307 Tells an SV that it is an integer.
2309 void SvIOK_on(SV* sv)
2316 Tells an SV that it is an integer and disables all other OK bits.
2318 void SvIOK_only(SV* sv)
2325 Tells and SV that it is an unsigned integer and disables all other OK bits.
2327 void SvIOK_only_UV(SV* sv)
2334 Returns a boolean indicating whether the SV contains an unsigned integer.
2336 void SvIOK_UV(SV* sv)
2343 Coerces the given SV to an integer and returns it. See C<SvIVx> for a
2344 version which guarantees to evaluate sv only once.
2353 Returns the raw value in the SV's IV slot, without checks or conversions.
2354 Only use when you are sure SvIOK is true. See also C<SvIV()>.
2363 Coerces the given SV to an integer and returns it. Guarantees to evaluate
2364 sv only once. Use the more efficient C<SvIV> otherwise.
2373 Returns the size of the string buffer in the SV, not including any part
2374 attributable to C<SvOOK>. See C<SvCUR>.
2376 STRLEN SvLEN(SV* sv)
2383 Returns a boolean indicating whether the SV contains a number, integer or
2393 Returns a boolean indicating whether the SV contains a number, integer or
2394 double. Checks the B<private> setting. Use C<SvNIOK>.
2396 bool SvNIOKp(SV* sv)
2403 Unsets the NV/IV status of an SV.
2405 void SvNIOK_off(SV* sv)
2412 Returns a boolean indicating whether the SV contains a double.
2421 Returns a boolean indicating whether the SV contains a double. Checks the
2422 B<private> setting. Use C<SvNOK>.
2431 Unsets the NV status of an SV.
2433 void SvNOK_off(SV* sv)
2440 Tells an SV that it is a double.
2442 void SvNOK_on(SV* sv)
2449 Tells an SV that it is a double and disables all other OK bits.
2451 void SvNOK_only(SV* sv)
2458 Coerce the given SV to a double and return it. See C<SvNVx> for a version
2459 which guarantees to evaluate sv only once.
2468 Coerces the given SV to a double and returns it. Guarantees to evaluate
2469 sv only once. Use the more efficient C<SvNV> otherwise.
2478 Returns the raw value in the SV's NV slot, without checks or conversions.
2479 Only use when you are sure SvNOK is true. See also C<SvNV()>.
2488 Returns a boolean indicating whether the value is an SV.
2497 Returns a boolean indicating whether the SvIVX is a valid offset value for
2498 the SvPVX. This hack is used internally to speed up removal of characters
2499 from the beginning of a SvPV. When SvOOK is true, then the start of the
2500 allocated string buffer is really (SvPVX - SvIVX).
2509 Returns a boolean indicating whether the SV contains a character
2519 Returns a boolean indicating whether the SV contains a character string.
2520 Checks the B<private> setting. Use C<SvPOK>.
2529 Unsets the PV status of an SV.
2531 void SvPOK_off(SV* sv)
2538 Tells an SV that it is a string.
2540 void SvPOK_on(SV* sv)
2547 Tells an SV that it is a string and disables all other OK bits.
2548 Will also turn off the UTF8 status.
2550 void SvPOK_only(SV* sv)
2555 =item SvPOK_only_UTF8
2557 Tells an SV that it is a string and disables all other OK bits,
2558 and leaves the UTF8 status as it was.
2560 void SvPOK_only_UTF8(SV* sv)
2567 Returns a pointer to the string in the SV, or a stringified form of the SV
2568 if the SV does not contain a string. Handles 'get' magic. See also
2569 C<SvPVx> for a version which guarantees to evaluate sv only once.
2571 char* SvPV(SV* sv, STRLEN len)
2578 Like C<SvPV>, but converts sv to byte representation first if necessary.
2580 char* SvPVbyte(SV* sv, STRLEN len)
2587 Like C<SvPV>, but converts sv to byte representation first if necessary.
2588 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
2592 char* SvPVbytex(SV* sv, STRLEN len)
2597 =item SvPVbytex_force
2599 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2600 Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
2603 char* SvPVbytex_force(SV* sv, STRLEN len)
2608 =item SvPVbyte_force
2610 Like C<SvPV_force>, but converts sv to byte representation first if necessary.
2612 char* SvPVbyte_force(SV* sv, STRLEN len)
2617 =item SvPVbyte_nolen
2619 Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
2621 char* SvPVbyte_nolen(SV* sv)
2628 Like C<SvPV>, but converts sv to utf8 first if necessary.
2630 char* SvPVutf8(SV* sv, STRLEN len)
2637 Like C<SvPV>, but converts sv to utf8 first if necessary.
2638 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
2641 char* SvPVutf8x(SV* sv, STRLEN len)
2646 =item SvPVutf8x_force
2648 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2649 Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
2652 char* SvPVutf8x_force(SV* sv, STRLEN len)
2657 =item SvPVutf8_force
2659 Like C<SvPV_force>, but converts sv to utf8 first if necessary.
2661 char* SvPVutf8_force(SV* sv, STRLEN len)
2666 =item SvPVutf8_nolen
2668 Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
2670 char* SvPVutf8_nolen(SV* sv)
2677 Returns a pointer to the physical string in the SV. The SV must contain a
2687 A version of C<SvPV> which guarantees to evaluate sv only once.
2689 char* SvPVx(SV* sv, STRLEN len)
2696 Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2697 force if you are going to update the SvPVX directly.
2699 char* SvPV_force(SV* sv, STRLEN len)
2704 =item SvPV_force_nomg
2706 Like <SvPV> but will force the SV into becoming a string (SvPOK). You want
2707 force if you are going to update the SvPVX directly. Doesn't process magic.
2709 char* SvPV_force_nomg(SV* sv, STRLEN len)
2716 Returns a pointer to the string in the SV, or a stringified form of the SV
2717 if the SV does not contain a string. Handles 'get' magic.
2719 char* SvPV_nolen(SV* sv)
2726 Returns the value of the object's reference count.
2728 U32 SvREFCNT(SV* sv)
2735 Decrements the reference count of the given SV.
2737 void SvREFCNT_dec(SV* sv)
2744 Increments the reference count of the given SV.
2746 SV* SvREFCNT_inc(SV* sv)
2753 Tests if the SV is an RV.
2762 Unsets the RV status of an SV.
2764 void SvROK_off(SV* sv)
2771 Tells an SV that it is an RV.
2773 void SvROK_on(SV* sv)
2780 Dereferences an RV to return the SV.
2789 Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
2790 argument more than once.
2792 void SvSETMAGIC(SV* sv)
2799 Like C<SvSetSV>, but does any set magic required afterwards.
2801 void SvSetMagicSV(SV* dsb, SV* ssv)
2806 =item SvSetMagicSV_nosteal
2808 Like C<SvSetMagicSV>, but does any set magic required afterwards.
2810 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
2817 Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
2820 void SvSetSV(SV* dsb, SV* ssv)
2825 =item SvSetSV_nosteal
2827 Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
2828 ssv. May evaluate arguments more than once.
2830 void SvSetSV_nosteal(SV* dsv, SV* ssv)
2837 Returns the stash of the SV.
2846 Taints an SV if tainting is enabled
2848 void SvTAINT(SV* sv)
2855 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
2858 bool SvTAINTED(SV* sv)
2865 Untaints an SV. Be I<very> careful with this routine, as it short-circuits
2866 some of Perl's fundamental security features. XS module authors should not
2867 use this function unless they fully understand all the implications of
2868 unconditionally untainting the value. Untainting should be done in the
2869 standard perl fashion, via a carefully crafted regexp, rather than directly
2870 untainting variables.
2872 void SvTAINTED_off(SV* sv)
2879 Marks an SV as tainted.
2881 void SvTAINTED_on(SV* sv)
2888 Returns a boolean indicating whether Perl would evaluate the SV as true or
2889 false, defined or undefined. Does not handle 'get' magic.
2898 An enum of flags for Perl types. These are found in the file B<sv.h>
2899 in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
2906 Returns the type of the SV. See C<svtype>.
2908 svtype SvTYPE(SV* sv)
2915 Integer type flag for scalars. See C<svtype>.
2922 Double type flag for scalars. See C<svtype>.
2929 Pointer type flag for scalars. See C<svtype>.
2936 Type flag for arrays. See C<svtype>.
2943 Type flag for code refs. See C<svtype>.
2950 Type flag for hashes. See C<svtype>.
2957 Type flag for blessed scalars. See C<svtype>.
2964 Returns a boolean indicating whether the SV contains an unsigned integer.
2973 Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
2974 perform the upgrade if necessary. See C<svtype>.
2976 void SvUPGRADE(SV* sv, svtype type)
2983 Returns a boolean indicating whether the SV contains UTF-8 encoded data.
2992 Unsets the UTF8 status of an SV.
2994 void SvUTF8_off(SV *sv)
3001 Turn on the UTF8 status of an SV (the data is not changed, just the flag).
3002 Do not use frivolously.
3004 void SvUTF8_on(SV *sv)
3011 Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
3012 for a version which guarantees to evaluate sv only once.
3021 Coerces the given SV to an unsigned integer and returns it. Guarantees to
3022 evaluate sv only once. Use the more efficient C<SvUV> otherwise.
3031 Returns the raw value in the SV's UV slot, without checks or conversions.
3032 Only use when you are sure SvIOK is true. See also C<SvUV()>.
3041 This function is only called on magical items, and is only used by
3042 sv_true() or its macro equivalent.
3044 bool sv_2bool(SV* sv)
3051 Using various gambits, try to get a CV from an SV; in addition, try if
3052 possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
3054 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
3061 Using various gambits, try to get an IO from an SV: the IO slot if its a
3062 GV; or the recursive result if we're an RV; or the IO slot of the symbol
3063 named after the PV if we're a string.
3072 Return the integer value of an SV, doing any necessary string conversion,
3073 magic etc. Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
3082 Marks an existing SV as mortal. The SV will be destroyed "soon", either
3083 by an explicit call to FREETMPS, or by an implicit call at places such as
3084 statement boundaries. See also C<sv_newmortal> and C<sv_mortalcopy>.
3086 SV* sv_2mortal(SV* sv)
3093 Return the num value of an SV, doing any necessary string or integer
3094 conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
3104 Return a pointer to the byte-encoded representation of the SV, and set *lp
3105 to its length. May cause the SV to be downgraded from UTF8 as a
3108 Usually accessed via the C<SvPVbyte> macro.
3110 char* sv_2pvbyte(SV* sv, STRLEN* lp)
3115 =item sv_2pvbyte_nolen
3117 Return a pointer to the byte-encoded representation of the SV.
3118 May cause the SV to be downgraded from UTF8 as a side-effect.
3120 Usually accessed via the C<SvPVbyte_nolen> macro.
3122 char* sv_2pvbyte_nolen(SV* sv)
3129 Return a pointer to the UTF8-encoded representation of the SV, and set *lp
3130 to its length. May cause the SV to be upgraded to UTF8 as a side-effect.
3132 Usually accessed via the C<SvPVutf8> macro.
3134 char* sv_2pvutf8(SV* sv, STRLEN* lp)
3139 =item sv_2pvutf8_nolen
3141 Return a pointer to the UTF8-encoded representation of the SV.
3142 May cause the SV to be upgraded to UTF8 as a side-effect.
3144 Usually accessed via the C<SvPVutf8_nolen> macro.
3146 char* sv_2pvutf8_nolen(SV* sv)
3153 Returns a pointer to the string value of an SV, and sets *lp to its length.
3154 If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
3156 Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
3157 usually end up here too.
3159 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
3166 Like C<sv_2pv()>, but doesn't return the length too. You should usually
3167 use the macro wrapper C<SvPV_nolen(sv)> instead.
3168 char* sv_2pv_nolen(SV* sv)
3175 Return the unsigned integer value of an SV, doing any necessary string
3176 conversion, magic etc. Normally used via the C<SvUV(sv)> and C<SvUVx(sv)>
3186 Remove any string offset. You should normally use the C<SvOOK_off> macro
3189 int sv_backoff(SV* sv)
3196 Blesses an SV into a specified package. The SV must be an RV. The package
3197 must be designated by its stash (see C<gv_stashpv()>). The reference count
3198 of the SV is unaffected.
3200 SV* sv_bless(SV* sv, HV* stash)
3207 Concatenates the string onto the end of the string which is in the SV.
3208 If the SV has the UTF8 status set, then the bytes appended should be
3209 valid UTF8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
3211 void sv_catpv(SV* sv, const char* ptr)
3218 Processes its arguments like C<sprintf> and appends the formatted
3219 output to an SV. If the appended data contains "wide" characters
3220 (including, but not limited to, SVs with a UTF-8 PV formatted with %s,
3221 and characters >255 formatted with %c), the original SV might get
3222 upgraded to UTF-8. Handles 'get' magic, but not 'set' magic.
3223 C<SvSETMAGIC()> must typically be called after calling this function
3224 to handle 'set' magic.
3226 void sv_catpvf(SV* sv, const char* pat, ...)
3233 Like C<sv_catpvf>, but also handles 'set' magic.
3235 void sv_catpvf_mg(SV *sv, const char* pat, ...)
3242 Concatenates the string onto the end of the string which is in the SV. The
3243 C<len> indicates number of bytes to copy. If the SV has the UTF8
3244 status set, then the bytes appended should be valid UTF8.
3245 Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
3247 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
3252 =item sv_catpvn_flags
3254 Concatenates the string onto the end of the string which is in the SV. The
3255 C<len> indicates number of bytes to copy. If the SV has the UTF8
3256 status set, then the bytes appended should be valid UTF8.
3257 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
3258 appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
3259 in terms of this function.
3261 void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
3268 Like C<sv_catpvn>, but also handles 'set' magic.
3270 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
3277 Like C<sv_catpv>, but also handles 'set' magic.
3279 void sv_catpv_mg(SV *sv, const char *ptr)
3286 Concatenates the string from SV C<ssv> onto the end of the string in
3287 SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
3288 not 'set' magic. See C<sv_catsv_mg>.
3290 void sv_catsv(SV* dsv, SV* ssv)
3295 =item sv_catsv_flags
3297 Concatenates the string from SV C<ssv> onto the end of the string in
3298 SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
3299 bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
3300 and C<sv_catsv_nomg> are implemented in terms of this function.
3302 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
3309 Like C<sv_catsv>, but also handles 'set' magic.
3311 void sv_catsv_mg(SV *dstr, SV *sstr)
3318 Efficient removal of characters from the beginning of the string buffer.
3319 SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
3320 the string buffer. The C<ptr> becomes the first character of the adjusted
3321 string. Uses the "OOK hack".
3323 void sv_chop(SV* sv, char* ptr)
3330 Clear an SV: call any destructors, free up any memory used by the body,
3331 and free the body itself. The SV's head is I<not> freed, although
3332 its type is set to all 1's so that it won't inadvertently be assumed
3333 to be live during global destruction etc.
3334 This function should only be called when REFCNT is zero. Most of the time
3335 you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
3338 void sv_clear(SV* sv)
3345 Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
3346 string in C<sv1> is less than, equal to, or greater than the string in
3347 C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3348 coerce its args to strings if necessary. See also C<sv_cmp_locale>.
3350 I32 sv_cmp(SV* sv1, SV* sv2)
3357 Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
3358 'use bytes' aware, handles get magic, and will coerce its args to strings
3359 if necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>.
3361 I32 sv_cmp_locale(SV* sv1, SV* sv2)
3368 Add Collate Transform magic to an SV if it doesn't already have it.
3370 Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
3371 scalar data of the variable, but transformed to such a format that a normal
3372 memory comparison can be used to compare the data according to the locale
3375 char* sv_collxfrm(SV* sv, STRLEN* nxp)
3382 Auto-decrement of the value in the SV, doing string to numeric conversion
3383 if necessary. Handles 'get' magic.
3390 =item sv_derived_from
3392 Returns a boolean indicating whether the SV is derived from the specified
3393 class. This is the function that implements C<UNIVERSAL::isa>. It works
3394 for class names as well as for objects.
3396 bool sv_derived_from(SV* sv, const char* name)
3399 Found in file universal.c
3403 Returns a boolean indicating whether the strings in the two SVs are
3404 identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
3405 coerce its args to strings if necessary.
3407 I32 sv_eq(SV* sv1, SV* sv2)
3412 =item sv_force_normal
3414 Undo various types of fakery on an SV: if the PV is a shared string, make
3415 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3416 an xpvmg. See also C<sv_force_normal_flags>.
3418 void sv_force_normal(SV *sv)
3423 =item sv_force_normal_flags
3425 Undo various types of fakery on an SV: if the PV is a shared string, make
3426 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
3427 an xpvmg. The C<flags> parameter gets passed to C<sv_unref_flags()>
3428 when unrefing. C<sv_force_normal> calls this function with flags set to 0.
3430 void sv_force_normal_flags(SV *sv, U32 flags)
3437 Decrement an SV's reference count, and if it drops to zero, call
3438 C<sv_clear> to invoke destructors and free up any memory used by
3439 the body; finally, deallocate the SV's head itself.
3440 Normally called via a wrapper macro C<SvREFCNT_dec>.
3442 void sv_free(SV* sv)
3449 Get a line from the filehandle and store it into the SV, optionally
3450 appending to the currently-stored string.
3452 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
3459 Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
3460 upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
3461 Use the C<SvGROW> wrapper instead.
3463 char* sv_grow(SV* sv, STRLEN newlen)
3470 Auto-increment of the value in the SV, doing string to numeric conversion
3471 if necessary. Handles 'get' magic.
3480 Inserts a string at the specified offset/length within the SV. Similar to
3481 the Perl substr() function.
3483 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
3490 Returns a boolean indicating whether the SV is blessed into the specified
3491 class. This does not check for subtypes; use C<sv_derived_from> to verify
3492 an inheritance relationship.
3494 int sv_isa(SV* sv, const char* name)
3501 Returns a boolean indicating whether the SV is an RV pointing to a blessed
3502 object. If the SV is not an RV, or if the object is not blessed, then this
3505 int sv_isobject(SV* sv)
3512 A private implementation of the C<SvIVx> macro for compilers which can't
3513 cope with complex macro expressions. Always use the macro instead.
3522 Returns the length of the string in the SV. Handles magic and type
3523 coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
3525 STRLEN sv_len(SV* sv)
3532 Returns the number of characters in the string in an SV, counting wide
3533 UTF8 bytes as a single character. Handles magic and type coercion.
3535 STRLEN sv_len_utf8(SV* sv)
3542 Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
3543 then adds a new magic item of type C<how> to the head of the magic list.
3545 C<name> is assumed to contain an C<SV*> if C<(name && namelen == HEf_SVKEY)>
3547 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
3554 Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
3555 The new SV is marked as mortal. It will be destroyed "soon", either by an
3556 explicit call to FREETMPS, or by an implicit call at places such as
3557 statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
3559 SV* sv_mortalcopy(SV* oldsv)
3566 Creates a new null SV which is mortal. The reference count of the SV is
3567 set to 1. It will be destroyed "soon", either by an explicit call to
3568 FREETMPS, or by an implicit call at places such as statement boundaries.
3569 See also C<sv_mortalcopy> and C<sv_2mortal>.
3578 Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
3581 SV* sv_newref(SV* sv)
3588 A private implementation of the C<SvNVx> macro for compilers which can't
3589 cope with complex macro expressions. Always use the macro instead.
3598 Converts the value pointed to by offsetp from a count of bytes from the
3599 start of the string, to a count of the equivalent number of UTF8 chars.
3600 Handles magic and type coercion.
3602 void sv_pos_b2u(SV* sv, I32* offsetp)
3609 Converts the value pointed to by offsetp from a count of UTF8 chars from
3610 the start of the string, to a count of the equivalent number of bytes; if
3611 lenp is non-zero, it does the same to lenp, but this time starting from
3612 the offset, rather than from the start of the string. Handles magic and
3615 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
3622 A private implementation of the C<SvPV_nolen> macro for compilers which can't
3623 cope with complex macro expressions. Always use the macro instead.
3632 A private implementation of the C<SvPVbyte_nolen> macro for compilers
3633 which can't cope with complex macro expressions. Always use the macro
3636 char* sv_pvbyte(SV *sv)
3643 A private implementation of the C<SvPVbyte> macro for compilers
3644 which can't cope with complex macro expressions. Always use the macro
3647 char* sv_pvbyten(SV *sv, STRLEN *len)
3652 =item sv_pvbyten_force
3654 A private implementation of the C<SvPVbytex_force> macro for compilers
3655 which can't cope with complex macro expressions. Always use the macro
3658 char* sv_pvbyten_force(SV* sv, STRLEN* lp)
3665 A private implementation of the C<SvPV> macro for compilers which can't
3666 cope with complex macro expressions. Always use the macro instead.
3668 char* sv_pvn(SV *sv, STRLEN *len)
3675 Get a sensible string out of the SV somehow.
3676 A private implementation of the C<SvPV_force> macro for compilers which
3677 can't cope with complex macro expressions. Always use the macro instead.
3679 char* sv_pvn_force(SV* sv, STRLEN* lp)
3684 =item sv_pvn_force_flags
3686 Get a sensible string out of the SV somehow.
3687 If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
3688 appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
3689 implemented in terms of this function.
3690 You normally want to use the various wrapper macros instead: see
3691 C<SvPV_force> and C<SvPV_force_nomg>
3693 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
3700 A private implementation of the C<SvPVutf8_nolen> macro for compilers
3701 which can't cope with complex macro expressions. Always use the macro
3704 char* sv_pvutf8(SV *sv)
3711 A private implementation of the C<SvPVutf8> macro for compilers
3712 which can't cope with complex macro expressions. Always use the macro
3715 char* sv_pvutf8n(SV *sv, STRLEN *len)
3720 =item sv_pvutf8n_force
3722 A private implementation of the C<SvPVutf8_force> macro for compilers
3723 which can't cope with complex macro expressions. Always use the macro
3726 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
3731 =item sv_recode_to_utf8
3733 The encoding is assumed to be an Encode object, on entry the PV
3734 of the sv is assumed to be octets in that encoding, and the sv
3735 will be converted into Unicode (and UTF-8).
3737 If the sv already is UTF-8 (or if it is not POK), or if the encoding
3738 is not a reference, nothing is done to the sv. If the encoding is not
3739 an C<Encode::XS> Encoding object, bad things will happen.
3740 (See F<lib/encoding.pm> and L<Encode>).
3742 The PV of the sv is returned.
3744 char* sv_recode_to_utf8(SV* sv, SV *encoding)
3751 Returns a string describing what the SV is a reference to.
3753 char* sv_reftype(SV* sv, int ob)
3760 Make the first argument a copy of the second, then delete the original.
3761 The target SV physically takes over ownership of the body of the source SV
3762 and inherits its flags; however, the target keeps any magic it owns,
3763 and any magic in the source is discarded.
3764 Note that this is a rather specialist SV copying operation; most of the
3765 time you'll want to use C<sv_setsv> or one of its many macro front-ends.
3767 void sv_replace(SV* sv, SV* nsv)
3772 =item sv_report_used
3774 Dump the contents of all SVs not yet freed. (Debugging aid).
3776 void sv_report_used()
3783 Underlying implementation for the C<reset> Perl function.
3784 Note that the perl-level function is vaguely deprecated.
3786 void sv_reset(char* s, HV* stash)
3793 Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
3794 referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
3795 push a back-reference to this RV onto the array of backreferences
3796 associated with that magic.
3798 SV* sv_rvweaken(SV *sv)
3805 Copies an integer into the given SV, upgrading first if necessary.
3806 Does not handle 'set' magic. See also C<sv_setiv_mg>.
3808 void sv_setiv(SV* sv, IV num)
3815 Like C<sv_setiv>, but also handles 'set' magic.
3817 void sv_setiv_mg(SV *sv, IV i)
3824 Copies a double into the given SV, upgrading first if necessary.
3825 Does not handle 'set' magic. See also C<sv_setnv_mg>.
3827 void sv_setnv(SV* sv, NV num)
3834 Like C<sv_setnv>, but also handles 'set' magic.
3836 void sv_setnv_mg(SV *sv, NV num)
3843 Copies a string into an SV. The string must be null-terminated. Does not
3844 handle 'set' magic. See C<sv_setpv_mg>.
3846 void sv_setpv(SV* sv, const char* ptr)
3853 Processes its arguments like C<sprintf> and sets an SV to the formatted
3854 output. Does not handle 'set' magic. See C<sv_setpvf_mg>.
3856 void sv_setpvf(SV* sv, const char* pat, ...)
3863 Like C<sv_setpvf>, but also handles 'set' magic.
3865 void sv_setpvf_mg(SV *sv, const char* pat, ...)
3872 Copies an integer into the given SV, also updating its string value.
3873 Does not handle 'set' magic. See C<sv_setpviv_mg>.
3875 void sv_setpviv(SV* sv, IV num)
3882 Like C<sv_setpviv>, but also handles 'set' magic.
3884 void sv_setpviv_mg(SV *sv, IV iv)
3891 Copies a string into an SV. The C<len> parameter indicates the number of
3892 bytes to be copied. Does not handle 'set' magic. See C<sv_setpvn_mg>.
3894 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
3901 Like C<sv_setpvn>, but also handles 'set' magic.
3903 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
3910 Like C<sv_setpv>, but also handles 'set' magic.
3912 void sv_setpv_mg(SV *sv, const char *ptr)
3919 Copies an integer into a new SV, optionally blessing the SV. The C<rv>
3920 argument will be upgraded to an RV. That RV will be modified to point to
3921 the new SV. The C<classname> argument indicates the package for the
3922 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3923 will be returned and will have a reference count of 1.
3925 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
3932 Copies a double into a new SV, optionally blessing the SV. The C<rv>
3933 argument will be upgraded to an RV. That RV will be modified to point to
3934 the new SV. The C<classname> argument indicates the package for the
3935 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3936 will be returned and will have a reference count of 1.
3938 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
3945 Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
3946 argument will be upgraded to an RV. That RV will be modified to point to
3947 the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
3948 into the SV. The C<classname> argument indicates the package for the
3949 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3950 will be returned and will have a reference count of 1.
3952 Do not use with other Perl types such as HV, AV, SV, CV, because those
3953 objects will become corrupted by the pointer copy process.
3955 Note that C<sv_setref_pvn> copies the string while this copies the pointer.
3957 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
3964 Copies a string into a new SV, optionally blessing the SV. The length of the
3965 string must be specified with C<n>. The C<rv> argument will be upgraded to
3966 an RV. That RV will be modified to point to the new SV. The C<classname>
3967 argument indicates the package for the blessing. Set C<classname> to
3968 C<Nullch> to avoid the blessing. The new SV will be returned and will have
3969 a reference count of 1.
3971 Note that C<sv_setref_pv> copies the pointer while this copies the string.
3973 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
3980 Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
3981 argument will be upgraded to an RV. That RV will be modified to point to
3982 the new SV. The C<classname> argument indicates the package for the
3983 blessing. Set C<classname> to C<Nullch> to avoid the blessing. The new SV
3984 will be returned and will have a reference count of 1.
3986 SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
3993 Copies the contents of the source SV C<ssv> into the destination SV
3994 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
3995 function if the source SV needs to be reused. Does not handle 'set' magic.
3996 Loosely speaking, it performs a copy-by-value, obliterating any previous
3997 content of the destination.
3999 You probably want to use one of the assortment of wrappers, such as
4000 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4001 C<SvSetMagicSV_nosteal>.
4004 void sv_setsv(SV* dsv, SV* ssv)
4009 =item sv_setsv_flags
4011 Copies the contents of the source SV C<ssv> into the destination SV
4012 C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
4013 function if the source SV needs to be reused. Does not handle 'set' magic.
4014 Loosely speaking, it performs a copy-by-value, obliterating any previous
4015 content of the destination.
4016 If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
4017 C<ssv> if appropriate, else not. C<sv_setsv> and C<sv_setsv_nomg> are
4018 implemented in terms of this function.
4020 You probably want to use one of the assortment of wrappers, such as
4021 C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
4022 C<SvSetMagicSV_nosteal>.
4024 This is the primary function for copying scalars, and most other
4025 copy-ish functions and macros use this underneath.
4027 void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
4034 Like C<sv_setsv>, but also handles 'set' magic.
4036 void sv_setsv_mg(SV *dstr, SV *sstr)
4043 Copies an unsigned integer into the given SV, upgrading first if necessary.
4044 Does not handle 'set' magic. See also C<sv_setuv_mg>.
4046 void sv_setuv(SV* sv, UV num)
4053 Like C<sv_setuv>, but also handles 'set' magic.
4055 void sv_setuv_mg(SV *sv, UV u)
4062 Taint an SV. Use C<SvTAINTED_on> instead.
4063 void sv_taint(SV* sv)
4070 Test an SV for taintedness. Use C<SvTAINTED> instead.
4071 bool sv_tainted(SV* sv)
4078 Returns true if the SV has a true value by Perl's rules.
4079 Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
4080 instead use an in-line version.
4087 =item sv_uni_display
4089 Build to the scalar dsv a displayable version of the scalar sv,
4090 he displayable version being at most pvlim bytes long
4091 (if longer, the rest is truncated and "..." will be appended).
4092 The flags argument is currently unused but available for future extensions.
4093 The pointer to the PV of the dsv is returned.
4095 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
4098 Found in file utf8.c
4102 Removes all magic of type C<type> from an SV.
4104 int sv_unmagic(SV* sv, int type)
4111 Unsets the RV status of the SV, and decrements the reference count of
4112 whatever was being referenced by the RV. This can almost be thought of
4113 as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
4114 being zero. See C<SvROK_off>.
4116 void sv_unref(SV* sv)
4121 =item sv_unref_flags
4123 Unsets the RV status of the SV, and decrements the reference count of
4124 whatever was being referenced by the RV. This can almost be thought of
4125 as a reversal of C<newSVrv>. The C<cflags> argument can contain
4126 C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
4127 (otherwise the decrementing is conditional on the reference count being
4128 different from one or the reference being a readonly SV).
4131 void sv_unref_flags(SV* sv, U32 flags)
4138 Untaint an SV. Use C<SvTAINTED_off> instead.
4139 void sv_untaint(SV* sv)
4146 Upgrade an SV to a more complex form. Generally adds a new body type to the
4147 SV, then copies across as much information as possible from the old body.
4148 You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
4150 bool sv_upgrade(SV* sv, U32 mt)
4157 Tells an SV to use C<ptr> to find its string value. Normally the string is
4158 stored inside the SV but sv_usepvn allows the SV to use an outside string.
4159 The C<ptr> should point to memory that was allocated by C<malloc>. The
4160 string length, C<len>, must be supplied. This function will realloc the
4161 memory pointed to by C<ptr>, so that pointer should not be freed or used by
4162 the programmer after giving it to sv_usepvn. Does not handle 'set' magic.
4163 See C<sv_usepvn_mg>.
4165 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
4172 Like C<sv_usepvn>, but also handles 'set' magic.
4174 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
4179 =item sv_utf8_decode
4181 Convert the octets in the PV from UTF-8 to chars. Scan for validity and then
4182 turn off SvUTF8 if needed so that we see characters. Used as a building block
4183 for decode_utf8 in Encode.xs
4185 NOTE: this function is experimental and may change or be
4186 removed without notice.
4188 bool sv_utf8_decode(SV *sv)
4193 =item sv_utf8_downgrade
4195 Attempt to convert the PV of an SV from UTF8-encoded to byte encoding.
4196 This may not be possible if the PV contains non-byte encoding characters;
4197 if this is the case, either returns false or, if C<fail_ok> is not
4200 NOTE: this function is experimental and may change or be
4201 removed without notice.
4203 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
4208 =item sv_utf8_encode
4210 Convert the PV of an SV to UTF8-encoded, but then turn off the C<SvUTF8>
4211 flag so that it looks like octets again. Used as a building block
4212 for encode_utf8 in Encode.xs
4214 void sv_utf8_encode(SV *sv)
4219 =item sv_utf8_upgrade
4221 Convert the PV of an SV to its UTF8-encoded form.
4222 Forces the SV to string form if it is not already.
4223 Always sets the SvUTF8 flag to avoid future validity checks even
4224 if all the bytes have hibit clear.
4226 STRLEN sv_utf8_upgrade(SV *sv)
4231 =item sv_utf8_upgrade_flags
4233 Convert the PV of an SV to its UTF8-encoded form.
4234 Forces the SV to string form if it is not already.
4235 Always sets the SvUTF8 flag to avoid future validity checks even
4236 if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
4237 will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
4238 C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
4240 STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
4247 A private implementation of the C<SvUVx> macro for compilers which can't
4248 cope with complex macro expressions. Always use the macro instead.
4257 Processes its arguments like C<vsprintf> and appends the formatted output
4258 to an SV. Uses an array of SVs if the C style variable argument list is
4259 missing (NULL). When running with taint checks enabled, indicates via
4260 C<maybe_tainted> if results are untrustworthy (often due to the use of
4263 Usually used via one of its frontends C<sv_catpvf> and C<sv_catpvf_mg>.
4265 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4272 Works like C<vcatpvfn> but copies the text into the SV instead of
4275 Usually used via one of its frontends C<sv_setpvf> and C<sv_setpvf_mg>.
4277 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
4284 Variable which is setup by C<xsubpp> to designate the object in a C++
4285 XSUB. This is always the proper type for the C++ object. See C<CLASS> and
4286 L<perlxs/"Using XS With C++">.
4291 Found in file XSUB.h
4295 Converts the specified character to lowercase.
4297 char toLOWER(char ch)
4300 Found in file handy.h
4304 Converts the specified character to uppercase.
4306 char toUPPER(char ch)
4309 Found in file handy.h
4313 The "p" contains the pointer to the UTF-8 string encoding
4314 the character that is being converted.
4316 The "ustrp" is a pointer to the character buffer to put the
4317 conversion result to. The "lenp" is a pointer to the length
4320 The "swash" is a pointer to the swash to use.
4322 The "normal" is a string like "ToLower" which means the swash
4323 $utf8::ToLower, which is stored in lib/unicore/To/Lower.pl,
4324 and loaded by SWASHGET, using lib/utf8_heavy.pl.
4326 The "special" is a string like "utf8::ToSpecLower", which means
4327 the hash %utf8::ToSpecLower, which is stored in the same file,
4328 lib/unicore/To/Lower.pl, and also loaded by SWASHGET. The access
4329 to the hash is by Perl_to_utf8_case().
4331 UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
4334 Found in file utf8.c
4336 =item utf8n_to_uvchr
4338 Returns the native character value of the first character in the string C<s>
4339 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4340 length, in bytes, of that character.
4342 Allows length and flags to be passed to low level routine.
4344 UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4347 Found in file utf8.c
4349 =item utf8n_to_uvuni
4351 Bottom level UTF-8 decode routine.
4352 Returns the unicode code point value of the first character in the string C<s>
4353 which is assumed to be in UTF8 encoding and no longer than C<curlen>;
4354 C<retlen> will be set to the length, in bytes, of that character.
4356 If C<s> does not point to a well-formed UTF8 character, the behaviour
4357 is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
4358 it is assumed that the caller will raise a warning, and this function
4359 will silently just set C<retlen> to C<-1> and return zero. If the
4360 C<flags> does not contain UTF8_CHECK_ONLY, warnings about
4361 malformations will be given, C<retlen> will be set to the expected
4362 length of the UTF-8 character in bytes, and zero will be returned.
4364 The C<flags> can also contain various flags to allow deviations from
4365 the strict UTF-8 encoding (see F<utf8.h>).
4367 Most code should use utf8_to_uvchr() rather than call this directly.
4369 UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN* retlen, U32 flags)
4372 Found in file utf8.c
4376 Returns the number of UTF8 characters between the UTF-8 pointers C<a>
4379 WARNING: use only if you *know* that the pointers point inside the
4382 IV utf8_distance(U8 *a, U8 *b)
4385 Found in file utf8.c
4389 Return the UTF-8 pointer C<s> displaced by C<off> characters, either
4390 forward or backward.
4392 WARNING: do not use the following unless you *know* C<off> is within
4393 the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
4394 on the first byte of character or just after the last byte of a character.
4396 U8* utf8_hop(U8 *s, I32 off)
4399 Found in file utf8.c
4403 Return the length of the UTF-8 char encoded string C<s> in characters.
4404 Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
4405 up past C<e>, croaks.
4407 STRLEN utf8_length(U8* s, U8 *e)
4410 Found in file utf8.c
4414 Converts a string C<s> of length C<len> from UTF8 into byte encoding.
4415 Unlike C<bytes_to_utf8>, this over-writes the original string, and
4416 updates len to contain the new length.
4417 Returns zero on failure, setting C<len> to -1.
4419 NOTE: this function is experimental and may change or be
4420 removed without notice.
4422 U8* utf8_to_bytes(U8 *s, STRLEN *len)
4425 Found in file utf8.c
4429 Returns the native character value of the first character in the string C<s>
4430 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4431 length, in bytes, of that character.
4433 If C<s> does not point to a well-formed UTF8 character, zero is
4434 returned and retlen is set, if possible, to -1.
4436 UV utf8_to_uvchr(U8 *s, STRLEN* retlen)
4439 Found in file utf8.c
4443 Returns the Unicode code point of the first character in the string C<s>
4444 which is assumed to be in UTF8 encoding; C<retlen> will be set to the
4445 length, in bytes, of that character.
4447 This function should only be used when returned UV is considered
4448 an index into the Unicode semantic tables (e.g. swashes).
4450 If C<s> does not point to a well-formed UTF8 character, zero is
4451 returned and retlen is set, if possible, to -1.
4453 UV utf8_to_uvuni(U8 *s, STRLEN* retlen)
4456 Found in file utf8.c
4460 Adds the UTF8 representation of the Native codepoint C<uv> to the end
4461 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4462 bytes available. The return value is the pointer to the byte after the
4463 end of the new character. In other words,
4465 d = uvchr_to_utf8(d, uv);
4467 is the recommended wide native character-aware way of saying
4471 U8* uvchr_to_utf8(U8 *d, UV uv)
4474 Found in file utf8.c
4476 =item uvuni_to_utf8_flags
4478 Adds the UTF8 representation of the Unicode codepoint C<uv> to the end
4479 of the string C<d>; C<d> should be have at least C<UTF8_MAXLEN+1> free
4480 bytes available. The return value is the pointer to the byte after the
4481 end of the new character. In other words,
4483 d = uvuni_to_utf8_flags(d, uv, flags);
4487 d = uvuni_to_utf8(d, uv);
4489 (which is equivalent to)
4491 d = uvuni_to_utf8_flags(d, uv, 0);
4493 is the recommended Unicode-aware way of saying
4497 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
4500 Found in file utf8.c
4504 This is the XSUB-writer's interface to Perl's C<warn> function. Use this
4505 function the same way you use the C C<printf> function. See
4508 void warn(const char* pat, ...)
4511 Found in file util.c
4515 Push an integer onto the stack, extending the stack if necessary. Handles
4516 'set' magic. See C<PUSHi>.
4525 Push a double onto the stack, extending the stack if necessary. Handles
4526 'set' magic. See C<PUSHn>.
4535 Push a string onto the stack, extending the stack if necessary. The C<len>
4536 indicates the length of the string. Handles 'set' magic. See
4539 void XPUSHp(char* str, STRLEN len)
4546 Push an SV onto the stack, extending the stack if necessary. Does not
4547 handle 'set' magic. See C<PUSHs>.
4556 Push an unsigned integer onto the stack, extending the stack if necessary.
4566 Macro to declare an XSUB and its C parameter list. This is handled by
4570 Found in file XSUB.h
4574 Return from XSUB, indicating number of items on the stack. This is usually
4575 handled by C<xsubpp>.
4577 void XSRETURN(int nitems)
4580 Found in file XSUB.h
4582 =item XSRETURN_EMPTY
4584 Return an empty list from an XSUB immediately.
4589 Found in file XSUB.h
4593 Return an integer from an XSUB immediately. Uses C<XST_mIV>.
4595 void XSRETURN_IV(IV iv)
4598 Found in file XSUB.h
4602 Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
4607 Found in file XSUB.h
4611 Return a double from an XSUB immediately. Uses C<XST_mNV>.
4613 void XSRETURN_NV(NV nv)
4616 Found in file XSUB.h
4620 Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
4622 void XSRETURN_PV(char* str)
4625 Found in file XSUB.h
4627 =item XSRETURN_UNDEF
4629 Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
4634 Found in file XSUB.h
4638 Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
4643 Found in file XSUB.h
4647 Place an integer into the specified position C<pos> on the stack. The
4648 value is stored in a new mortal SV.
4650 void XST_mIV(int pos, IV iv)
4653 Found in file XSUB.h
4657 Place C<&PL_sv_no> into the specified position C<pos> on the
4660 void XST_mNO(int pos)
4663 Found in file XSUB.h
4667 Place a double into the specified position C<pos> on the stack. The value
4668 is stored in a new mortal SV.
4670 void XST_mNV(int pos, NV nv)
4673 Found in file XSUB.h
4677 Place a copy of a string into the specified position C<pos> on the stack.
4678 The value is stored in a new mortal SV.
4680 void XST_mPV(int pos, char* str)
4683 Found in file XSUB.h
4687 Place C<&PL_sv_undef> into the specified position C<pos> on the
4690 void XST_mUNDEF(int pos)
4693 Found in file XSUB.h
4697 Place C<&PL_sv_yes> into the specified position C<pos> on the
4700 void XST_mYES(int pos)
4703 Found in file XSUB.h
4707 The version identifier for an XS module. This is usually
4708 handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
4711 Found in file XSUB.h
4713 =item XS_VERSION_BOOTCHECK
4715 Macro to verify that a PM module's $VERSION variable matches the XS
4716 module's C<XS_VERSION> variable. This is usually handled automatically by
4717 C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
4719 XS_VERSION_BOOTCHECK;
4722 Found in file XSUB.h
4726 The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
4727 destination, C<nitems> is the number of items, and C<type> is the type.
4729 void Zero(void* dest, int nitems, type)
4732 Found in file handy.h
4738 Until May 1997, this document was maintained by Jeff Okamoto
4739 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
4741 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
4742 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
4743 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
4744 Stephen McCamant, and Gurusamy Sarathy.
4746 API Listing originally by Dean Roehrich <roehrich@cray.com>.
4748 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
4752 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
projects / p5sagit/p5-mst-13.2.git / blob