1PERLAPI(1) Perl Programmers Reference Guide PERLAPI(1)
2
6 perlapi - autogenerated documentation for the perl public API
7
9 This file contains the documentation of the perl public API generated
10 by embed.pl, specifically a listing of functions, macros, flags, and
11 variables that may be used by extension writers. The interfaces of any
12 functions that are not listed here are subject to change without
13 notice. For this reason, blindly using functions listed in proto.h is
14 to be avoided when writing extensions.
15 Note that all Perl API global variables must be referenced with the
17 "PL_" prefix. Some macros are provided for compatibility with the
18 older, unadorned names, but this support may be disabled in a future
19 release.
20 The listing is alphabetical, case insensitive.
22
24 GIMME A backward-compatible version of "GIMME_V" which can only
25 return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
26 "G_SCALAR". Deprecated. Use "GIMME_V" instead.
27 U32 GIMME
29 GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns
31 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list con‐
32 text, respectively.
33 U32 GIMME_V
35 G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and
37 perlcall.
38 G_DISCARD
40 Indicates that arguments returned from a callback should be
41 discarded. See perlcall.
42 G_EVAL Used to force a Perl "eval" wrapper around a callback. See
44 perlcall.
45 G_NOARGS
47 Indicates that no arguments are being sent to a callback. See
48 perlcall.
49 G_SCALAR
51 Used to indicate scalar context. See "GIMME_V", "GIMME", and
52 perlcall.
53 G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
55
57 AvFILL Same as "av_len()". Deprecated, use "av_len()" instead.
58 int AvFILL(AV* av)
60 av_clear
62 Clears an array, making it empty. Does not free the memory
63 used by the array itself.
64 void av_clear(AV* ar)
66 av_delete
68 Deletes the element indexed by "key" from the array. Returns
69 the deleted element. If "flags" equals "G_DISCARD", the element
70 is freed and null is returned.
71 SV* av_delete(AV* ar, I32 key, I32 flags)
73 av_exists
75 Returns true if the element indexed by "key" has been initial‐
76 ized.
77 This relies on the fact that uninitialized array elements are
79 set to &PL_sv_undef.
80 bool av_exists(AV* ar, I32 key)
82 av_extend
84 Pre-extend an array. The "key" is the index to which the array
85 should be extended.
86 void av_extend(AV* ar, I32 key)
88 av_fetch
90 Returns the SV at the specified index in the array. The "key"
91 is the index. If "lval" is set then the fetch will be part of
92 a store. Check that the return value is non-null before deref‐
93 erencing it to a "SV*".
94 See "Understanding the Magic of Tied Hashes and Arrays" in
96 perlguts for more information on how to use this function on
97 tied arrays.
98 SV** av_fetch(AV* ar, I32 key, I32 lval)
100 av_fill Ensure than an array has a given number of elements, equivalent
102 to Perl's "$#array = $fill;".
103 void av_fill(AV* ar, I32 fill)
105 av_len Returns the highest index in the array. Returns -1 if the
107 array is empty.
108 I32 av_len(AV* ar)
110 av_make Creates a new AV and populates it with a list of SVs. The SVs
112 are copied into the array, so they may be freed after the call
113 to av_make. The new AV will have a reference count of 1.
114 AV* av_make(I32 size, SV** svp)
116 av_pop Pops an SV off the end of the array. Returns &PL_sv_undef if
118 the array is empty.
119 SV* av_pop(AV* ar)
121 av_push Pushes an SV onto the end of the array. The array will grow
123 automatically to accommodate the addition.
124 void av_push(AV* ar, SV* val)
126 av_shift
128 Shifts an SV off the beginning of the array.
129 SV* av_shift(AV* ar)
131 av_store
133 Stores an SV in an array. The array index is specified as
134 "key". The return value will be NULL if the operation failed
135 or if the value did not need to be actually stored within the
136 array (as in the case of tied arrays). Otherwise it can be
137 dereferenced to get the original "SV*". Note that the caller
138 is responsible for suitably incrementing the reference count of
139 "val" before the call, and decrementing it if the function
140 returned NULL.
141 See "Understanding the Magic of Tied Hashes and Arrays" in
143 perlguts for more information on how to use this function on
144 tied arrays.
145 SV** av_store(AV* ar, I32 key, SV* val)
147 av_undef
149 Undefines the array. Frees the memory used by the array
150 itself.
151 void av_undef(AV* ar)
153 av_unshift
155 Unshift the given number of "undef" values onto the beginning
156 of the array. The array will grow automatically to accommodate
157 the addition. You must then use "av_store" to assign values to
158 these new elements.
159 void av_unshift(AV* ar, I32 num)
161 get_av Returns the AV of the specified Perl array. If "create" is set
163 and the Perl variable does not exist then it will be created.
164 If "create" is not set and the variable does not exist then
165 NULL is returned.
166 NOTE: the perl_ form of this function is deprecated.
168 AV* get_av(const char* name, I32 create)
170 newAV Creates a new AV. The reference count is set to 1.
172 AV* newAV()
174 sortsv Sort an array. Here is an example:
176 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
178 See lib/sort.pm for details about controlling the sorting algo‐
180 rithm.
181 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
183
185 call_argv
186 Performs a callback to the specified Perl sub. See perlcall.
187 NOTE: the perl_ form of this function is deprecated.
189 I32 call_argv(const char* sub_name, I32 flags, char** argv)
191 call_method
193 Performs a callback to the specified Perl method. The blessed
194 object must be on the stack. See perlcall.
195 NOTE: the perl_ form of this function is deprecated.
197 I32 call_method(const char* methname, I32 flags)
199 call_pv Performs a callback to the specified Perl sub. See perlcall.
201 NOTE: the perl_ form of this function is deprecated.
203 I32 call_pv(const char* sub_name, I32 flags)
205 call_sv Performs a callback to the Perl sub whose name is in the SV.
207 See perlcall.
208 NOTE: the perl_ form of this function is deprecated.
210 I32 call_sv(SV* sv, I32 flags)
212 ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
214 ENTER;
216 eval_pv Tells Perl to "eval" the given string and return an SV* result.
218 NOTE: the perl_ form of this function is deprecated.
220 SV* eval_pv(const char* p, I32 croak_on_error)
222 eval_sv Tells Perl to "eval" the string in the SV.
224 NOTE: the perl_ form of this function is deprecated.
226 I32 eval_sv(SV* sv, I32 flags)
228 FREETMPS
230 Closing bracket for temporaries on a callback. See "SAVETMPS"
231 and perlcall.
232 FREETMPS;
234 LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
236 LEAVE;
238 SAVETMPS
240 Opening bracket for temporaries on a callback. See "FREETMPS"
241 and perlcall.
242 SAVETMPS;
244
246 isALNUM Returns a boolean indicating whether the C "char" is an ASCII
247 alphanumeric character (including underscore) or digit.
248 bool isALNUM(char ch)
250 isALPHA Returns a boolean indicating whether the C "char" is an ASCII
252 alphabetic character.
253 bool isALPHA(char ch)
255 isDIGIT Returns a boolean indicating whether the C "char" is an ASCII
257 digit.
258 bool isDIGIT(char ch)
260 isLOWER Returns a boolean indicating whether the C "char" is a lower‐
262 case character.
263 bool isLOWER(char ch)
265 isSPACE Returns a boolean indicating whether the C "char" is white‐
267 space.
268 bool isSPACE(char ch)
270 isUPPER Returns a boolean indicating whether the C "char" is an upper‐
272 case character.
273 bool isUPPER(char ch)
275 toLOWER Converts the specified character to lowercase.
277 char toLOWER(char ch)
279 toUPPER Converts the specified character to uppercase.
281 char toUPPER(char ch)
283
285 perl_clone
286 Create and return a new interpreter by cloning the current one.
287 perl_clone takes these flags as parameters:
289 CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
291 without it we only clone the data and zero the stacks, with it
292 we copy the stacks and the new perl interpreter is ready to run
293 at the exact same point as the previous one. The pseudo-fork
294 code uses COPY_STACKS while the threads->new doesn't.
295 CLONEf_KEEP_PTR_TABLE perl_clone keeps a ptr_table with the
297 pointer of the old variable as a key and the new variable as a
298 value, this allows it to check if something has been cloned and
299 not clone it again but rather just use the value and increase
300 the refcount. If KEEP_PTR_TABLE is not set then perl_clone will
301 kill the ptr_table using the function "ptr_ta‐
302 ble_free(PL_ptr_table); PL_ptr_table = NULL;", reason to keep
303 it around is if you want to dup some of your own variable who
304 are outside the graph perl scans, example of this code is in
305 threads.xs create
306 CLONEf_CLONE_HOST This is a win32 thing, it is ignored on unix,
308 it tells perls win32host code (which is c++) to clone itself,
309 this is needed on win32 if you want to run two threads at the
310 same time, if you just want to do some stuff in a separate perl
311 interpreter and then throw it away and return to the original
312 one, you don't need to do anything.
313 PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
315
317 CvSTASH Returns the stash of the CV.
318 HV* CvSTASH(CV* cv)
320 get_cv Returns the CV of the specified Perl subroutine. If "create"
322 is set and the Perl subroutine does not exist then it will be
323 declared (which has the same effect as saying "sub name;"). If
324 "create" is not set and the subroutine does not exist then NULL
325 is returned.
326 NOTE: the perl_ form of this function is deprecated.
328 CV* get_cv(const char* name, I32 create)
330
332 cv_undef
333 Clear out all the active components of a CV. This can happen
334 either by an explicit "undef &foo", or by the reference count
335 going to zero. In the former case, we keep the CvOUTSIDE
336 pointer, so that any anonymous children can still follow the
337 full lexical scope chain.
338 void cv_undef(CV* cv)
340 load_module
342 Loads the module whose name is pointed to by the string part of
343 name. Note that the actual module name, not its filename,
344 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm".
345 flags can be any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT,
346 or PERL_LOADMOD_IMPORT_OPS (or 0 for no flags). ver, if speci‐
347 fied, provides version semantics similar to "use Foo::Bar VER‐
348 SION". The optional trailing SV* arguments can be used to
349 specify arguments to the module's import() method, similar to
350 "use Foo::Bar VERSION LIST".
351 void load_module(U32 flags, SV* name, SV* ver, ...)
353 nothreadhook
355 Stub that provides thread hook for perl_destruct when there are
356 no threads.
357 int nothreadhook()
359 perl_alloc
361 Allocates a new Perl interpreter. See perlembed.
362 PerlInterpreter* perl_alloc()
364 perl_construct
366 Initializes a new Perl interpreter. See perlembed.
367 void perl_construct(PerlInterpreter* interp)
369 perl_destruct
371 Shuts down a Perl interpreter. See perlembed.
372 int perl_destruct(PerlInterpreter* interp)
374 perl_free
376 Releases a Perl interpreter. See perlembed.
377 void perl_free(PerlInterpreter* interp)
379 perl_parse
381 Tells a Perl interpreter to parse a Perl script. See perlem‐
382 bed.
383 int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
385 perl_run
387 Tells a Perl interpreter to run. See perlembed.
388 int perl_run(PerlInterpreter* interp)
390 require_pv
392 Tells Perl to "require" the file named by the string argument.
393 It is analogous to the Perl code "eval "require '$file'"".
394 It's even implemented that way; consider using load_module
395 instead.
396 NOTE: the perl_ form of this function is deprecated.
398 void require_pv(const char* pv)
400
402 packlist
403 The engine implementing pack() Perl function.
404 void packlist(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist)
406 pack_cat
408 The engine implementing pack() Perl function. Note: parameters
409 next_in_list and flags are not used. This call should not be
410 used; use packlist instead.
411 void pack_cat(SV *cat, char *pat, char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
413 unpackstring
415 The engine implementing unpack() Perl function. "unpackstring"
416 puts the extracted list items on the stack and returns the num‐
417 ber of elements. Issue "PUTBACK" before and "SPAGAIN" after
418 the call to this function.
419 I32 unpackstring(char *pat, char *patend, char *s, char *strend, U32 flags)
421 unpack_str
423 The engine implementing unpack() Perl function. Note: parame‐
424 ters strbeg, new_s and ocnt are not used. This call should not
425 be used, use unpackstring instead.
426 I32 unpack_str(char *pat, char *patend, char *s, char *strbeg, char *strend, char **new_s, I32 ocnt, U32 flags)
428
430 PL_modglobal
431 "PL_modglobal" is a general purpose, interpreter global HV for
432 use by extensions that need to keep information on a per-inter‐
433 preter basis. In a pinch, it can also be used as a symbol ta‐
434 ble for extensions to share data among each other. It is a
435 good idea to use keys prefixed by the package name of the
436 extension that owns the data.
437 HV* PL_modglobal
439 PL_na A convenience variable which is typically used with "SvPV" when
441 one doesn't care about the length of the string. It is usually
442 more efficient to either declare a local variable and use that
443 instead or to use the "SvPV_nolen" macro.
444 STRLEN PL_na
446 PL_sv_no
448 This is the "false" SV. See "PL_sv_yes". Always refer to this
449 as &PL_sv_no.
450 SV PL_sv_no
452 PL_sv_undef
454 This is the "undef" SV. Always refer to this as &PL_sv_undef.
455 SV PL_sv_undef
457 PL_sv_yes
459 This is the "true" SV. See "PL_sv_no". Always refer to this
460 as &PL_sv_yes.
461 SV PL_sv_yes
463
465 GvSV Return the SV from the GV.
466 SV* GvSV(GV* gv)
468 gv_fetchmeth
470 Returns the glob with the given "name" and a defined subroutine
471 or "NULL". The glob lives in the given "stash", or in the
472 stashes accessible via @ISA and UNIVERSAL::.
473 The argument "level" should be either 0 or -1. If "level==0",
475 as a side-effect creates a glob with the given "name" in the
476 given "stash" which in the case of success contains an alias
477 for the subroutine, and sets up caching info for this glob.
478 Similarly for all the searched stashes.
479 This function grants "SUPER" token as a postfix of the stash
481 name. The GV returned from "gv_fetchmeth" may be a method cache
482 entry, which is not visible to Perl code. So when calling
483 "call_sv", you should not use the GV directly; instead, you
484 should use the method's CV, which can be obtained from the GV
485 with the "GvCV" macro.
486 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
488 gv_fetchmethod
490 See gv_fetchmethod_autoload.
491 GV* gv_fetchmethod(HV* stash, const char* name)
493 gv_fetchmethod_autoload
495 Returns the glob which contains the subroutine to call to
496 invoke the method on the "stash". In fact in the presence of
497 autoloading this may be the glob for "AUTOLOAD". In this case
498 the corresponding variable $AUTOLOAD is already setup.
499 The third parameter of "gv_fetchmethod_autoload" determines
501 whether AUTOLOAD lookup is performed if the given method is not
502 present: non-zero means yes, look for AUTOLOAD; zero means no,
503 don't look for AUTOLOAD. Calling "gv_fetchmethod" is equiva‐
504 lent to calling "gv_fetchmethod_autoload" with a non-zero
505 "autoload" parameter.
506 These functions grant "SUPER" token as a prefix of the method
508 name. Note that if you want to keep the returned glob for a
509 long time, you need to check for it being "AUTOLOAD", since at
510 the later time the call may load a different subroutine due to
511 $AUTOLOAD changing its value. Use the glob created via a side
512 effect to do this.
513 These functions have the same side-effects and as "gv_fetch‐
515 meth" with "level==0". "name" should be writable if contains
516 ':' or "' ''". The warning against passing the GV returned by
517 "gv_fetchmeth" to "call_sv" apply equally to these functions.
518 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
520 gv_fetchmeth_autoload
522 Same as gv_fetchmeth(), but looks for autoloaded subroutines
523 too. Returns a glob for the subroutine.
524 For an autoloaded subroutine without a GV, will create a GV
526 even if "level < 0". For an autoloaded subroutine without a
527 stub, GvCV() of the result may be zero.
528 GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
530 gv_stashpv
532 Returns a pointer to the stash for a specified package. "name"
533 should be a valid UTF-8 string and must be null-terminated. If
534 "create" is set then the package will be created if it does not
535 already exist. If "create" is not set and the package does not
536 exist then NULL is returned.
537 HV* gv_stashpv(const char* name, I32 create)
539 gv_stashpvn
541 Returns a pointer to the stash for a specified package. "name"
542 should be a valid UTF-8 string. The "namelen" parameter indi‐
543 cates the length of the "name", in bytes. If "create" is set
544 then the package will be created if it does not already exist.
545 If "create" is not set and the package does not exist then NULL
546 is returned.
547 HV* gv_stashpvn(const char* name, U32 namelen, I32 create)
549 gv_stashsv
551 Returns a pointer to the stash for a specified package, which
552 must be a valid UTF-8 string. See "gv_stashpv".
553 HV* gv_stashsv(SV* sv, I32 create)
555
557 Nullav Null AV pointer.
558 Nullch Null character pointer.
560 Nullcv Null CV pointer.
562 Nullhv Null HV pointer.
564 Nullsv Null SV pointer.
566
568 get_hv Returns the HV of the specified Perl hash. If "create" is set
569 and the Perl variable does not exist then it will be created.
570 If "create" is not set and the variable does not exist then
571 NULL is returned.
572 NOTE: the perl_ form of this function is deprecated.
574 HV* get_hv(const char* name, I32 create)
576 HEf_SVKEY
578 This flag, used in the length slot of hash entries and magic
579 structures, specifies the structure contains an "SV*" pointer
580 where a "char*" pointer is to be expected. (For information
581 only--not to be used).
582 HeHASH Returns the computed hash stored in the hash entry.
584 U32 HeHASH(HE* he)
586 HeKEY Returns the actual pointer stored in the key slot of the hash
588 entry. The pointer may be either "char*" or "SV*", depending on
589 the value of "HeKLEN()". Can be assigned to. The "HePV()" or
590 "HeSVKEY()" macros are usually preferable for finding the value
591 of a key.
592 void* HeKEY(HE* he)
594 HeKLEN If this is negative, and amounts to "HEf_SVKEY", it indicates
596 the entry holds an "SV*" key. Otherwise, holds the actual
597 length of the key. Can be assigned to. The "HePV()" macro is
598 usually preferable for finding key lengths.
599 STRLEN HeKLEN(HE* he)
601 HePV Returns the key slot of the hash entry as a "char*" value,
603 doing any necessary dereferencing of possibly "SV*" keys. The
604 length of the string is placed in "len" (this is a macro, so do
605 not use &len). If you do not care about what the length of the
606 key is, you may use the global variable "PL_na", though this is
607 rather less efficient than using a local variable. Remember
608 though, that hash keys in perl are free to contain embedded
609 nulls, so using "strlen()" or similar is not a good way to find
610 the length of hash keys. This is very similar to the "SvPV()"
611 macro described elsewhere in this document.
612 char* HePV(HE* he, STRLEN len)
614 HeSVKEY Returns the key as an "SV*", or "Nullsv" if the hash entry does
616 not contain an "SV*" key.
617 SV* HeSVKEY(HE* he)
619 HeSVKEY_force
621 Returns the key as an "SV*". Will create and return a tempo‐
622 rary mortal "SV*" if the hash entry contains only a "char*"
623 key.
624 SV* HeSVKEY_force(HE* he)
626 HeSVKEY_set
628 Sets the key to a given "SV*", taking care to set the appropri‐
629 ate flags to indicate the presence of an "SV*" key, and returns
630 the same "SV*".
631 SV* HeSVKEY_set(HE* he, SV* sv)
633 HeVAL Returns the value slot (type "SV*") stored in the hash entry.
635 SV* HeVAL(HE* he)
637 HvNAME Returns the package name of a stash. See "SvSTASH", "CvSTASH".
639 char* HvNAME(HV* stash)
641 hv_clear
643 Clears a hash, making it empty.
644 void hv_clear(HV* tb)
646 hv_clear_placeholders
648 Clears any placeholders from a hash. If a restricted hash has
649 any of its keys marked as readonly and the key is subsequently
650 deleted, the key is not actually deleted but is marked by
651 assigning it a value of &PL_sv_placeholder. This tags it so it
652 will be ignored by future operations such as iterating over the
653 hash, but will still allow the hash to have a value reassigned
654 to the key at some future point. This function clears any such
655 placeholder keys from the hash. See Hash::Util::lock_keys()
656 for an example of its use.
657 void hv_clear_placeholders(HV* hb)
659 hv_delete
661 Deletes a key/value pair in the hash. The value SV is removed
662 from the hash and returned to the caller. The "klen" is the
663 length of the key. The "flags" value will normally be zero; if
664 set to G_DISCARD then NULL will be returned.
665 SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
667 hv_delete_ent
669 Deletes a key/value pair in the hash. The value SV is removed
670 from the hash and returned to the caller. The "flags" value
671 will normally be zero; if set to G_DISCARD then NULL will be
672 returned. "hash" can be a valid precomputed hash value, or 0
673 to ask for it to be computed.
674 SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
676 hv_exists
678 Returns a boolean indicating whether the specified hash key
679 exists. The "klen" is the length of the key.
680 bool hv_exists(HV* tb, const char* key, I32 klen)
682 hv_exists_ent
684 Returns a boolean indicating whether the specified hash key
685 exists. "hash" can be a valid precomputed hash value, or 0 to
686 ask for it to be computed.
687 bool hv_exists_ent(HV* tb, SV* key, U32 hash)
689 hv_fetch
691 Returns the SV which corresponds to the specified key in the
692 hash. The "klen" is the length of the key. If "lval" is set
693 then the fetch will be part of a store. Check that the return
694 value is non-null before dereferencing it to an "SV*".
695 See "Understanding the Magic of Tied Hashes and Arrays" in
697 perlguts for more information on how to use this function on
698 tied hashes.
699 SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
701 hv_fetch_ent
703 Returns the hash entry which corresponds to the specified key
704 in the hash. "hash" must be a valid precomputed hash number
705 for the given "key", or 0 if you want the function to compute
706 it. IF "lval" is set then the fetch will be part of a store.
707 Make sure the return value is non-null before accessing it.
708 The return value when "tb" is a tied hash is a pointer to a
709 static location, so be sure to make a copy of the structure if
710 you need to store it somewhere.
711 See "Understanding the Magic of Tied Hashes and Arrays" in
713 perlguts for more information on how to use this function on
714 tied hashes.
715 HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
717 hv_iterinit
719 Prepares a starting point to traverse a hash table. Returns
720 the number of keys in the hash (i.e. the same as "HvKEYS(tb)").
721 The return value is currently only meaningful for hashes with‐
722 out tie magic.
723 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
725 number of hash buckets that happen to be in use. If you still
726 need that esoteric value, you can get it through the macro
727 "HvFILL(tb)".
728 I32 hv_iterinit(HV* tb)
730 hv_iterkey
732 Returns the key from the current position of the hash iterator.
733 See "hv_iterinit".
734 char* hv_iterkey(HE* entry, I32* retlen)
736 hv_iterkeysv
738 Returns the key as an "SV*" from the current position of the
739 hash iterator. The return value will always be a mortal copy
740 of the key. Also see "hv_iterinit".
741 SV* hv_iterkeysv(HE* entry)
743 hv_iternext
745 Returns entries from a hash iterator. See "hv_iterinit".
746 You may call "hv_delete" or "hv_delete_ent" on the hash entry
748 that the iterator currently points to, without losing your
749 place or invalidating your iterator. Note that in this case
750 the current entry is deleted from the hash with your iterator
751 holding the last reference to it. Your iterator is flagged to
752 free the entry on the next call to "hv_iternext", so you must
753 not discard your iterator immediately else the entry will leak
754 - call "hv_iternext" to trigger the resource deallocation.
755 HE* hv_iternext(HV* tb)
757 hv_iternextsv
759 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
760 one operation.
761 SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
763 hv_iternext_flags
765 Returns entries from a hash iterator. See "hv_iterinit" and
766 "hv_iternext". The "flags" value will normally be zero; if
767 HV_ITERNEXT_WANTPLACEHOLDERS is set the placeholders keys (for
768 restricted hashes) will be returned in addition to normal keys.
769 By default placeholders are automatically skipped over. Cur‐
770 rently a placeholder is implemented with a value that is
771 &Perl_sv_placeholder. Note that the implementation of place‐
772 holders and restricted hashes may change, and the implementa‐
773 tion currently is insufficiently abstracted for any change to
774 be tidy.
775 NOTE: this function is experimental and may change or be
777 removed without notice.
778 HE* hv_iternext_flags(HV* tb, I32 flags)
780 hv_iterval
782 Returns the value from the current position of the hash itera‐
783 tor. See "hv_iterkey".
784 SV* hv_iterval(HV* tb, HE* entry)
786 hv_magic
788 Adds magic to a hash. See "sv_magic".
789 void hv_magic(HV* hv, GV* gv, int how)
791 hv_scalar
793 Evaluates the hash in scalar context and returns the result.
794 Handles magic when the hash is tied.
795 SV* hv_scalar(HV* hv)
797 hv_store
799 Stores an SV in a hash. The hash key is specified as "key" and
800 "klen" is the length of the key. The "hash" parameter is the
801 precomputed hash value; if it is zero then Perl will compute
802 it. The return value will be NULL if the operation failed or
803 if the value did not need to be actually stored within the hash
804 (as in the case of tied hashes). Otherwise it can be derefer‐
805 enced to get the original "SV*". Note that the caller is
806 responsible for suitably incrementing the reference count of
807 "val" before the call, and decrementing it if the function
808 returned NULL. Effectively a successful hv_store takes owner‐
809 ship of one reference to "val". This is usually what you want;
810 a newly created SV has a reference count of one, so if all your
811 code does is create SVs then store them in a hash, hv_store
812 will own the only reference to the new SV, and your code
813 doesn't need to do anything further to tidy up. hv_store is
814 not implemented as a call to hv_store_ent, and does not create
815 a temporary SV for the key, so if your key data is not already
816 in SV form then use hv_store in preference to hv_store_ent.
817 See "Understanding the Magic of Tied Hashes and Arrays" in
819 perlguts for more information on how to use this function on
820 tied hashes.
821 SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
823 hv_store_ent
825 Stores "val" in a hash. The hash key is specified as "key".
826 The "hash" parameter is the precomputed hash value; if it is
827 zero then Perl will compute it. The return value is the new
828 hash entry so created. It will be NULL if the operation failed
829 or if the value did not need to be actually stored within the
830 hash (as in the case of tied hashes). Otherwise the contents
831 of the return value can be accessed using the "He?" macros
832 described here. Note that the caller is responsible for suit‐
833 ably incrementing the reference count of "val" before the call,
834 and decrementing it if the function returned NULL. Effectively
835 a successful hv_store_ent takes ownership of one reference to
836 "val". This is usually what you want; a newly created SV has a
837 reference count of one, so if all your code does is create SVs
838 then store them in a hash, hv_store will own the only reference
839 to the new SV, and your code doesn't need to do anything fur‐
840 ther to tidy up. Note that hv_store_ent only reads the "key";
841 unlike "val" it does not take ownership of it, so maintaining
842 the correct reference count on "key" is entirely the caller's
843 responsibility. hv_store is not implemented as a call to
844 hv_store_ent, and does not create a temporary SV for the key,
845 so if your key data is not already in SV form then use hv_store
846 in preference to hv_store_ent.
847 See "Understanding the Magic of Tied Hashes and Arrays" in
849 perlguts for more information on how to use this function on
850 tied hashes.
851 HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
853 hv_undef
855 Undefines the hash.
856 void hv_undef(HV* tb)
858 newHV Creates a new HV. The reference count is set to 1.
860 HV* newHV()
862
864 mg_clear
865 Clear something magical that the SV represents. See
866 "sv_magic".
867 int mg_clear(SV* sv)
869 mg_copy Copies the magic from one SV to another. See "sv_magic".
871 int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
873 mg_find Finds the magic pointer for type matching the SV. See
875 "sv_magic".
876 MAGIC* mg_find(SV* sv, int type)
878 mg_free Free any magic storage used by the SV. See "sv_magic".
880 int mg_free(SV* sv)
882 mg_get Do magic after a value is retrieved from the SV. See
884 "sv_magic".
885 int mg_get(SV* sv)
887 mg_length
889 Report on the SV's length. See "sv_magic".
890 U32 mg_length(SV* sv)
892 mg_magical
894 Turns on the magical status of an SV. See "sv_magic".
895 void mg_magical(SV* sv)
897 mg_set Do magic after a value is assigned to the SV. See "sv_magic".
899 int mg_set(SV* sv)
901 SvGETMAGIC
903 Invokes "mg_get" on an SV if it has 'get' magic. This macro
904 evaluates its argument more than once.
905 void SvGETMAGIC(SV* sv)
907 SvLOCK Arranges for a mutual exclusion lock to be obtained on sv if a
909 suitable module has been loaded.
910 void SvLOCK(SV* sv)
912 SvSETMAGIC
914 Invokes "mg_set" on an SV if it has 'set' magic. This macro
915 evaluates its argument more than once.
916 void SvSETMAGIC(SV* sv)
918 SvSetMagicSV
920 Like "SvSetSV", but does any set magic required afterwards.
921 void SvSetMagicSV(SV* dsb, SV* ssv)
923 SvSetMagicSV_nosteal
925 Like "SvSetSV_nosteal", but does any set magic required after‐
926 wards.
927 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
929 SvSetSV Calls "sv_setsv" if dsv is not the same as ssv. May evaluate
931 arguments more than once.
932 void SvSetSV(SV* dsb, SV* ssv)
934 SvSetSV_nosteal
936 Calls a non-destructive version of "sv_setsv" if dsv is not the
937 same as ssv. May evaluate arguments more than once.
938 void SvSetSV_nosteal(SV* dsv, SV* ssv)
940 SvSHARE Arranges for sv to be shared between threads if a suitable mod‐
942 ule has been loaded.
943 void SvSHARE(SV* sv)
945 SvUNLOCK
947 Releases a mutual exclusion lock on sv if a suitable module has
948 been loaded.
949 void SvUNLOCK(SV* sv)
951
953 Copy The XSUB-writer's interface to the C "memcpy" function. The
954 "src" is the source, "dest" is the destination, "nitems" is the
955 number of items, and "type" is the type. May fail on overlap‐
956 ping copies. See also "Move".
957 void Copy(void* src, void* dest, int nitems, type)
959 CopyD Like "Copy" but returns dest. Useful for encouraging compilers
961 to tail-call optimise.
962 void * CopyD(void* src, void* dest, int nitems, type)
964 Move The XSUB-writer's interface to the C "memmove" function. The
966 "src" is the source, "dest" is the destination, "nitems" is the
967 number of items, and "type" is the type. Can do overlapping
968 moves. See also "Copy".
969 void Move(void* src, void* dest, int nitems, type)
971 MoveD Like "Move" but returns dest. Useful for encouraging compilers
973 to tail-call optimise.
974 void * MoveD(void* src, void* dest, int nitems, type)
976 Newx The XSUB-writer's interface to the C "malloc" function.
978 void Newx(void* ptr, int nitems, type)
980 Newxc The XSUB-writer's interface to the C "malloc" function, with
982 cast.
983 void Newxc(void* ptr, int nitems, type, cast)
985 Newxz The XSUB-writer's interface to the C "malloc" function. The
987 allocated memory is zeroed with "memzero".
988 In 5.9.3, we removed the 1st parameter, a debug aid, from the
990 api. It was used to uniquely identify each usage of these
991 allocation functions, but was deemed unnecessary with the
992 availability of better memory tracking tools, valgrind for
993 example.
994 void Newxz(void* ptr, int nitems, type)
996 Poison Fill up memory with a pattern (byte 0xAB over and over again)
998 that hopefully catches attempts to access uninitialized memory.
999 void Poison(void* dest, int nitems, type)
1001 Renew The XSUB-writer's interface to the C "realloc" function.
1003 void Renew(void* ptr, int nitems, type)
1005 Renewc The XSUB-writer's interface to the C "realloc" function, with
1007 cast.
1008 void Renewc(void* ptr, int nitems, type, cast)
1010 Safefree
1012 The XSUB-writer's interface to the C "free" function.
1013 void Safefree(void* ptr)
1015 savepv Perl's version of "strdup()". Returns a pointer to a newly
1017 allocated string which is a duplicate of "pv". The size of the
1018 string is determined by "strlen()". The memory allocated for
1019 the new string can be freed with the "Safefree()" function.
1020 char* savepv(const char* pv)
1022 savepvn Perl's version of what "strndup()" would be if it existed.
1024 Returns a pointer to a newly allocated string which is a dupli‐
1025 cate of the first "len" bytes from "pv". The memory allocated
1026 for the new string can be freed with the "Safefree()" function.
1027 char* savepvn(const char* pv, I32 len)
1029 savesharedpv
1031 A version of "savepv()" which allocates the duplicate string in
1032 memory which is shared between threads.
1033 char* savesharedpv(const char* pv)
1035 savesvpv
1037 A version of "savepv()"/"savepvn()" which gets the string to
1038 duplicate from the passed in SV using "SvPV()"
1039 char* savesvpv(SV* sv)
1041 StructCopy
1043 This is an architecture-independent macro to copy one structure
1044 to another.
1045 void StructCopy(type src, type dest, type)
1047 Zero The XSUB-writer's interface to the C "memzero" function. The
1049 "dest" is the destination, "nitems" is the number of items, and
1050 "type" is the type.
1051 void Zero(void* dest, int nitems, type)
1053 ZeroD Like "Zero" but returns dest. Useful for encouraging compilers
1055 to tail-call optimise.
1056 void * ZeroD(void* dest, int nitems, type)
1058
1060 fbm_compile
1061 Analyses the string in order to make fast searches on it using
1062 fbm_instr() -- the Boyer-Moore algorithm.
1063 void fbm_compile(SV* sv, U32 flags)
1065 fbm_instr
1067 Returns the location of the SV in the string delimited by "str"
1068 and "strend". It returns "Nullch" if the string can't be
1069 found. The "sv" does not have to be fbm_compiled, but the
1070 search will not be as fast then.
1071 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
1073 form Takes a sprintf-style format pattern and conventional (non-SV)
1075 arguments and returns the formatted string.
1076 (char *) Perl_form(pTHX_ const char* pat, ...)
1078 can be used any place a string (char *) is required:
1080 char * s = Perl_form("%d.%d",major,minor);
1082 Uses a single private buffer so if you want to format several
1084 strings you must explicitly copy the earlier strings away (and
1085 free the copies when you are done).
1086 char* form(const char* pat, ...)
1088 getcwd_sv
1090 Fill the sv with current working directory
1091 int getcwd_sv(SV* sv)
1093 strEQ Test two strings to see if they are equal. Returns true or
1095 false.
1096 bool strEQ(char* s1, char* s2)
1098 strGE Test two strings to see if the first, "s1", is greater than or
1100 equal to the second, "s2". Returns true or false.
1101 bool strGE(char* s1, char* s2)
1103 strGT Test two strings to see if the first, "s1", is greater than the
1105 second, "s2". Returns true or false.
1106 bool strGT(char* s1, char* s2)
1108 strLE Test two strings to see if the first, "s1", is less than or
1110 equal to the second, "s2". Returns true or false.
1111 bool strLE(char* s1, char* s2)
1113 strLT Test two strings to see if the first, "s1", is less than the
1115 second, "s2". Returns true or false.
1116 bool strLT(char* s1, char* s2)
1118 strNE Test two strings to see if they are different. Returns true or
1120 false.
1121 bool strNE(char* s1, char* s2)
1123 strnEQ Test two strings to see if they are equal. The "len" parameter
1125 indicates the number of bytes to compare. Returns true or
1126 false. (A wrapper for "strncmp").
1127 bool strnEQ(char* s1, char* s2, STRLEN len)
1129 strnNE Test two strings to see if they are different. The "len"
1131 parameter indicates the number of bytes to compare. Returns
1132 true or false. (A wrapper for "strncmp").
1133 bool strnNE(char* s1, char* s2, STRLEN len)
1135 sv_nolocking
1137 Dummy routine which "locks" an SV when there is no locking mod‐
1138 ule present. Exists to avoid test for a NULL function pointer
1139 and because it could potentially warn under some level of
1140 strict-ness.
1141 void sv_nolocking(SV *)
1143 sv_nosharing
1145 Dummy routine which "shares" an SV when there is no sharing
1146 module present. Exists to avoid test for a NULL function
1147 pointer and because it could potentially warn under some level
1148 of strict-ness.
1149 void sv_nosharing(SV *)
1151 sv_nounlocking
1153 Dummy routine which "unlocks" an SV when there is no locking
1154 module present. Exists to avoid test for a NULL function
1155 pointer and because it could potentially warn under some level
1156 of strict-ness.
1157 void sv_nounlocking(SV *)
1159
1161 grok_bin
1162 converts a string representing a binary number to numeric form.
1163 On entry start and *len give the string to scan, *flags gives
1165 conversion flags, and result should be NULL or a pointer to an
1166 NV. The scan stops at the end of the string, or the first
1167 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
1168 in *flags, encountering an invalid character will also trigger
1169 a warning. On return *len is set to the length of the scanned
1170 string, and *flags gives output flags.
1171 If the value is <= "UV_MAX" it is returned as a UV, the output
1173 flags are clear, and nothing is written to *result. If the
1174 value is > UV_MAX "grok_bin" returns UV_MAX, sets
1175 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
1176 the value to *result (or the value is discarded if result is
1177 NULL).
1178 The binary number may optionally be prefixed with "0b" or "b"
1180 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
1181 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
1182 binary number may use '_' characters to separate digits.
1183 UV grok_bin(char* start, STRLEN* len, I32* flags, NV *result)
1185 grok_hex
1187 converts a string representing a hex number to numeric form.
1188 On entry start and *len give the string to scan, *flags gives
1190 conversion flags, and result should be NULL or a pointer to an
1191 NV. The scan stops at the end of the string, or the first
1192 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
1193 in *flags, encountering an invalid character will also trigger
1194 a warning. On return *len is set to the length of the scanned
1195 string, and *flags gives output flags.
1196 If the value is <= UV_MAX it is returned as a UV, the output
1198 flags are clear, and nothing is written to *result. If the
1199 value is > UV_MAX "grok_hex" returns UV_MAX, sets
1200 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
1201 the value to *result (or the value is discarded if result is
1202 NULL).
1203 The hex number may optionally be prefixed with "0x" or "x"
1205 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
1206 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the hex
1207 number may use '_' characters to separate digits.
1208 UV grok_hex(char* start, STRLEN* len, I32* flags, NV *result)
1210 grok_number
1212 Recognise (or not) a number. The type of the number is
1213 returned (0 if unrecognised), otherwise it is a bit-ORed combi‐
1214 nation of IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX,
1215 IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUM‐
1216 BER_NAN (defined in perl.h).
1217 If the value of the number can fit an in UV, it is returned in
1219 the *valuep IS_NUMBER_IN_UV will be set to indicate that *val‐
1220 uep is valid, IS_NUMBER_IN_UV will never be set unless *valuep
1221 is valid, but *valuep may have been assigned to during process‐
1222 ing even though IS_NUMBER_IN_UV is not set on return. If val‐
1223 uep is NULL, IS_NUMBER_IN_UV will be set for the same cases as
1224 when valuep is non-NULL, but no actual assignment (or SEGV)
1225 will occur.
1226 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing
1228 decimals were seen (in which case *valuep gives the true value
1229 truncated to an integer), and IS_NUMBER_NEG if the number is
1230 negative (in which case *valuep holds the absolute value).
1231 IS_NUMBER_IN_UV is not set if e notation was used or the number
1232 is larger than a UV.
1233 int grok_number(const char *pv, STRLEN len, UV *valuep)
1235 grok_numeric_radix
1237 Scan and skip for a numeric decimal separator (radix).
1238 bool grok_numeric_radix(const char **sp, const char *send)
1240 grok_oct
1242 converts a string representing an octal number to numeric form.
1243 On entry start and *len give the string to scan, *flags gives
1245 conversion flags, and result should be NULL or a pointer to an
1246 NV. The scan stops at the end of the string, or the first
1247 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
1248 in *flags, encountering an invalid character will also trigger
1249 a warning. On return *len is set to the length of the scanned
1250 string, and *flags gives output flags.
1251 If the value is <= UV_MAX it is returned as a UV, the output
1253 flags are clear, and nothing is written to *result. If the
1254 value is > UV_MAX "grok_oct" returns UV_MAX, sets
1255 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
1256 the value to *result (or the value is discarded if result is
1257 NULL).
1258 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
1260 octal number may use '_' characters to separate digits.
1261 UV grok_oct(char* start, STRLEN* len_p, I32* flags, NV *result)
1263 scan_bin
1265 For backwards compatibility. Use "grok_bin" instead.
1266 NV scan_bin(char* start, STRLEN len, STRLEN* retlen)
1268 scan_hex
1270 For backwards compatibility. Use "grok_hex" instead.
1271 NV scan_hex(char* start, STRLEN len, STRLEN* retlen)
1273 scan_oct
1275 For backwards compatibility. Use "grok_oct" instead.
1276 NV scan_oct(char* start, STRLEN len, STRLEN* retlen)
1278
1280 cv_const_sv
1281 If "cv" is a constant sub eligible for inlining. returns the
1282 constant value returned by the sub. Otherwise, returns NULL.
1283 Constant subs can be created with "newCONSTSUB" or as described
1285 in "Constant Functions" in perlsub.
1286 SV* cv_const_sv(CV* cv)
1288 newCONSTSUB
1290 Creates a constant sub equivalent to Perl "sub FOO () { 123 }"
1291 which is eligible for inlining at compile-time.
1292 CV* newCONSTSUB(HV* stash, char* name, SV* sv)
1294 newXS Used by "xsubpp" to hook up XSUBs as Perl subs.
1296
1298 pad_sv Get the value at offset po in the current pad. Use macro
1299 PAD_SV instead of calling this function directly.
1300 SV* pad_sv(PADOFFSET po)
1302
1304 dMARK Declare a stack marker variable, "mark", for the XSUB. See
1305 "MARK" and "dORIGMARK".
1306 dMARK;
1308 dORIGMARK
1310 Saves the original stack mark for the XSUB. See "ORIGMARK".
1311 dORIGMARK;
1313 dSP Declares a local copy of perl's stack pointer for the XSUB,
1315 available via the "SP" macro. See "SP".
1316 dSP;
1318 EXTEND Used to extend the argument stack for an XSUB's return values.
1320 Once used, guarantees that there is room for at least "nitems"
1321 to be pushed onto the stack.
1322 void EXTEND(SP, int nitems)
1324 MARK Stack marker variable for the XSUB. See "dMARK".
1326 mPUSHi Push an integer onto the stack. The stack must have room for
1328 this element. Handles 'set' magic. Does not use "TARG". See
1329 also "PUSHi", "mXPUSHi" and "XPUSHi".
1330 void mPUSHi(IV iv)
1332 mPUSHn Push a double onto the stack. The stack must have room for
1334 this element. Handles 'set' magic. Does not use "TARG". See
1335 also "PUSHn", "mXPUSHn" and "XPUSHn".
1336 void mPUSHn(NV nv)
1338 mPUSHp Push a string onto the stack. The stack must have room for
1340 this element. The "len" indicates the length of the string.
1341 Handles 'set' magic. Does not use "TARG". See also "PUSHp",
1342 "mXPUSHp" and "XPUSHp".
1343 void mPUSHp(char* str, STRLEN len)
1345 mPUSHu Push an unsigned integer onto the stack. The stack must have
1347 room for this element. Handles 'set' magic. Does not use
1348 "TARG". See also "PUSHu", "mXPUSHu" and "XPUSHu".
1349 void mPUSHu(UV uv)
1351 mXPUSHi Push an integer onto the stack, extending the stack if neces‐
1353 sary. Handles 'set' magic. Does not use "TARG". See also
1354 "XPUSHi", "mPUSHi" and "PUSHi".
1355 void mXPUSHi(IV iv)
1357 mXPUSHn Push a double onto the stack, extending the stack if necessary.
1359 Handles 'set' magic. Does not use "TARG". See also "XPUSHn",
1360 "mPUSHn" and "PUSHn".
1361 void mXPUSHn(NV nv)
1363 mXPUSHp Push a string onto the stack, extending the stack if necessary.
1365 The "len" indicates the length of the string. Handles 'set'
1366 magic. Does not use "TARG". See also "XPUSHp", "mPUSHp" and
1367 "PUSHp".
1368 void mXPUSHp(char* str, STRLEN len)
1370 mXPUSHu Push an unsigned integer onto the stack, extending the stack if
1372 necessary. Handles 'set' magic. Does not use "TARG". See
1373 also "XPUSHu", "mPUSHu" and "PUSHu".
1374 void mXPUSHu(UV uv)
1376 ORIGMARK
1378 The original stack mark for the XSUB. See "dORIGMARK".
1379 POPi Pops an integer off the stack.
1381 IV POPi
1383 POPl Pops a long off the stack.
1385 long POPl
1387 POPn Pops a double off the stack.
1389 NV POPn
1391 POPp Pops a string off the stack. Deprecated. New code should use
1393 POPpx.
1394 char* POPp
1396 POPpbytex
1398 Pops a string off the stack which must consist of bytes i.e.
1399 characters < 256.
1400 char* POPpbytex
1402 POPpx Pops a string off the stack.
1404 char* POPpx
1406 POPs Pops an SV off the stack.
1408 SV* POPs
1410 PUSHi Push an integer onto the stack. The stack must have room for
1412 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
1413 or "dXSTARG" should be called to declare it. Do not call mul‐
1414 tiple "TARG"-oriented macros to return lists from XSUB's - see
1415 "mPUSHi" instead. See also "XPUSHi" and "mXPUSHi".
1416 void PUSHi(IV iv)
1418 PUSHMARK
1420 Opening bracket for arguments on a callback. See "PUTBACK" and
1421 perlcall.
1422 void PUSHMARK(SP)
1424 PUSHmortal
1426 Push a new mortal SV onto the stack. The stack must have room
1427 for this element. Does not handle 'set' magic. Does not use
1428 "TARG". See also "PUSHs", "XPUSHmortal" and "XPUSHs".
1429 void PUSHmortal()
1431 PUSHn Push a double onto the stack. The stack must have room for
1433 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
1434 or "dXSTARG" should be called to declare it. Do not call mul‐
1435 tiple "TARG"-oriented macros to return lists from XSUB's - see
1436 "mPUSHn" instead. See also "XPUSHn" and "mXPUSHn".
1437 void PUSHn(NV nv)
1439 PUSHp Push a string onto the stack. The stack must have room for
1441 this element. The "len" indicates the length of the string.
1442 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
1443 should be called to declare it. Do not call multiple
1444 "TARG"-oriented macros to return lists from XSUB's - see
1445 "mPUSHp" instead. See also "XPUSHp" and "mXPUSHp".
1446 void PUSHp(char* str, STRLEN len)
1448 PUSHs Push an SV onto the stack. The stack must have room for this
1450 element. Does not handle 'set' magic. Does not use "TARG".
1451 See also "PUSHmortal", "XPUSHs" and "XPUSHmortal".
1452 void PUSHs(SV* sv)
1454 PUSHu Push an unsigned integer onto the stack. The stack must have
1456 room for this element. Handles 'set' magic. Uses "TARG", so
1457 "dTARGET" or "dXSTARG" should be called to declare it. Do not
1458 call multiple "TARG"-oriented macros to return lists from
1459 XSUB's - see "mPUSHu" instead. See also "XPUSHu" and
1460 "mXPUSHu".
1461 void PUSHu(UV uv)
1463 PUTBACK Closing bracket for XSUB arguments. This is usually handled by
1465 "xsubpp". See "PUSHMARK" and perlcall for other uses.
1466 PUTBACK;
1468 SP Stack pointer. This is usually handled by "xsubpp". See "dSP"
1470 and "SPAGAIN".
1471 SPAGAIN Refetch the stack pointer. Used after a callback. See perl‐
1473 call.
1474 SPAGAIN;
1476 XPUSHi Push an integer onto the stack, extending the stack if neces‐
1478 sary. Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXS‐
1479 TARG" should be called to declare it. Do not call multiple
1480 "TARG"-oriented macros to return lists from XSUB's - see
1481 "mXPUSHi" instead. See also "PUSHi" and "mPUSHi".
1482 void XPUSHi(IV iv)
1484 XPUSHmortal
1486 Push a new mortal SV onto the stack, extending the stack if
1487 necessary. Does not handle 'set' magic. Does not use "TARG".
1488 See also "XPUSHs", "PUSHmortal" and "PUSHs".
1489 void XPUSHmortal()
1491 XPUSHn Push a double onto the stack, extending the stack if necessary.
1493 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
1494 should be called to declare it. Do not call multiple
1495 "TARG"-oriented macros to return lists from XSUB's - see
1496 "mXPUSHn" instead. See also "PUSHn" and "mPUSHn".
1497 void XPUSHn(NV nv)
1499 XPUSHp Push a string onto the stack, extending the stack if necessary.
1501 The "len" indicates the length of the string. Handles 'set'
1502 magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be called
1503 to declare it. Do not call multiple "TARG"-oriented macros to
1504 return lists from XSUB's - see "mXPUSHp" instead. See also
1505 "PUSHp" and "mPUSHp".
1506 void XPUSHp(char* str, STRLEN len)
1508 XPUSHs Push an SV onto the stack, extending the stack if necessary.
1510 Does not handle 'set' magic. Does not use "TARG". See also
1511 "XPUSHmortal", "PUSHs" and "PUSHmortal".
1512 void XPUSHs(SV* sv)
1514 XPUSHu Push an unsigned integer onto the stack, extending the stack if
1516 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
1517 "dXSTARG" should be called to declare it. Do not call multiple
1518 "TARG"-oriented macros to return lists from XSUB's - see
1519 "mXPUSHu" instead. See also "PUSHu" and "mPUSHu".
1520 void XPUSHu(UV uv)
1522 XSRETURN
1524 Return from XSUB, indicating number of items on the stack.
1525 This is usually handled by "xsubpp".
1526 void XSRETURN(int nitems)
1528 XSRETURN_EMPTY
1530 Return an empty list from an XSUB immediately.
1531 XSRETURN_EMPTY;
1533 XSRETURN_IV
1535 Return an integer from an XSUB immediately. Uses "XST_mIV".
1536 void XSRETURN_IV(IV iv)
1538 XSRETURN_NO
1540 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
1541 XSRETURN_NO;
1543 XSRETURN_NV
1545 Return a double from an XSUB immediately. Uses "XST_mNV".
1546 void XSRETURN_NV(NV nv)
1548 XSRETURN_PV
1550 Return a copy of a string from an XSUB immediately. Uses
1551 "XST_mPV".
1552 void XSRETURN_PV(char* str)
1554 XSRETURN_UNDEF
1556 Return &PL_sv_undef from an XSUB immediately. Uses
1557 "XST_mUNDEF".
1558 XSRETURN_UNDEF;
1560 XSRETURN_UV
1562 Return an integer from an XSUB immediately. Uses "XST_mUV".
1563 void XSRETURN_UV(IV uv)
1565 XSRETURN_YES
1567 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
1568 XSRETURN_YES;
1570 XST_mIV Place an integer into the specified position "pos" on the
1572 stack. The value is stored in a new mortal SV.
1573 void XST_mIV(int pos, IV iv)
1575 XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
1577 void XST_mNO(int pos)
1579 XST_mNV Place a double into the specified position "pos" on the stack.
1581 The value is stored in a new mortal SV.
1582 void XST_mNV(int pos, NV nv)
1584 XST_mPV Place a copy of a string into the specified position "pos" on
1586 the stack. The value is stored in a new mortal SV.
1587 void XST_mPV(int pos, char* str)
1589 XST_mUNDEF
1591 Place &PL_sv_undef into the specified position "pos" on the
1592 stack.
1593 void XST_mUNDEF(int pos)
1595 XST_mYES
1597 Place &PL_sv_yes into the specified position "pos" on the
1598 stack.
1599 void XST_mYES(int pos)
1601
1603 svtype An enum of flags for Perl types. These are found in the file
1604 sv.h in the "svtype" enum. Test these flags with the "SvTYPE"
1605 macro.
1606 SVt_IV Integer type flag for scalars. See "svtype".
1608 SVt_NV Double type flag for scalars. See "svtype".
1610 SVt_PV Pointer type flag for scalars. See "svtype".
1612 SVt_PVAV
1614 Type flag for arrays. See "svtype".
1615 SVt_PVCV
1617 Type flag for code refs. See "svtype".
1618 SVt_PVHV
1620 Type flag for hashes. See "svtype".
1621 SVt_PVMG
1623 Type flag for blessed scalars. See "svtype".
1624
1626 get_sv Returns the SV of the specified Perl scalar. If "create" is
1627 set and the Perl variable does not exist then it will be cre‐
1628 ated. If "create" is not set and the variable does not exist
1629 then NULL is returned.
1630 NOTE: the perl_ form of this function is deprecated.
1632 SV* get_sv(const char* name, I32 create)
1634 looks_like_number
1636 Test if the content of an SV looks like a number (or is a num‐
1637 ber). "Inf" and "Infinity" are treated as numbers (so will not
1638 issue a non-numeric warning), even if your atof() doesn't grok
1639 them.
1640 I32 looks_like_number(SV* sv)
1642 newRV_inc
1644 Creates an RV wrapper for an SV. The reference count for the
1645 original SV is incremented.
1646 SV* newRV_inc(SV* sv)
1648 newRV_noinc
1650 Creates an RV wrapper for an SV. The reference count for the
1651 original SV is not incremented.
1652 SV* newRV_noinc(SV *sv)
1654 NEWSV Creates a new SV. A non-zero "len" parameter indicates the
1656 number of bytes of preallocated string space the SV should
1657 have. An extra byte for a tailing NUL is also reserved.
1658 (SvPOK is not set for the SV even if string space is allo‐
1659 cated.) The reference count for the new SV is set to 1. "id"
1660 is an integer id between 0 and 1299 (used to identify leaks).
1661 SV* NEWSV(int id, STRLEN len)
1663 newSV Create a new null SV, or if len > 0, create a new empty SVt_PV
1665 type SV with an initial PV allocation of len+1. Normally
1666 accessed via the "NEWSV" macro.
1667 SV* newSV(STRLEN len)
1669 newSVhek
1671 Creates a new SV from the hash key structure. It will generate
1672 scalars that point to the shared string table where possible.
1673 Returns a new (undefined) SV if the hek is NULL.
1674 SV* newSVhek(const HEK *hek)
1676 newSViv Creates a new SV and copies an integer into it. The reference
1678 count for the SV is set to 1.
1679 SV* newSViv(IV i)
1681 newSVnv Creates a new SV and copies a floating point value into it.
1683 The reference count for the SV is set to 1.
1684 SV* newSVnv(NV n)
1686 newSVpv Creates a new SV and copies a string into it. The reference
1688 count for the SV is set to 1. If "len" is zero, Perl will com‐
1689 pute the length using strlen(). For efficiency, consider using
1690 "newSVpvn" instead.
1691 SV* newSVpv(const char* s, STRLEN len)
1693 newSVpvf
1695 Creates a new SV and initializes it with the string formatted
1696 like "sprintf".
1697 SV* newSVpvf(const char* pat, ...)
1699 newSVpvn
1701 Creates a new SV and copies a string into it. The reference
1702 count for the SV is set to 1. Note that if "len" is zero, Perl
1703 will create a zero length string. You are responsible for
1704 ensuring that the source string is at least "len" bytes long.
1705 If the "s" argument is NULL the new SV will be undefined.
1706 SV* newSVpvn(const char* s, STRLEN len)
1708 newSVpvn_share
1710 Creates a new SV with its SvPVX_const pointing to a shared
1711 string in the string table. If the string does not already
1712 exist in the table, it is created first. Turns on READONLY and
1713 FAKE. The string's hash is stored in the UV slot of the SV; if
1714 the "hash" parameter is non-zero, that value is used; otherwise
1715 the hash is computed. The idea here is that as the string ta‐
1716 ble is used for shared hash keys these strings will have
1717 SvPVX_const == HeKEY and hash lookup will avoid string compare.
1718 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
1720 newSVrv Creates a new SV for the RV, "rv", to point to. If "rv" is not
1722 an RV then it will be upgraded to one. If "classname" is non-
1723 null then the new SV will be blessed in the specified package.
1724 The new SV is returned and its reference count is 1.
1725 SV* newSVrv(SV* rv, const char* classname)
1727 newSVsv Creates a new SV which is an exact duplicate of the original
1729 SV. (Uses "sv_setsv").
1730 SV* newSVsv(SV* old)
1732 newSVuv Creates a new SV and copies an unsigned integer into it. The
1734 reference count for the SV is set to 1.
1735 SV* newSVuv(UV u)
1737 SvCUR Returns the length of the string which is in the SV. See
1739 "SvLEN".
1740 STRLEN SvCUR(SV* sv)
1742 SvCUR_set
1744 Set the current length of the string which is in the SV. See
1745 "SvCUR" and "SvIV_set".
1746 void SvCUR_set(SV* sv, STRLEN len)
1748 SvEND Returns a pointer to the last character in the string which is
1750 in the SV. See "SvCUR". Access the character as *(SvEND(sv)).
1751 char* SvEND(SV* sv)
1753 SvGROW Expands the character buffer in the SV so that it has room for
1755 the indicated number of bytes (remember to reserve space for an
1756 extra trailing NUL character). Calls "sv_grow" to perform the
1757 expansion if necessary. Returns a pointer to the character
1758 buffer.
1759 char * SvGROW(SV* sv, STRLEN len)
1761 SvIOK Returns a boolean indicating whether the SV contains an inte‐
1763 ger.
1764 bool SvIOK(SV* sv)
1766 SvIOKp Returns a boolean indicating whether the SV contains an inte‐
1768 ger. Checks the private setting. Use "SvIOK".
1769 bool SvIOKp(SV* sv)
1771 SvIOK_notUV
1773 Returns a boolean indicating whether the SV contains a signed
1774 integer.
1775 bool SvIOK_notUV(SV* sv)
1777 SvIOK_off
1779 Unsets the IV status of an SV.
1780 void SvIOK_off(SV* sv)
1782 SvIOK_on
1784 Tells an SV that it is an integer.
1785 void SvIOK_on(SV* sv)
1787 SvIOK_only
1789 Tells an SV that it is an integer and disables all other OK
1790 bits.
1791 void SvIOK_only(SV* sv)
1793 SvIOK_only_UV
1795 Tells and SV that it is an unsigned integer and disables all
1796 other OK bits.
1797 void SvIOK_only_UV(SV* sv)
1799 SvIOK_UV
1801 Returns a boolean indicating whether the SV contains an
1802 unsigned integer.
1803 bool SvIOK_UV(SV* sv)
1805 SvIsCOW Returns a boolean indicating whether the SV is Copy-On-Write.
1807 (either shared hash key scalars, or full Copy On Write scalars
1808 if 5.9.0 is configured for COW)
1809 bool SvIsCOW(SV* sv)
1811 SvIsCOW_shared_hash
1813 Returns a boolean indicating whether the SV is Copy-On-Write
1814 shared hash key scalar.
1815 bool SvIsCOW_shared_hash(SV* sv)
1817 SvIV Coerces the given SV to an integer and returns it. See "SvIVx"
1819 for a version which guarantees to evaluate sv only once.
1820 IV SvIV(SV* sv)
1822 SvIVX Returns the raw value in the SV's IV slot, without checks or
1824 conversions. Only use when you are sure SvIOK is true. See
1825 also "SvIV()".
1826 IV SvIVX(SV* sv)
1828 SvIVx Coerces the given SV to an integer and returns it. Guarantees
1830 to evaluate sv only once. Use the more efficient "SvIV" other‐
1831 wise.
1832 IV SvIVx(SV* sv)
1834 SvIV_set
1836 Set the value of the IV pointer in sv to val. It is possible
1837 to perform the same function of this macro with an lvalue
1838 assignment to "SvIVX". With future Perls, however, it will be
1839 more efficient to use "SvIV_set" instead of the lvalue assign‐
1840 ment to "SvIVX".
1841 void SvIV_set(SV* sv, IV val)
1843 SvLEN Returns the size of the string buffer in the SV, not including
1845 any part attributable to "SvOOK". See "SvCUR".
1846 STRLEN SvLEN(SV* sv)
1848 SvLEN_set
1850 Set the actual length of the string which is in the SV. See
1851 "SvIV_set".
1852 void SvLEN_set(SV* sv, STRLEN len)
1854 SvMAGIC_set
1856 Set the value of the MAGIC pointer in sv to val. See
1857 "SvIV_set".
1858 void SvMAGIC_set(SV* sv, MAGIC* val)
1860 SvNIOK Returns a boolean indicating whether the SV contains a number,
1862 integer or double.
1863 bool SvNIOK(SV* sv)
1865 SvNIOKp Returns a boolean indicating whether the SV contains a number,
1867 integer or double. Checks the private setting. Use "SvNIOK".
1868 bool SvNIOKp(SV* sv)
1870 SvNIOK_off
1872 Unsets the NV/IV status of an SV.
1873 void SvNIOK_off(SV* sv)
1875 SvNOK Returns a boolean indicating whether the SV contains a double.
1877 bool SvNOK(SV* sv)
1879 SvNOKp Returns a boolean indicating whether the SV contains a double.
1881 Checks the private setting. Use "SvNOK".
1882 bool SvNOKp(SV* sv)
1884 SvNOK_off
1886 Unsets the NV status of an SV.
1887 void SvNOK_off(SV* sv)
1889 SvNOK_on
1891 Tells an SV that it is a double.
1892 void SvNOK_on(SV* sv)
1894 SvNOK_only
1896 Tells an SV that it is a double and disables all other OK bits.
1897 void SvNOK_only(SV* sv)
1899 SvNV Coerce the given SV to a double and return it. See "SvNVx" for
1901 a version which guarantees to evaluate sv only once.
1902 NV SvNV(SV* sv)
1904 SvNVX Returns the raw value in the SV's NV slot, without checks or
1906 conversions. Only use when you are sure SvNOK is true. See
1907 also "SvNV()".
1908 NV SvNVX(SV* sv)
1910 SvNVx Coerces the given SV to a double and returns it. Guarantees to
1912 evaluate sv only once. Use the more efficient "SvNV" otherwise.
1913 NV SvNVx(SV* sv)
1915 SvNV_set
1917 Set the value of the NV pointer in sv to val. See "SvIV_set".
1918 void SvNV_set(SV* sv, NV val)
1920 SvOK Returns a boolean indicating whether the value is an SV. It
1922 also tells whether the value is defined or not.
1923 bool SvOK(SV* sv)
1925 SvOOK Returns a boolean indicating whether the SvIVX is a valid off‐
1927 set value for the SvPVX. This hack is used internally to speed
1928 up removal of characters from the beginning of a SvPV. When
1929 SvOOK is true, then the start of the allocated string buffer is
1930 really (SvPVX - SvIVX).
1931 bool SvOOK(SV* sv)
1933 SvPOK Returns a boolean indicating whether the SV contains a charac‐
1935 ter string.
1936 bool SvPOK(SV* sv)
1938 SvPOKp Returns a boolean indicating whether the SV contains a charac‐
1940 ter string. Checks the private setting. Use "SvPOK".
1941 bool SvPOKp(SV* sv)
1943 SvPOK_off
1945 Unsets the PV status of an SV.
1946 void SvPOK_off(SV* sv)
1948 SvPOK_on
1950 Tells an SV that it is a string.
1951 void SvPOK_on(SV* sv)
1953 SvPOK_only
1955 Tells an SV that it is a string and disables all other OK bits.
1956 Will also turn off the UTF-8 status.
1957 void SvPOK_only(SV* sv)
1959 SvPOK_only_UTF8
1961 Tells an SV that it is a string and disables all other OK bits,
1962 and leaves the UTF-8 status as it was.
1963 void SvPOK_only_UTF8(SV* sv)
1965 SvPV Returns a pointer to the string in the SV, or a stringified
1967 form of the SV if the SV does not contain a string. The SV may
1968 cache the stringified version becoming "SvPOK". Handles 'get'
1969 magic. See also "SvPVx" for a version which guarantees to eval‐
1970 uate sv only once.
1971 char* SvPV(SV* sv, STRLEN len)
1973 SvPVbyte
1975 Like "SvPV", but converts sv to byte representation first if
1976 necessary.
1977 char* SvPVbyte(SV* sv, STRLEN len)
1979 SvPVbytex
1981 Like "SvPV", but converts sv to byte representation first if
1982 necessary. Guarantees to evaluate sv only once; use the more
1983 efficient "SvPVbyte" otherwise.
1984 char* SvPVbytex(SV* sv, STRLEN len)
1986 SvPVbytex_force
1988 Like "SvPV_force", but converts sv to byte representation first
1989 if necessary. Guarantees to evaluate sv only once; use the
1990 more efficient "SvPVbyte_force" otherwise.
1991 char* SvPVbytex_force(SV* sv, STRLEN len)
1993 SvPVbyte_force
1995 Like "SvPV_force", but converts sv to byte representation first
1996 if necessary.
1997 char* SvPVbyte_force(SV* sv, STRLEN len)
1999 SvPVbyte_nolen
2001 Like "SvPV_nolen", but converts sv to byte representation first
2002 if necessary.
2003 char* SvPVbyte_nolen(SV* sv)
2005 SvPVutf8
2007 Like "SvPV", but converts sv to utf8 first if necessary.
2008 char* SvPVutf8(SV* sv, STRLEN len)
2010 SvPVutf8x
2012 Like "SvPV", but converts sv to utf8 first if necessary. Guar‐
2013 antees to evaluate sv only once; use the more efficient
2014 "SvPVutf8" otherwise.
2015 char* SvPVutf8x(SV* sv, STRLEN len)
2017 SvPVutf8x_force
2019 Like "SvPV_force", but converts sv to utf8 first if necessary.
2020 Guarantees to evaluate sv only once; use the more efficient
2021 "SvPVutf8_force" otherwise.
2022 char* SvPVutf8x_force(SV* sv, STRLEN len)
2024 SvPVutf8_force
2026 Like "SvPV_force", but converts sv to utf8 first if necessary.
2027 char* SvPVutf8_force(SV* sv, STRLEN len)
2029 SvPVutf8_nolen
2031 Like "SvPV_nolen", but converts sv to utf8 first if necessary.
2032 char* SvPVutf8_nolen(SV* sv)
2034 SvPVX Returns a pointer to the physical string in the SV. The SV
2036 must contain a string.
2037 char* SvPVX(SV* sv)
2039 SvPVx A version of "SvPV" which guarantees to evaluate sv only once.
2041 char* SvPVx(SV* sv, STRLEN len)
2043 SvPV_force
2045 Like "SvPV" but will force the SV into containing just a string
2046 ("SvPOK_only"). You want force if you are going to update the
2047 "SvPVX" directly.
2048 char* SvPV_force(SV* sv, STRLEN len)
2050 SvPV_force_nomg
2052 Like "SvPV" but will force the SV into containing just a string
2053 ("SvPOK_only"). You want force if you are going to update the
2054 "SvPVX" directly. Doesn't process magic.
2055 char* SvPV_force_nomg(SV* sv, STRLEN len)
2057 SvPV_nolen
2059 Returns a pointer to the string in the SV, or a stringified
2060 form of the SV if the SV does not contain a string. The SV may
2061 cache the stringified form becoming "SvPOK". Handles 'get'
2062 magic.
2063 char* SvPV_nolen(SV* sv)
2065 SvPV_set
2067 Set the value of the PV pointer in sv to val. See "SvIV_set".
2068 void SvPV_set(SV* sv, char* val)
2070 SvREFCNT
2072 Returns the value of the object's reference count.
2073 U32 SvREFCNT(SV* sv)
2075 SvREFCNT_dec
2077 Decrements the reference count of the given SV.
2078 void SvREFCNT_dec(SV* sv)
2080 SvREFCNT_inc
2082 Increments the reference count of the given SV.
2083 SV* SvREFCNT_inc(SV* sv)
2085 SvROK Tests if the SV is an RV.
2087 bool SvROK(SV* sv)
2089 SvROK_off
2091 Unsets the RV status of an SV.
2092 void SvROK_off(SV* sv)
2094 SvROK_on
2096 Tells an SV that it is an RV.
2097 void SvROK_on(SV* sv)
2099 SvRV Dereferences an RV to return the SV.
2101 SV* SvRV(SV* sv)
2103 SvRV_set
2105 Set the value of the RV pointer in sv to val. See "SvIV_set".
2106 void SvRV_set(SV* sv, SV* val)
2108 SvSTASH Returns the stash of the SV.
2110 HV* SvSTASH(SV* sv)
2112 SvSTASH_set
2114 Set the value of the STASH pointer in sv to val. See
2115 "SvIV_set".
2116 void SvSTASH_set(SV* sv, STASH* val)
2118 SvTAINT Taints an SV if tainting is enabled.
2120 void SvTAINT(SV* sv)
2122 SvTAINTED
2124 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE
2125 if not.
2126 bool SvTAINTED(SV* sv)
2128 SvTAINTED_off
2130 Untaints an SV. Be very careful with this routine, as it short-
2131 circuits some of Perl's fundamental security features. XS mod‐
2132 ule authors should not use this function unless they fully
2133 understand all the implications of unconditionally untainting
2134 the value. Untainting should be done in the standard perl fash‐
2135 ion, via a carefully crafted regexp, rather than directly
2136 untainting variables.
2137 void SvTAINTED_off(SV* sv)
2139 SvTAINTED_on
2141 Marks an SV as tainted if tainting is enabled.
2142 void SvTAINTED_on(SV* sv)
2144 SvTRUE Returns a boolean indicating whether Perl would evaluate the SV
2146 as true or false, defined or undefined. Does not handle 'get'
2147 magic.
2148 bool SvTRUE(SV* sv)
2150 SvTYPE Returns the type of the SV. See "svtype".
2152 svtype SvTYPE(SV* sv)
2154 SvUOK Returns a boolean indicating whether the SV contains an
2156 unsigned integer.
2157 void SvUOK(SV* sv)
2159 SvUPGRADE
2161 Used to upgrade an SV to a more complex form. Uses
2162 "sv_upgrade" to perform the upgrade if necessary. See
2163 "svtype".
2164 void SvUPGRADE(SV* sv, svtype type)
2166 SvUTF8 Returns a boolean indicating whether the SV contains UTF-8
2168 encoded data.
2169 bool SvUTF8(SV* sv)
2171 SvUTF8_off
2173 Unsets the UTF-8 status of an SV.
2174 void SvUTF8_off(SV *sv)
2176 SvUTF8_on
2178 Turn on the UTF-8 status of an SV (the data is not changed,
2179 just the flag). Do not use frivolously.
2180 void SvUTF8_on(SV *sv)
2182 SvUV Coerces the given SV to an unsigned integer and returns it.
2184 See "SvUVx" for a version which guarantees to evaluate sv only
2185 once.
2186 UV SvUV(SV* sv)
2188 SvUVX Returns the raw value in the SV's UV slot, without checks or
2190 conversions. Only use when you are sure SvIOK is true. See
2191 also "SvUV()".
2192 UV SvUVX(SV* sv)
2194 SvUVx Coerces the given SV to an unsigned integer and returns it.
2196 Guarantees to evaluate sv only once. Use the more efficient
2197 "SvUV" otherwise.
2198 UV SvUVx(SV* sv)
2200 SvUV_set
2202 Set the value of the UV pointer in sv to val. See "SvIV_set".
2203 void SvUV_set(SV* sv, UV val)
2205 sv_2bool
2207 This function is only called on magical items, and is only used
2208 by sv_true() or its macro equivalent.
2209 bool sv_2bool(SV* sv)
2211 sv_2cv Using various gambits, try to get a CV from an SV; in addition,
2213 try if possible to set *st and *gvp to the stash and GV associ‐
2214 ated with it.
2215 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
2217 sv_2io Using various gambits, try to get an IO from an SV: the IO slot
2219 if its a GV; or the recursive result if we're an RV; or the IO
2220 slot of the symbol named after the PV if we're a string.
2221 IO* sv_2io(SV* sv)
2223 sv_2iv Return the integer value of an SV, doing any necessary string
2225 conversion, magic etc. Normally used via the "SvIV(sv)" and
2226 "SvIVx(sv)" macros.
2227 IV sv_2iv(SV* sv)
2229 sv_2mortal
2231 Marks an existing SV as mortal. The SV will be destroyed
2232 "soon", either by an explicit call to FREETMPS, or by an
2233 implicit call at places such as statement boundaries. SvTEMP()
2234 is turned on which means that the SV's string buffer can be
2235 "stolen" if this SV is copied. See also "sv_newmortal" and
2236 "sv_mortalcopy".
2237 SV* sv_2mortal(SV* sv)
2239 sv_2nv Return the num value of an SV, doing any necessary string or
2241 integer conversion, magic etc. Normally used via the "SvNV(sv)"
2242 and "SvNVx(sv)" macros.
2243 NV sv_2nv(SV* sv)
2245 sv_2pvbyte
2247 Return a pointer to the byte-encoded representation of the SV,
2248 and set *lp to its length. May cause the SV to be downgraded
2249 from UTF-8 as a side-effect.
2250 Usually accessed via the "SvPVbyte" macro.
2252 char* sv_2pvbyte(SV* sv, STRLEN* lp)
2254 sv_2pvbyte_nolen
2256 Return a pointer to the byte-encoded representation of the SV.
2257 May cause the SV to be downgraded from UTF-8 as a side-effect.
2258 Usually accessed via the "SvPVbyte_nolen" macro.
2260 char* sv_2pvbyte_nolen(SV* sv)
2262 sv_2pvutf8
2264 Return a pointer to the UTF-8-encoded representation of the SV,
2265 and set *lp to its length. May cause the SV to be upgraded to
2266 UTF-8 as a side-effect.
2267 Usually accessed via the "SvPVutf8" macro.
2269 char* sv_2pvutf8(SV* sv, STRLEN* lp)
2271 sv_2pvutf8_nolen
2273 Return a pointer to the UTF-8-encoded representation of the SV.
2274 May cause the SV to be upgraded to UTF-8 as a side-effect.
2275 Usually accessed via the "SvPVutf8_nolen" macro.
2277 char* sv_2pvutf8_nolen(SV* sv)
2279 sv_2pv_flags
2281 Returns a pointer to the string value of an SV, and sets *lp to
2282 its length. If flags includes SV_GMAGIC, does an mg_get()
2283 first. Coerces sv to a string if necessary. Normally invoked
2284 via the "SvPV_flags" macro. "sv_2pv()" and "sv_2pv_nomg" usu‐
2285 ally end up here too.
2286 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
2288 sv_2pv_nolen
2290 Like "sv_2pv()", but doesn't return the length too. You should
2291 usually use the macro wrapper "SvPV_nolen(sv)" instead.
2292 char* sv_2pv_nolen(SV* sv)
2293 sv_2uv Return the unsigned integer value of an SV, doing any necessary
2295 string conversion, magic etc. Normally used via the "SvUV(sv)"
2296 and "SvUVx(sv)" macros.
2297 UV sv_2uv(SV* sv)
2299 sv_backoff
2301 Remove any string offset. You should normally use the
2302 "SvOOK_off" macro wrapper instead.
2303 int sv_backoff(SV* sv)
2305 sv_bless
2307 Blesses an SV into a specified package. The SV must be an RV.
2308 The package must be designated by its stash (see
2309 "gv_stashpv()"). The reference count of the SV is unaffected.
2310 SV* sv_bless(SV* sv, HV* stash)
2312 sv_catpv
2314 Concatenates the string onto the end of the string which is in
2315 the SV. If the SV has the UTF-8 status set, then the bytes
2316 appended should be valid UTF-8. Handles 'get' magic, but not
2317 'set' magic. See "sv_catpv_mg".
2318 void sv_catpv(SV* sv, const char* ptr)
2320 sv_catpvf
2322 Processes its arguments like "sprintf" and appends the format‐
2323 ted output to an SV. If the appended data contains "wide"
2324 characters (including, but not limited to, SVs with a UTF-8 PV
2325 formatted with %s, and characters >255 formatted with %c), the
2326 original SV might get upgraded to UTF-8. Handles 'get' magic,
2327 but not 'set' magic. See "sv_catpvf_mg". If the original SV
2328 was UTF-8, the pattern should be valid UTF-8; if the original
2329 SV was bytes, the pattern should be too.
2330 void sv_catpvf(SV* sv, const char* pat, ...)
2332 sv_catpvf_mg
2334 Like "sv_catpvf", but also handles 'set' magic.
2335 void sv_catpvf_mg(SV *sv, const char* pat, ...)
2337 sv_catpvn
2339 Concatenates the string onto the end of the string which is in
2340 the SV. The "len" indicates number of bytes to copy. If the
2341 SV has the UTF-8 status set, then the bytes appended should be
2342 valid UTF-8. Handles 'get' magic, but not 'set' magic. See
2343 "sv_catpvn_mg".
2344 void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
2346 sv_catpvn_flags
2348 Concatenates the string onto the end of the string which is in
2349 the SV. The "len" indicates number of bytes to copy. If the
2350 SV has the UTF-8 status set, then the bytes appended should be
2351 valid UTF-8. If "flags" has "SV_GMAGIC" bit set, will "mg_get"
2352 on "dsv" if appropriate, else not. "sv_catpvn" and "sv_cat‐
2353 pvn_nomg" are implemented in terms of this function.
2354 void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
2356 sv_catpvn_mg
2358 Like "sv_catpvn", but also handles 'set' magic.
2359 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
2361 sv_catpvn_nomg
2363 Like "sv_catpvn" but doesn't process magic.
2364 void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
2366 sv_catpv_mg
2368 Like "sv_catpv", but also handles 'set' magic.
2369 void sv_catpv_mg(SV *sv, const char *ptr)
2371 sv_catsv
2373 Concatenates the string from SV "ssv" onto the end of the
2374 string in SV "dsv". Modifies "dsv" but not "ssv". Handles
2375 'get' magic, but not 'set' magic. See "sv_catsv_mg".
2376 void sv_catsv(SV* dsv, SV* ssv)
2378 sv_catsv_flags
2380 Concatenates the string from SV "ssv" onto the end of the
2381 string in SV "dsv". Modifies "dsv" but not "ssv". If "flags"
2382 has "SV_GMAGIC" bit set, will "mg_get" on the SVs if appropri‐
2383 ate, else not. "sv_catsv" and "sv_catsv_nomg" are implemented
2384 in terms of this function.
2385 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
2387 sv_catsv_mg
2389 Like "sv_catsv", but also handles 'set' magic.
2390 void sv_catsv_mg(SV *dstr, SV *sstr)
2392 sv_catsv_nomg
2394 Like "sv_catsv" but doesn't process magic.
2395 void sv_catsv_nomg(SV* dsv, SV* ssv)
2397 sv_chop Efficient removal of characters from the beginning of the
2399 string buffer. SvPOK(sv) must be true and the "ptr" must be a
2400 pointer to somewhere inside the string buffer. The "ptr"
2401 becomes the first character of the adjusted string. Uses the
2402 "OOK hack". Beware: after this function returns, "ptr" and
2403 SvPVX_const(sv) may no longer refer to the same chunk of data.
2404 void sv_chop(SV* sv, char* ptr)
2406 sv_clear
2408 Clear an SV: call any destructors, free up any memory used by
2409 the body, and free the body itself. The SV's head is not freed,
2410 although its type is set to all 1's so that it won't inadver‐
2411 tently be assumed to be live during global destruction etc.
2412 This function should only be called when REFCNT is zero. Most
2413 of the time you'll want to call "sv_free()" (or its macro wrap‐
2414 per "SvREFCNT_dec") instead.
2415 void sv_clear(SV* sv)
2417 sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1 indicat‐
2419 ing whether the string in "sv1" is less than, equal to, or
2420 greater than the string in "sv2". Is UTF-8 and 'use bytes'
2421 aware, handles get magic, and will coerce its args to strings
2422 if necessary. See also "sv_cmp_locale".
2423 I32 sv_cmp(SV* sv1, SV* sv2)
2425 sv_cmp_locale
2427 Compares the strings in two SVs in a locale-aware manner. Is
2428 UTF-8 and 'use bytes' aware, handles get magic, and will coerce
2429 its args to strings if necessary. See also "sv_cmp_locale".
2430 See also "sv_cmp".
2431 I32 sv_cmp_locale(SV* sv1, SV* sv2)
2433 sv_collxfrm
2435 Add Collate Transform magic to an SV if it doesn't already have
2436 it.
2437 Any scalar variable may carry PERL_MAGIC_collxfrm magic that
2439 contains the scalar data of the variable, but transformed to
2440 such a format that a normal memory comparison can be used to
2441 compare the data according to the locale settings.
2442 char* sv_collxfrm(SV* sv, STRLEN* nxp)
2444 sv_copypv
2446 Copies a stringified representation of the source SV into the
2447 destination SV. Automatically performs any necessary mg_get
2448 and coercion of numeric values into strings. Guaranteed to
2449 preserve UTF-8 flag even from overloaded objects. Similar in
2450 nature to sv_2pv[_flags] but operates directly on an SV instead
2451 of just the string. Mostly uses sv_2pv_flags to do its work,
2452 except when that would lose the UTF-8'ness of the PV.
2453 void sv_copypv(SV* dsv, SV* ssv)
2455 sv_dec Auto-decrement of the value in the SV, doing string to numeric
2457 conversion if necessary. Handles 'get' magic.
2458 void sv_dec(SV* sv)
2460 sv_derived_from
2462 Returns a boolean indicating whether the SV is derived from the
2463 specified class. This is the function that implements "UNIVER‐
2464 SAL::isa". It works for class names as well as for objects.
2465 bool sv_derived_from(SV* sv, const char* name)
2467 sv_eq Returns a boolean indicating whether the strings in the two SVs
2469 are identical. Is UTF-8 and 'use bytes' aware, handles get
2470 magic, and will coerce its args to strings if necessary.
2471 I32 sv_eq(SV* sv1, SV* sv2)
2473 sv_force_normal
2475 Undo various types of fakery on an SV: if the PV is a shared
2476 string, make a private copy; if we're a ref, stop refing; if
2477 we're a glob, downgrade to an xpvmg. See also "sv_force_nor‐
2478 mal_flags".
2479 void sv_force_normal(SV *sv)
2481 sv_force_normal_flags
2483 Undo various types of fakery on an SV: if the PV is a shared
2484 string, make a private copy; if we're a ref, stop refing; if
2485 we're a glob, downgrade to an xpvmg. The "flags" parameter gets
2486 passed to "sv_unref_flags()" when unrefing. "sv_force_normal"
2487 calls this function with flags set to 0.
2488 void sv_force_normal_flags(SV *sv, U32 flags)
2490 sv_free Decrement an SV's reference count, and if it drops to zero,
2492 call "sv_clear" to invoke destructors and free up any memory
2493 used by the body; finally, deallocate the SV's head itself.
2494 Normally called via a wrapper macro "SvREFCNT_dec".
2495 void sv_free(SV* sv)
2497 sv_gets Get a line from the filehandle and store it into the SV,
2499 optionally appending to the currently-stored string.
2500 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
2502 sv_grow Expands the character buffer in the SV. If necessary, uses
2504 "sv_unref" and upgrades the SV to "SVt_PV". Returns a pointer
2505 to the character buffer. Use the "SvGROW" wrapper instead.
2506 char* sv_grow(SV* sv, STRLEN newlen)
2508 sv_inc Auto-increment of the value in the SV, doing string to numeric
2510 conversion if necessary. Handles 'get' magic.
2511 void sv_inc(SV* sv)
2513 sv_insert
2515 Inserts a string at the specified offset/length within the SV.
2516 Similar to the Perl substr() function.
2517 void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, char* little, STRLEN littlelen)
2519 sv_isa Returns a boolean indicating whether the SV is blessed into the
2521 specified class. This does not check for subtypes; use
2522 "sv_derived_from" to verify an inheritance relationship.
2523 int sv_isa(SV* sv, const char* name)
2525 sv_isobject
2527 Returns a boolean indicating whether the SV is an RV pointing
2528 to a blessed object. If the SV is not an RV, or if the object
2529 is not blessed, then this will return false.
2530 int sv_isobject(SV* sv)
2532 sv_iv A private implementation of the "SvIVx" macro for compilers
2534 which can't cope with complex macro expressions. Always use the
2535 macro instead.
2536 IV sv_iv(SV* sv)
2538 sv_len Returns the length of the string in the SV. Handles magic and
2540 type coercion. See also "SvCUR", which gives raw access to the
2541 xpv_cur slot.
2542 STRLEN sv_len(SV* sv)
2544 sv_len_utf8
2546 Returns the number of characters in the string in an SV, count‐
2547 ing wide UTF-8 bytes as a single character. Handles magic and
2548 type coercion.
2549 STRLEN sv_len_utf8(SV* sv)
2551 sv_magic
2553 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
2554 necessary, then adds a new magic item of type "how" to the head
2555 of the magic list.
2556 See "sv_magicext" (which "sv_magic" now calls) for a descrip‐
2558 tion of the handling of the "name" and "namlen" arguments.
2559 You need to use "sv_magicext" to add magic to SvREADONLY SVs
2561 and also to add more than one instance of the same 'how'.
2562 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
2564 sv_magicext
2566 Adds magic to an SV, upgrading it if necessary. Applies the
2567 supplied vtable and returns a pointer to the magic added.
2568 Note that "sv_magicext" will allow things that "sv_magic" will
2570 not. In particular, you can add magic to SvREADONLY SVs, and
2571 add more than one instance of the same 'how'.
2572 If "namlen" is greater than zero then a "savepvn" copy of
2574 "name" is stored, if "namlen" is zero then "name" is stored as-
2575 is and - as another special case - if "(name && namlen ==
2576 HEf_SVKEY)" then "name" is assumed to contain an "SV*" and is
2577 stored as-is with its REFCNT incremented.
2578 (This is now used as a subroutine by "sv_magic".)
2580 MAGIC * sv_magicext(SV* sv, SV* obj, int how, MGVTBL *vtbl, const char* name, I32 namlen)
2582 sv_mortalcopy
2584 Creates a new SV which is a copy of the original SV (using
2585 "sv_setsv"). The new SV is marked as mortal. It will be
2586 destroyed "soon", either by an explicit call to FREETMPS, or by
2587 an implicit call at places such as statement boundaries. See
2588 also "sv_newmortal" and "sv_2mortal".
2589 SV* sv_mortalcopy(SV* oldsv)
2591 sv_newmortal
2593 Creates a new null SV which is mortal. The reference count of
2594 the SV is set to 1. It will be destroyed "soon", either by an
2595 explicit call to FREETMPS, or by an implicit call at places
2596 such as statement boundaries. See also "sv_mortalcopy" and
2597 "sv_2mortal".
2598 SV* sv_newmortal()
2600 sv_newref
2602 Increment an SV's reference count. Use the "SvREFCNT_inc()"
2603 wrapper instead.
2604 SV* sv_newref(SV* sv)
2606 sv_nv A private implementation of the "SvNVx" macro for compilers
2608 which can't cope with complex macro expressions. Always use the
2609 macro instead.
2610 NV sv_nv(SV* sv)
2612 sv_pos_b2u
2614 Converts the value pointed to by offsetp from a count of bytes
2615 from the start of the string, to a count of the equivalent num‐
2616 ber of UTF-8 chars. Handles magic and type coercion.
2617 void sv_pos_b2u(SV* sv, I32* offsetp)
2619 sv_pos_u2b
2621 Converts the value pointed to by offsetp from a count of UTF-8
2622 chars from the start of the string, to a count of the equiva‐
2623 lent number of bytes; if lenp is non-zero, it does the same to
2624 lenp, but this time starting from the offset, rather than from
2625 the start of the string. Handles magic and type coercion.
2626 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
2628 sv_pv Use the "SvPV_nolen" macro instead
2630 char* sv_pv(SV *sv)
2632 sv_pvbyte
2634 Use "SvPVbyte_nolen" instead.
2635 char* sv_pvbyte(SV *sv)
2637 sv_pvbyten
2639 A private implementation of the "SvPVbyte" macro for compilers
2640 which can't cope with complex macro expressions. Always use the
2641 macro instead.
2642 char* sv_pvbyten(SV *sv, STRLEN *len)
2644 sv_pvbyten_force
2646 A private implementation of the "SvPVbytex_force" macro for
2647 compilers which can't cope with complex macro expressions.
2648 Always use the macro instead.
2649 char* sv_pvbyten_force(SV* sv, STRLEN* lp)
2651 sv_pvn A private implementation of the "SvPV" macro for compilers
2653 which can't cope with complex macro expressions. Always use the
2654 macro instead.
2655 char* sv_pvn(SV *sv, STRLEN *len)
2657 sv_pvn_force
2659 Get a sensible string out of the SV somehow. A private imple‐
2660 mentation of the "SvPV_force" macro for compilers which can't
2661 cope with complex macro expressions. Always use the macro
2662 instead.
2663 char* sv_pvn_force(SV* sv, STRLEN* lp)
2665 sv_pvn_force_flags
2667 Get a sensible string out of the SV somehow. If "flags" has
2668 "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
2669 not. "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
2670 terms of this function. You normally want to use the various
2671 wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg"
2672 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
2674 sv_pvutf8
2676 Use the "SvPVutf8_nolen" macro instead
2677 char* sv_pvutf8(SV *sv)
2679 sv_pvutf8n
2681 A private implementation of the "SvPVutf8" macro for compilers
2682 which can't cope with complex macro expressions. Always use the
2683 macro instead.
2684 char* sv_pvutf8n(SV *sv, STRLEN *len)
2686 sv_pvutf8n_force
2688 A private implementation of the "SvPVutf8_force" macro for com‐
2689 pilers which can't cope with complex macro expressions. Always
2690 use the macro instead.
2691 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
2693 sv_reftype
2695 Returns a string describing what the SV is a reference to.
2696 char* sv_reftype(SV* sv, int ob)
2698 sv_replace
2700 Make the first argument a copy of the second, then delete the
2701 original. The target SV physically takes over ownership of the
2702 body of the source SV and inherits its flags; however, the tar‐
2703 get keeps any magic it owns, and any magic in the source is
2704 discarded. Note that this is a rather specialist SV copying
2705 operation; most of the time you'll want to use "sv_setsv" or
2706 one of its many macro front-ends.
2707 void sv_replace(SV* sv, SV* nsv)
2709 sv_report_used
2711 Dump the contents of all SVs not yet freed. (Debugging aid).
2712 void sv_report_used()
2714 sv_reset
2716 Underlying implementation for the "reset" Perl function. Note
2717 that the perl-level function is vaguely deprecated.
2718 void sv_reset(char* s, HV* stash)
2720 sv_rvweaken
2722 Weaken a reference: set the "SvWEAKREF" flag on this RV; give
2723 the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
2724 already; and push a back-reference to this RV onto the array of
2725 backreferences associated with that magic.
2726 SV* sv_rvweaken(SV *sv)
2728 sv_setiv
2730 Copies an integer into the given SV, upgrading first if neces‐
2731 sary. Does not handle 'set' magic. See also "sv_setiv_mg".
2732 void sv_setiv(SV* sv, IV num)
2734 sv_setiv_mg
2736 Like "sv_setiv", but also handles 'set' magic.
2737 void sv_setiv_mg(SV *sv, IV i)
2739 sv_setnv
2741 Copies a double into the given SV, upgrading first if neces‐
2742 sary. Does not handle 'set' magic. See also "sv_setnv_mg".
2743 void sv_setnv(SV* sv, NV num)
2745 sv_setnv_mg
2747 Like "sv_setnv", but also handles 'set' magic.
2748 void sv_setnv_mg(SV *sv, NV num)
2750 sv_setpv
2752 Copies a string into an SV. The string must be null-termi‐
2753 nated. Does not handle 'set' magic. See "sv_setpv_mg".
2754 void sv_setpv(SV* sv, const char* ptr)
2756 sv_setpvf
2758 Works like "sv_catpvf" but copies the text into the SV instead
2759 of appending it. Does not handle 'set' magic. See "sv_set‐
2760 pvf_mg".
2761 void sv_setpvf(SV* sv, const char* pat, ...)
2763 sv_setpvf_mg
2765 Like "sv_setpvf", but also handles 'set' magic.
2766 void sv_setpvf_mg(SV *sv, const char* pat, ...)
2768 sv_setpviv
2770 Copies an integer into the given SV, also updating its string
2771 value. Does not handle 'set' magic. See "sv_setpviv_mg".
2772 void sv_setpviv(SV* sv, IV num)
2774 sv_setpviv_mg
2776 Like "sv_setpviv", but also handles 'set' magic.
2777 void sv_setpviv_mg(SV *sv, IV iv)
2779 sv_setpvn
2781 Copies a string into an SV. The "len" parameter indicates the
2782 number of bytes to be copied. If the "ptr" argument is NULL
2783 the SV will become undefined. Does not handle 'set' magic.
2784 See "sv_setpvn_mg".
2785 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
2787 sv_setpvn_mg
2789 Like "sv_setpvn", but also handles 'set' magic.
2790 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
2792 sv_setpv_mg
2794 Like "sv_setpv", but also handles 'set' magic.
2795 void sv_setpv_mg(SV *sv, const char *ptr)
2797 sv_setref_iv
2799 Copies an integer into a new SV, optionally blessing the SV.
2800 The "rv" argument will be upgraded to an RV. That RV will be
2801 modified to point to the new SV. The "classname" argument
2802 indicates the package for the blessing. Set "classname" to
2803 "Nullch" to avoid the blessing. The new SV will have a refer‐
2804 ence count of 1, and the RV will be returned.
2805 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
2807 sv_setref_nv
2809 Copies a double into a new SV, optionally blessing the SV. The
2810 "rv" argument will be upgraded to an RV. That RV will be modi‐
2811 fied to point to the new SV. The "classname" argument indi‐
2812 cates the package for the blessing. Set "classname" to
2813 "Nullch" to avoid the blessing. The new SV will have a refer‐
2814 ence count of 1, and the RV will be returned.
2815 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
2817 sv_setref_pv
2819 Copies a pointer into a new SV, optionally blessing the SV.
2820 The "rv" argument will be upgraded to an RV. That RV will be
2821 modified to point to the new SV. If the "pv" argument is NULL
2822 then "PL_sv_undef" will be placed into the SV. The "classname"
2823 argument indicates the package for the blessing. Set "class‐
2824 name" to "Nullch" to avoid the blessing. The new SV will have
2825 a reference count of 1, and the RV will be returned.
2826 Do not use with other Perl types such as HV, AV, SV, CV,
2828 because those objects will become corrupted by the pointer copy
2829 process.
2830 Note that "sv_setref_pvn" copies the string while this copies
2832 the pointer.
2833 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
2835 sv_setref_pvn
2837 Copies a string into a new SV, optionally blessing the SV. The
2838 length of the string must be specified with "n". The "rv"
2839 argument will be upgraded to an RV. That RV will be modified
2840 to point to the new SV. The "classname" argument indicates the
2841 package for the blessing. Set "classname" to "Nullch" to avoid
2842 the blessing. The new SV will have a reference count of 1, and
2843 the RV will be returned.
2844 Note that "sv_setref_pv" copies the pointer while this copies
2846 the string.
2847 SV* sv_setref_pvn(SV* rv, const char* classname, char* pv, STRLEN n)
2849 sv_setref_uv
2851 Copies an unsigned integer into a new SV, optionally blessing
2852 the SV. The "rv" argument will be upgraded to an RV. That RV
2853 will be modified to point to the new SV. The "classname" argu‐
2854 ment indicates the package for the blessing. Set "classname"
2855 to "Nullch" to avoid the blessing. The new SV will have a ref‐
2856 erence count of 1, and the RV will be returned.
2857 SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
2859 sv_setsv
2861 Copies the contents of the source SV "ssv" into the destination
2862 SV "dsv". The source SV may be destroyed if it is mortal, so
2863 don't use this function if the source SV needs to be reused.
2864 Does not handle 'set' magic. Loosely speaking, it performs a
2865 copy-by-value, obliterating any previous content of the desti‐
2866 nation.
2867 You probably want to use one of the assortment of wrappers,
2869 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
2870 "SvSetMagicSV_nosteal".
2871 void sv_setsv(SV* dsv, SV* ssv)
2873 sv_setsv_flags
2875 Copies the contents of the source SV "ssv" into the destination
2876 SV "dsv". The source SV may be destroyed if it is mortal, so
2877 don't use this function if the source SV needs to be reused.
2878 Does not handle 'set' magic. Loosely speaking, it performs a
2879 copy-by-value, obliterating any previous content of the desti‐
2880 nation. If the "flags" parameter has the "SV_GMAGIC" bit set,
2881 will "mg_get" on "ssv" if appropriate, else not. If the "flags"
2882 parameter has the "NOSTEAL" bit set then the buffers of temps
2883 will not be stolen. <sv_setsv> and "sv_setsv_nomg" are imple‐
2884 mented in terms of this function.
2885 You probably want to use one of the assortment of wrappers,
2887 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
2888 "SvSetMagicSV_nosteal".
2889 This is the primary function for copying scalars, and most
2891 other copy-ish functions and macros use this underneath.
2892 void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
2894 sv_setsv_mg
2896 Like "sv_setsv", but also handles 'set' magic.
2897 void sv_setsv_mg(SV *dstr, SV *sstr)
2899 sv_setsv_nomg
2901 Like "sv_setsv" but doesn't process magic.
2902 void sv_setsv_nomg(SV* dsv, SV* ssv)
2904 sv_setuv
2906 Copies an unsigned integer into the given SV, upgrading first
2907 if necessary. Does not handle 'set' magic. See also
2908 "sv_setuv_mg".
2909 void sv_setuv(SV* sv, UV num)
2911 sv_setuv_mg
2913 Like "sv_setuv", but also handles 'set' magic.
2914 void sv_setuv_mg(SV *sv, UV u)
2916 sv_taint
2918 Taint an SV. Use "SvTAINTED_on" instead.
2919 void sv_taint(SV* sv)
2920 sv_tainted
2922 Test an SV for taintedness. Use "SvTAINTED" instead.
2923 bool sv_tainted(SV* sv)
2924 sv_true Returns true if the SV has a true value by Perl's rules. Use
2926 the "SvTRUE" macro instead, which may call "sv_true()" or may
2927 instead use an in-line version.
2928 I32 sv_true(SV *sv)
2930 sv_unmagic
2932 Removes all magic of type "type" from an SV.
2933 int sv_unmagic(SV* sv, int type)
2935 sv_unref
2937 Unsets the RV status of the SV, and decrements the reference
2938 count of whatever was being referenced by the RV. This can
2939 almost be thought of as a reversal of "newSVrv". This is
2940 "sv_unref_flags" with the "flag" being zero. See "SvROK_off".
2941 void sv_unref(SV* sv)
2943 sv_unref_flags
2945 Unsets the RV status of the SV, and decrements the reference
2946 count of whatever was being referenced by the RV. This can
2947 almost be thought of as a reversal of "newSVrv". The "cflags"
2948 argument can contain "SV_IMMEDIATE_UNREF" to force the refer‐
2949 ence count to be decremented (otherwise the decrementing is
2950 conditional on the reference count being different from one or
2951 the reference being a readonly SV). See "SvROK_off".
2952 void sv_unref_flags(SV* sv, U32 flags)
2954 sv_untaint
2956 Untaint an SV. Use "SvTAINTED_off" instead.
2957 void sv_untaint(SV* sv)
2958 sv_upgrade
2960 Upgrade an SV to a more complex form. Generally adds a new
2961 body type to the SV, then copies across as much information as
2962 possible from the old body. You generally want to use the
2963 "SvUPGRADE" macro wrapper. See also "svtype".
2964 bool sv_upgrade(SV* sv, U32 mt)
2966 sv_usepvn
2968 Tells an SV to use "ptr" to find its string value. Normally
2969 the string is stored inside the SV but sv_usepvn allows the SV
2970 to use an outside string. The "ptr" should point to memory
2971 that was allocated by "malloc". The string length, "len", must
2972 be supplied. This function will realloc the memory pointed to
2973 by "ptr", so that pointer should not be freed or used by the
2974 programmer after giving it to sv_usepvn. Does not handle 'set'
2975 magic. See "sv_usepvn_mg".
2976 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
2978 sv_usepvn_mg
2980 Like "sv_usepvn", but also handles 'set' magic.
2981 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
2983 sv_utf8_decode
2985 If the PV of the SV is an octet sequence in UTF-8 and contains
2986 a multiple-byte character, the "SvUTF8" flag is turned on so
2987 that it looks like a character. If the PV contains only single-
2988 byte characters, the "SvUTF8" flag stays being off. Scans PV
2989 for validity and returns false if the PV is invalid UTF-8.
2990 NOTE: this function is experimental and may change or be
2992 removed without notice.
2993 bool sv_utf8_decode(SV *sv)
2995 sv_utf8_downgrade
2997 Attempts to convert the PV of an SV from characters to bytes.
2998 If the PV contains a character beyond byte, this conversion
2999 will fail; in this case, either returns false or, if "fail_ok"
3000 is not true, croaks.
3001 This is not as a general purpose Unicode to byte encoding
3003 interface: use the Encode extension for that.
3004 NOTE: this function is experimental and may change or be
3006 removed without notice.
3007 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
3009 sv_utf8_encode
3011 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
3012 flag off so that it looks like octets again.
3013 void sv_utf8_encode(SV *sv)
3015 sv_utf8_upgrade
3017 Converts the PV of an SV to its UTF-8-encoded form. Forces the
3018 SV to string form if it is not already. Always sets the SvUTF8
3019 flag to avoid future validity checks even if all the bytes have
3020 hibit clear.
3021 This is not as a general purpose byte encoding to Unicode
3023 interface: use the Encode extension for that.
3024 STRLEN sv_utf8_upgrade(SV *sv)
3026 sv_utf8_upgrade_flags
3028 Converts the PV of an SV to its UTF-8-encoded form. Forces the
3029 SV to string form if it is not already. Always sets the SvUTF8
3030 flag to avoid future validity checks even if all the bytes have
3031 hibit clear. If "flags" has "SV_GMAGIC" bit set, will "mg_get"
3032 on "sv" if appropriate, else not. "sv_utf8_upgrade" and
3033 "sv_utf8_upgrade_nomg" are implemented in terms of this func‐
3034 tion.
3035 This is not as a general purpose byte encoding to Unicode
3037 interface: use the Encode extension for that.
3038 STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
3040 sv_uv A private implementation of the "SvUVx" macro for compilers
3042 which can't cope with complex macro expressions. Always use the
3043 macro instead.
3044 UV sv_uv(SV* sv)
3046 sv_vcatpvf
3048 Processes its arguments like "vsprintf" and appends the format‐
3049 ted output to an SV. Does not handle 'set' magic. See
3050 "sv_vcatpvf_mg".
3051 Usually used via its frontend "sv_catpvf".
3053 void sv_vcatpvf(SV* sv, const char* pat, va_list* args)
3055 sv_vcatpvfn
3057 Processes its arguments like "vsprintf" and appends the format‐
3058 ted output to an SV. Uses an array of SVs if the C style vari‐
3059 able argument list is missing (NULL). When running with taint
3060 checks enabled, indicates via "maybe_tainted" if results are
3061 untrustworthy (often due to the use of locales).
3062 XXX Except that it maybe_tainted is never assigned to.
3064 Usually used via one of its frontends "sv_vcatpvf" and
3066 "sv_vcatpvf_mg".
3067 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3069 sv_vcatpvf_mg
3071 Like "sv_vcatpvf", but also handles 'set' magic.
3072 Usually used via its frontend "sv_catpvf_mg".
3074 void sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
3076 sv_vsetpvf
3078 Works like "sv_vcatpvf" but copies the text into the SV instead
3079 of appending it. Does not handle 'set' magic. See "sv_vset‐
3080 pvf_mg".
3081 Usually used via its frontend "sv_setpvf".
3083 void sv_vsetpvf(SV* sv, const char* pat, va_list* args)
3085 sv_vsetpvfn
3087 Works like "sv_vcatpvfn" but copies the text into the SV
3088 instead of appending it.
3089 Usually used via one of its frontends "sv_vsetpvf" and
3091 "sv_vsetpvf_mg".
3092 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3094 sv_vsetpvf_mg
3096 Like "sv_vsetpvf", but also handles 'set' magic.
3097 Usually used via its frontend "sv_setpvf_mg".
3099 void sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
3101
3103 bytes_from_utf8
3104 Converts a string "s" of length "len" from UTF-8 into byte
3105 encoding. Unlike "utf8_to_bytes" but like "bytes_to_utf8",
3106 returns a pointer to the newly-created string, and updates
3107 "len" to contain the new length. Returns the original string
3108 if no conversion occurs, "len" is unchanged. Do nothing if
3109 "is_utf8" points to 0. Sets "is_utf8" to 0 if "s" is converted
3110 or contains all 7bit characters.
3111 NOTE: this function is experimental and may change or be
3113 removed without notice.
3114 U8* bytes_from_utf8(U8 *s, STRLEN *len, bool *is_utf8)
3116 bytes_to_utf8
3118 Converts a string "s" of length "len" from ASCII into UTF-8
3119 encoding. Returns a pointer to the newly-created string, and
3120 sets "len" to reflect the new length.
3121 If you want to convert to UTF-8 from other encodings than
3123 ASCII, see sv_recode_to_utf8().
3124 NOTE: this function is experimental and may change or be
3126 removed without notice.
3127 U8* bytes_to_utf8(U8 *s, STRLEN *len)
3129 ibcmp_utf8
3131 Return true if the strings s1 and s2 differ case-insensitively,
3132 false if not (if they are equal case-insensitively). If u1 is
3133 true, the string s1 is assumed to be in UTF-8-encoded Unicode.
3134 If u2 is true, the string s2 is assumed to be in UTF-8-encoded
3135 Unicode. If u1 or u2 are false, the respective string is
3136 assumed to be in native 8-bit encoding.
3137 If the pe1 and pe2 are non-NULL, the scanning pointers will be
3139 copied in there (they will point at the beginning of the next
3140 character). If the pointers behind pe1 or pe2 are non-NULL,
3141 they are the end pointers beyond which scanning will not con‐
3142 tinue under any circumstances. If the byte lengths l1 and l2
3143 are non-zero, s1+l1 and s2+l2 will be used as goal end pointers
3144 that will also stop the scan, and which qualify towards defin‐
3145 ing a successful match: all the scans that define an explicit
3146 length must reach their goal pointers for a match to succeed).
3147 For case-insensitiveness, the "casefolding" of Unicode is used
3149 instead of upper/lowercasing both the characters, see
3150 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
3151 I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
3153 is_utf8_char
3155 Tests if some arbitrary number of bytes begins in a valid UTF-8
3156 character. Note that an INVARIANT (i.e. ASCII) character is a
3157 valid UTF-8 character. The actual number of bytes in the UTF-8
3158 character will be returned if it is valid, otherwise 0.
3159 STRLEN is_utf8_char(U8 *p)
3161 is_utf8_string
3163 Returns true if first "len" bytes of the given string form a
3164 valid UTF-8 string, false otherwise. Note that 'a valid UTF-8
3165 string' does not mean 'a string that contains code points above
3166 0x7F encoded in UTF-8' because a valid ASCII string is a valid
3167 UTF-8 string.
3168 See also is_utf8_string_loclen() and is_utf8_string_loc().
3170 bool is_utf8_string(U8 *s, STRLEN len)
3172 is_utf8_string_loc
3174 Like is_utf8_string() but stores the location of the failure
3175 (in the case of "utf8ness failure") or the location s+len (in
3176 the case of "utf8ness success") in the "ep".
3177 See also is_utf8_string_loclen() and is_utf8_string().
3179 bool is_utf8_string_loc(U8 *s, STRLEN len, U8 **p)
3181 is_utf8_string_loclen
3183 Like is_utf8_string() but stores the location of the failure
3184 (in the case of "utf8ness failure") or the location s+len (in
3185 the case of "utf8ness success") in the "ep", and the number of
3186 UTF-8 encoded characters in the "el".
3187 See also is_utf8_string_loc() and is_utf8_string().
3189 bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
3191 pv_uni_display
3193 Build to the scalar dsv a displayable version of the string
3194 spv, length len, the displayable version being at most pvlim
3195 bytes long (if longer, the rest is truncated and "..." will be
3196 appended).
3197 The flags argument can have UNI_DISPLAY_ISPRINT set to display
3199 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
3200 to display the \\[nrfta\\] as the backslashed versions (like
3201 '\n') (UNI_DISPLAY_BACKSLASH is preferred over UNI_DIS‐
3202 PLAY_ISPRINT for \\). UNI_DISPLAY_QQ (and its alias UNI_DIS‐
3203 PLAY_REGEX) have both UNI_DISPLAY_BACKSLASH and UNI_DIS‐
3204 PLAY_ISPRINT turned on.
3205 The pointer to the PV of the dsv is returned.
3207 char* pv_uni_display(SV *dsv, U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
3209 sv_cat_decode
3211 The encoding is assumed to be an Encode object, the PV of the
3212 ssv is assumed to be octets in that encoding and decoding the
3213 input starts from the position which (PV + *offset) pointed to.
3214 The dsv will be concatenated the decoded UTF-8 string from ssv.
3215 Decoding will terminate when the string tstr appears in decod‐
3216 ing output or the input ends on the PV of the ssv. The value
3217 which the offset points will be modified to the last input
3218 position on the ssv.
3219 Returns TRUE if the terminator was found, else returns FALSE.
3221 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
3223 sv_recode_to_utf8
3225 The encoding is assumed to be an Encode object, on entry the PV
3226 of the sv is assumed to be octets in that encoding, and the sv
3227 will be converted into Unicode (and UTF-8).
3228 If the sv already is UTF-8 (or if it is not POK), or if the
3230 encoding is not a reference, nothing is done to the sv. If the
3231 encoding is not an "Encode::XS" Encoding object, bad things
3232 will happen. (See lib/encoding.pm and Encode).
3233 The PV of the sv is returned.
3235 char* sv_recode_to_utf8(SV* sv, SV *encoding)
3237 sv_uni_display
3239 Build to the scalar dsv a displayable version of the scalar sv,
3240 the displayable version being at most pvlim bytes long (if
3241 longer, the rest is truncated and "..." will be appended).
3242 The flags argument is as in pv_uni_display().
3244 The pointer to the PV of the dsv is returned.
3246 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
3248 to_utf8_case
3250 The "p" contains the pointer to the UTF-8 string encoding the
3251 character that is being converted.
3252 The "ustrp" is a pointer to the character buffer to put the
3254 conversion result to. The "lenp" is a pointer to the length of
3255 the result.
3256 The "swashp" is a pointer to the swash to use.
3258 Both the special and normal mappings are stored lib/uni‐
3260 core/To/Foo.pl, and loaded by SWASHGET, using
3261 lib/utf8_heavy.pl. The special (usually, but not always, a
3262 multicharacter mapping), is tried first.
3263 The "special" is a string like "utf8::ToSpecLower", which means
3265 the hash %utf8::ToSpecLower. The access to the hash is through
3266 Perl_to_utf8_case().
3267 The "normal" is a string like "ToLower" which means the swash
3269 %utf8::ToLower.
3270 UV to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, char *normal, char *special)
3272 to_utf8_fold
3274 Convert the UTF-8 encoded character at p to its foldcase ver‐
3275 sion and store that in UTF-8 in ustrp and its length in bytes
3276 in lenp. Note that the ustrp needs to be at least
3277 UTF8_MAXBYTES_CASE+1 bytes since the foldcase version may be
3278 longer than the original character (up to three characters).
3279 The first character of the foldcased version is returned (but
3281 note, as explained above, that there may be more.)
3282 UV to_utf8_fold(U8 *p, U8* ustrp, STRLEN *lenp)
3284 to_utf8_lower
3286 Convert the UTF-8 encoded character at p to its lowercase ver‐
3287 sion and store that in UTF-8 in ustrp and its length in bytes
3288 in lenp. Note that the ustrp needs to be at least
3289 UTF8_MAXBYTES_CASE+1 bytes since the lowercase version may be
3290 longer than the original character.
3291 The first character of the lowercased version is returned (but
3293 note, as explained above, that there may be more.)
3294 UV to_utf8_lower(U8 *p, U8* ustrp, STRLEN *lenp)
3296 to_utf8_title
3298 Convert the UTF-8 encoded character at p to its titlecase ver‐
3299 sion and store that in UTF-8 in ustrp and its length in bytes
3300 in lenp. Note that the ustrp needs to be at least
3301 UTF8_MAXBYTES_CASE+1 bytes since the titlecase version may be
3302 longer than the original character.
3303 The first character of the titlecased version is returned (but
3305 note, as explained above, that there may be more.)
3306 UV to_utf8_title(U8 *p, U8* ustrp, STRLEN *lenp)
3308 to_utf8_upper
3310 Convert the UTF-8 encoded character at p to its uppercase ver‐
3311 sion and store that in UTF-8 in ustrp and its length in bytes
3312 in lenp. Note that the ustrp needs to be at least
3313 UTF8_MAXBYTES_CASE+1 bytes since the uppercase version may be
3314 longer than the original character.
3315 The first character of the uppercased version is returned (but
3317 note, as explained above, that there may be more.)
3318 UV to_utf8_upper(U8 *p, U8* ustrp, STRLEN *lenp)
3320 utf8n_to_uvchr
3322 Returns the native character value of the first character in
3323 the string "s" which is assumed to be in UTF-8 encoding;
3324 "retlen" will be set to the length, in bytes, of that charac‐
3325 ter.
3326 Allows length and flags to be passed to low level routine.
3328 UV utf8n_to_uvchr(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
3330 utf8n_to_uvuni
3332 Bottom level UTF-8 decode routine. Returns the unicode code
3333 point value of the first character in the string "s" which is
3334 assumed to be in UTF-8 encoding and no longer than "curlen";
3335 "retlen" will be set to the length, in bytes, of that charac‐
3336 ter.
3337 If "s" does not point to a well-formed UTF-8 character, the be‐
3339 haviour is dependent on the value of "flags": if it contains
3340 UTF8_CHECK_ONLY, it is assumed that the caller will raise a
3341 warning, and this function will silently just set "retlen" to
3342 "-1" and return zero. If the "flags" does not contain
3343 UTF8_CHECK_ONLY, warnings about malformations will be given,
3344 "retlen" will be set to the expected length of the UTF-8 char‐
3345 acter in bytes, and zero will be returned.
3346 The "flags" can also contain various flags to allow deviations
3348 from the strict UTF-8 encoding (see utf8.h).
3349 Most code should use utf8_to_uvchr() rather than call this
3351 directly.
3352 UV utf8n_to_uvuni(U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
3354 utf8_distance
3356 Returns the number of UTF-8 characters between the UTF-8 point‐
3357 ers "a" and "b".
3358 WARNING: use only if you *know* that the pointers point inside
3360 the same UTF-8 buffer.
3361 IV utf8_distance(U8 *a, U8 *b)
3363 utf8_hop
3365 Return the UTF-8 pointer "s" displaced by "off" characters,
3366 either forward or backward.
3367 WARNING: do not use the following unless you *know* "off" is
3369 within the UTF-8 data pointed to by "s" *and* that on entry "s"
3370 is aligned on the first byte of character or just after the
3371 last byte of a character.
3372 U8* utf8_hop(U8 *s, I32 off)
3374 utf8_length
3376 Return the length of the UTF-8 char encoded string "s" in char‐
3377 acters. Stops at "e" (inclusive). If "e < s" or if the scan
3378 would end up past "e", croaks.
3379 STRLEN utf8_length(U8* s, U8 *e)
3381 utf8_to_bytes
3383 Converts a string "s" of length "len" from UTF-8 into byte
3384 encoding. Unlike "bytes_to_utf8", this over-writes the origi‐
3385 nal string, and updates len to contain the new length. Returns
3386 zero on failure, setting "len" to -1.
3387 NOTE: this function is experimental and may change or be
3389 removed without notice.
3390 U8* utf8_to_bytes(U8 *s, STRLEN *len)
3392 utf8_to_uvchr
3394 Returns the native character value of the first character in
3395 the string "s" which is assumed to be in UTF-8 encoding;
3396 "retlen" will be set to the length, in bytes, of that charac‐
3397 ter.
3398 If "s" does not point to a well-formed UTF-8 character, zero is
3400 returned and retlen is set, if possible, to -1.
3401 UV utf8_to_uvchr(U8 *s, STRLEN *retlen)
3403 utf8_to_uvuni
3405 Returns the Unicode code point of the first character in the
3406 string "s" which is assumed to be in UTF-8 encoding; "retlen"
3407 will be set to the length, in bytes, of that character.
3408 This function should only be used when returned UV is consid‐
3410 ered an index into the Unicode semantic tables (e.g. swashes).
3411 If "s" does not point to a well-formed UTF-8 character, zero is
3413 returned and retlen is set, if possible, to -1.
3414 UV utf8_to_uvuni(U8 *s, STRLEN *retlen)
3416 uvchr_to_utf8
3418 Adds the UTF-8 representation of the Native codepoint "uv" to
3419 the end of the string "d"; "d" should be have at least
3420 "UTF8_MAXBYTES+1" free bytes available. The return value is the
3421 pointer to the byte after the end of the new character. In
3422 other words,
3423 d = uvchr_to_utf8(d, uv);
3425 is the recommended wide native character-aware way of saying
3427 *(d++) = uv;
3429 U8* uvchr_to_utf8(U8 *d, UV uv)
3431 uvuni_to_utf8_flags
3433 Adds the UTF-8 representation of the Unicode codepoint "uv" to
3434 the end of the string "d"; "d" should be have at least
3435 "UTF8_MAXBYTES+1" free bytes available. The return value is the
3436 pointer to the byte after the end of the new character. In
3437 other words,
3438 d = uvuni_to_utf8_flags(d, uv, flags);
3440 or, in most cases,
3442 d = uvuni_to_utf8(d, uv);
3444 (which is equivalent to)
3446 d = uvuni_to_utf8_flags(d, uv, 0);
3448 is the recommended Unicode-aware way of saying
3450 *(d++) = uv;
3452 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
3454
3456 ax Variable which is setup by "xsubpp" to indicate the stack base
3457 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
3458 The "dMARK" macro must be called prior to setup the "MARK"
3459 variable.
3460 I32 ax
3462 CLASS Variable which is setup by "xsubpp" to indicate the class name
3464 for a C++ XS constructor. This is always a "char*". See
3465 "THIS".
3466 char* CLASS
3468 dAX Sets up the "ax" variable. This is usually handled automati‐
3470 cally by "xsubpp" by calling "dXSARGS".
3471 dAX;
3473 dAXMARK Sets up the "ax" variable and stack marker variable "mark".
3475 This is usually handled automatically by "xsubpp" by calling
3476 "dXSARGS".
3477 dAXMARK;
3479 dITEMS Sets up the "items" variable. This is usually handled automat‐
3481 ically by "xsubpp" by calling "dXSARGS".
3482 dITEMS;
3484 dXSARGS Sets up stack and mark pointers for an XSUB, calling dSP and
3486 dMARK. Sets up the "ax" and "items" variables by calling "dAX"
3487 and "dITEMS". This is usually handled automatically by
3488 "xsubpp".
3489 dXSARGS;
3491 dXSI32 Sets up the "ix" variable for an XSUB which has aliases. This
3493 is usually handled automatically by "xsubpp".
3494 dXSI32;
3496 items Variable which is setup by "xsubpp" to indicate the number of
3498 items on the stack. See "Variable-length Parameter Lists" in
3499 perlxs.
3500 I32 items
3502 ix Variable which is setup by "xsubpp" to indicate which of an
3504 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword"
3505 in perlxs.
3506 I32 ix
3508 newXSproto
3510 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl pro‐
3511 totypes to the subs.
3512 RETVAL Variable which is setup by "xsubpp" to hold the return value
3514 for an XSUB. This is always the proper type for the XSUB. See
3515 "The RETVAL Variable" in perlxs.
3516 (whatever) RETVAL
3518 ST Used to access elements on the XSUB's stack.
3520 SV* ST(int ix)
3522 THIS Variable which is setup by "xsubpp" to designate the object in
3524 a C++ XSUB. This is always the proper type for the C++ object.
3525 See "CLASS" and "Using XS With C++" in perlxs.
3526 (whatever) THIS
3528 XS Macro to declare an XSUB and its C parameter list. This is
3530 handled by "xsubpp".
3531 XS_VERSION
3533 The version identifier for an XS module. This is usually han‐
3534 dled automatically by "ExtUtils::MakeMaker". See "XS_VER‐
3535 SION_BOOTCHECK".
3536 XS_VERSION_BOOTCHECK
3538 Macro to verify that a PM module's $VERSION variable matches
3539 the XS module's "XS_VERSION" variable. This is usually handled
3540 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
3541 perlxs.
3542 XS_VERSION_BOOTCHECK;
3544
3546 croak This is the XSUB-writer's interface to Perl's "die" function.
3547 Normally call this function the same way you call the C
3548 "printf" function. Calling "croak" returns control directly to
3549 Perl, sidestepping the normal C order of execution. See "warn".
3550 If you want to throw an exception object, assign the object to
3552 $@ and then pass "Nullch" to croak():
3553 errsv = get_sv("@", TRUE);
3555 sv_setsv(errsv, exception_object);
3556 croak(Nullch);
3557 void croak(const char* pat, ...)
3559 warn This is the XSUB-writer's interface to Perl's "warn" function.
3561 Call this function the same way you call the C "printf" func‐
3562 tion. See "croak".
3563 void warn(const char* pat, ...)
3565
3567 Until May 1997, this document was maintained by Jeff Okamoto
3568 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
3569 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
3571 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil Bow‐
3572 ers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer, Stephen
3573 McCamant, and Gurusamy Sarathy.
3574 API Listing originally by Dean Roehrich <roehrich@cray.com>.
3576 Updated to be autogenerated from comments in the source by Benjamin
3578 Stuhl.
3579
3581 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
3582perl v5.8.8 2006-01-07 PERLAPI(1)