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 Perl was originally written to handle US-ASCII only (that is characters
22 whose ordinal numbers are in the range 0 - 127). And documentation and
23 comments may still use the term ASCII, when sometimes in fact the
24 entire range from 0 - 255 is meant.
25 Note that Perl can be compiled and run under EBCDIC (See perlebcdic) or
27 ASCII. Most of the documentation (and even comments in the code)
28 ignore the EBCDIC possibility. For almost all purposes the differences
29 are transparent. As an example, under EBCDIC, instead of UTF-8, UTF-
30 EBCDIC is used to encode Unicode strings, and so whenever this
31 documentation refers to "utf8" (and variants of that name, including in
32 function names), it also (essentially transparently) means
33 "UTF-EBCDIC". But the ordinals of characters differ between ASCII,
34 EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
35 occupy more bytes than in UTF-8.
36 Also, on some EBCDIC machines, functions that are documented as
38 operating on US-ASCII (or Basic Latin in Unicode terminology) may in
39 fact operate on all 256 characters in the EBCDIC range, not just the
40 subset corresponding to US-ASCII.
41 The listing below is alphabetical, case insensitive.
43
45 GIMME A backward-compatible version of "GIMME_V" which can only
46 return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
47 "G_SCALAR". Deprecated. Use "GIMME_V" instead.
48 U32 GIMME
50 GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns
52 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list
53 context, respectively.
54 U32 GIMME_V
56 G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and
58 perlcall.
59 G_DISCARD
61 Indicates that arguments returned from a callback should be
62 discarded. See perlcall.
63 G_EVAL Used to force a Perl "eval" wrapper around a callback. See
65 perlcall.
66 G_NOARGS
68 Indicates that no arguments are being sent to a callback. See
69 perlcall.
70 G_SCALAR
72 Used to indicate scalar context. See "GIMME_V", "GIMME", and
73 perlcall.
74 G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
76
78 AvFILL Same as "av_len()". Deprecated, use "av_len()" instead.
79 int AvFILL(AV* av)
81 av_clear
83 Clears an array, making it empty. Does not free the memory
84 used by the array itself.
85 void av_clear(AV *av)
87 av_create_and_push
89 Push an SV onto the end of the array, creating the array if
90 necessary. A small internal helper function to remove a
91 commonly duplicated idiom.
92 NOTE: this function is experimental and may change or be
94 removed without notice.
95 void av_create_and_push(AV **const avp, SV *const val)
97 av_create_and_unshift_one
99 Unshifts an SV onto the beginning of the array, creating the
100 array if necessary. A small internal helper function to remove
101 a commonly duplicated idiom.
102 NOTE: this function is experimental and may change or be
104 removed without notice.
105 SV** av_create_and_unshift_one(AV **const avp, SV *const val)
107 av_delete
109 Deletes the element indexed by "key" from the array. Returns
110 the deleted element. If "flags" equals "G_DISCARD", the element
111 is freed and null is returned.
112 SV* av_delete(AV *av, I32 key, I32 flags)
114 av_exists
116 Returns true if the element indexed by "key" has been
117 initialized.
118 This relies on the fact that uninitialized array elements are
120 set to &PL_sv_undef.
121 bool av_exists(AV *av, I32 key)
123 av_extend
125 Pre-extend an array. The "key" is the index to which the array
126 should be extended.
127 void av_extend(AV *av, I32 key)
129 av_fetch
131 Returns the SV at the specified index in the array. The "key"
132 is the index. If "lval" is set then the fetch will be part of
133 a store. Check that the return value is non-null before
134 dereferencing it to a "SV*".
135 See "Understanding the Magic of Tied Hashes and Arrays" in
137 perlguts for more information on how to use this function on
138 tied arrays.
139 SV** av_fetch(AV *av, I32 key, I32 lval)
141 av_fill Set the highest index in the array to the given number,
143 equivalent to Perl's "$#array = $fill;".
144 The number of elements in the an array will be "fill + 1" after
146 av_fill() returns. If the array was previously shorter then
147 the additional elements appended are set to "PL_sv_undef". If
148 the array was longer, then the excess elements are freed.
149 "av_fill(av, -1)" is the same as "av_clear(av)".
150 void av_fill(AV *av, I32 fill)
152 av_len Returns the highest index in the array. The number of elements
154 in the array is "av_len(av) + 1". Returns -1 if the array is
155 empty.
156 I32 av_len(const AV *av)
158 av_make Creates a new AV and populates it with a list of SVs. The SVs
160 are copied into the array, so they may be freed after the call
161 to av_make. The new AV will have a reference count of 1.
162 AV* av_make(I32 size, SV **strp)
164 av_pop Pops an SV off the end of the array. Returns &PL_sv_undef if
166 the array is empty.
167 SV* av_pop(AV *av)
169 av_push Pushes an SV onto the end of the array. The array will grow
171 automatically to accommodate the addition. Like "av_store",
172 this takes ownership of one reference count.
173 void av_push(AV *av, SV *val)
175 av_shift
177 Shifts an SV off the beginning of the array. Returns
178 &PL_sv_undef if the array is empty.
179 SV* av_shift(AV *av)
181 av_store
183 Stores an SV in an array. The array index is specified as
184 "key". The return value will be NULL if the operation failed
185 or if the value did not need to be actually stored within the
186 array (as in the case of tied arrays). Otherwise it can be
187 dereferenced to get the original "SV*". Note that the caller
188 is responsible for suitably incrementing the reference count of
189 "val" before the call, and decrementing it if the function
190 returned NULL.
191 See "Understanding the Magic of Tied Hashes and Arrays" in
193 perlguts for more information on how to use this function on
194 tied arrays.
195 SV** av_store(AV *av, I32 key, SV *val)
197 av_undef
199 Undefines the array. Frees the memory used by the array
200 itself.
201 void av_undef(AV *av)
203 av_unshift
205 Unshift the given number of "undef" values onto the beginning
206 of the array. The array will grow automatically to accommodate
207 the addition. You must then use "av_store" to assign values to
208 these new elements.
209 void av_unshift(AV *av, I32 num)
211 get_av Returns the AV of the specified Perl array. "flags" are passed
213 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
214 not exist then it will be created. If "flags" is zero and the
215 variable does not exist then NULL is returned.
216 NOTE: the perl_ form of this function is deprecated.
218 AV* get_av(const char *name, I32 flags)
220 newAV Creates a new AV. The reference count is set to 1.
222 AV* newAV()
224 sortsv Sort an array. Here is an example:
226 sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
228 Currently this always uses mergesort. See sortsv_flags for a
230 more flexible routine.
231 void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
233 sortsv_flags
235 Sort an array, with various options.
236 void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
238
240 call_argv
241 Performs a callback to the specified Perl sub. See perlcall.
242 NOTE: the perl_ form of this function is deprecated.
244 I32 call_argv(const char* sub_name, I32 flags, char** argv)
246 call_method
248 Performs a callback to the specified Perl method. The blessed
249 object must be on the stack. See perlcall.
250 NOTE: the perl_ form of this function is deprecated.
252 I32 call_method(const char* methname, I32 flags)
254 call_pv Performs a callback to the specified Perl sub. See perlcall.
256 NOTE: the perl_ form of this function is deprecated.
258 I32 call_pv(const char* sub_name, I32 flags)
260 call_sv Performs a callback to the Perl sub whose name is in the SV.
262 See perlcall.
263 NOTE: the perl_ form of this function is deprecated.
265 I32 call_sv(SV* sv, VOL I32 flags)
267 ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
269 ENTER;
271 eval_pv Tells Perl to "eval" the given string and return an SV* result.
273 NOTE: the perl_ form of this function is deprecated.
275 SV* eval_pv(const char* p, I32 croak_on_error)
277 eval_sv Tells Perl to "eval" the string in the SV.
279 NOTE: the perl_ form of this function is deprecated.
281 I32 eval_sv(SV* sv, I32 flags)
283 FREETMPS
285 Closing bracket for temporaries on a callback. See "SAVETMPS"
286 and perlcall.
287 FREETMPS;
289 LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
291 LEAVE;
293 SAVETMPS
295 Opening bracket for temporaries on a callback. See "FREETMPS"
296 and perlcall.
297 SAVETMPS;
299
301 isALNUM Returns a boolean indicating whether the C "char" is a US-ASCII
302 (Basic Latin) alphanumeric character (including underscore) or
303 digit.
304 bool isALNUM(char ch)
306 isALPHA Returns a boolean indicating whether the C "char" is a US-ASCII
308 (Basic Latin) alphabetic character.
309 bool isALPHA(char ch)
311 isDIGIT Returns a boolean indicating whether the C "char" is a US-ASCII
313 (Basic Latin) digit.
314 bool isDIGIT(char ch)
316 isLOWER Returns a boolean indicating whether the C "char" is a US-ASCII
318 (Basic Latin) lowercase character.
319 bool isLOWER(char ch)
321 isSPACE Returns a boolean indicating whether the C "char" is a US-ASCII
323 (Basic Latin) whitespace.
324 bool isSPACE(char ch)
326 isUPPER Returns a boolean indicating whether the C "char" is a US-ASCII
328 (Basic Latin) uppercase character.
329 bool isUPPER(char ch)
331 toLOWER Converts the specified character to lowercase. Characters
333 outside the US-ASCII (Basic Latin) range are viewed as not
334 having any case.
335 char toLOWER(char ch)
337 toUPPER Converts the specified character to uppercase. Characters
339 outside the US-ASCII (Basic Latin) range are viewed as not
340 having any case.
341 char toUPPER(char ch)
343
345 perl_clone
346 Create and return a new interpreter by cloning the current one.
347 perl_clone takes these flags as parameters:
349 CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
351 without it we only clone the data and zero the stacks, with it
352 we copy the stacks and the new perl interpreter is ready to run
353 at the exact same point as the previous one. The pseudo-fork
354 code uses COPY_STACKS while the threads->create doesn't.
355 CLONEf_KEEP_PTR_TABLE perl_clone keeps a ptr_table with the
357 pointer of the old variable as a key and the new variable as a
358 value, this allows it to check if something has been cloned and
359 not clone it again but rather just use the value and increase
360 the refcount. If KEEP_PTR_TABLE is not set then perl_clone will
361 kill the ptr_table using the function
362 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;", reason to
363 keep it around is if you want to dup some of your own variable
364 who are outside the graph perl scans, example of this code is
365 in threads.xs create
366 CLONEf_CLONE_HOST This is a win32 thing, it is ignored on unix,
368 it tells perls win32host code (which is c++) to clone itself,
369 this is needed on win32 if you want to run two threads at the
370 same time, if you just want to do some stuff in a separate perl
371 interpreter and then throw it away and return to the original
372 one, you don't need to do anything.
373 PerlInterpreter* perl_clone(PerlInterpreter *proto_perl, UV flags)
375
377 CvSTASH Returns the stash of the CV.
378 HV* CvSTASH(CV* cv)
380 get_cv Uses "strlen" to get the length of "name", then calls
382 "get_cvn_flags".
383 NOTE: the perl_ form of this function is deprecated.
385 CV* get_cv(const char* name, I32 flags)
387 get_cvn_flags
389 Returns the CV of the specified Perl subroutine. "flags" are
390 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
391 subroutine does not exist then it will be declared (which has
392 the same effect as saying "sub name;"). If "GV_ADD" is not set
393 and the subroutine does not exist then NULL is returned.
394 NOTE: the perl_ form of this function is deprecated.
396 CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
398
400 cv_undef
401 Clear out all the active components of a CV. This can happen
402 either by an explicit "undef &foo", or by the reference count
403 going to zero. In the former case, we keep the CvOUTSIDE
404 pointer, so that any anonymous children can still follow the
405 full lexical scope chain.
406 void cv_undef(CV* cv)
408 load_module
410 Loads the module whose name is pointed to by the string part of
411 name. Note that the actual module name, not its filename,
412 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm".
413 flags can be any of PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT,
414 or PERL_LOADMOD_IMPORT_OPS (or 0 for no flags). ver, if
415 specified, provides version semantics similar to "use Foo::Bar
416 VERSION". The optional trailing SV* arguments can be used to
417 specify arguments to the module's import() method, similar to
418 "use Foo::Bar VERSION LIST". They must be terminated with a
419 final NULL pointer. Note that this list can only be omitted
420 when the PERL_LOADMOD_NOIMPORT flag has been used. Otherwise
421 at least a single NULL pointer to designate the default import
422 list is required.
423 void load_module(U32 flags, SV* name, SV* ver, ...)
425 nothreadhook
427 Stub that provides thread hook for perl_destruct when there are
428 no threads.
429 int nothreadhook()
431 perl_alloc
433 Allocates a new Perl interpreter. See perlembed.
434 PerlInterpreter* perl_alloc()
436 perl_construct
438 Initializes a new Perl interpreter. See perlembed.
439 void perl_construct(PerlInterpreter *my_perl)
441 perl_destruct
443 Shuts down a Perl interpreter. See perlembed.
444 int perl_destruct(PerlInterpreter *my_perl)
446 perl_free
448 Releases a Perl interpreter. See perlembed.
449 void perl_free(PerlInterpreter *my_perl)
451 perl_parse
453 Tells a Perl interpreter to parse a Perl script. See
454 perlembed.
455 int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit, int argc, char** argv, char** env)
457 perl_run
459 Tells a Perl interpreter to run. See perlembed.
460 int perl_run(PerlInterpreter *my_perl)
462 require_pv
464 Tells Perl to "require" the file named by the string argument.
465 It is analogous to the Perl code "eval "require '$file'"".
466 It's even implemented that way; consider using load_module
467 instead.
468 NOTE: the perl_ form of this function is deprecated.
470 void require_pv(const char* pv)
472
474 pv_display
475 Similar to
476 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
478 except that an additional "\0" will be appended to the string
480 when len > cur and pv[cur] is "\0".
481 Note that the final string may be up to 7 chars longer than
483 pvlim.
484 char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
486 pv_escape
488 Escapes at most the first "count" chars of pv and puts the
489 results into dsv such that the size of the escaped string will
490 not exceed "max" chars and will not contain any incomplete
491 escape sequences.
492 If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes
494 in the string will also be escaped.
495 Normally the SV will be cleared before the escaped string is
497 prepared, but when PERL_PV_ESCAPE_NOCLEAR is set this will not
498 occur.
499 If PERL_PV_ESCAPE_UNI is set then the input string is treated
501 as Unicode, if PERL_PV_ESCAPE_UNI_DETECT is set then the input
502 string is scanned using "is_utf8_string()" to determine if it
503 is Unicode.
504 If PERL_PV_ESCAPE_ALL is set then all input chars will be
506 output using "\x01F1" style escapes, otherwise only chars above
507 255 will be escaped using this style, other non printable chars
508 will use octal or common escaped patterns like "\n". If
509 PERL_PV_ESCAPE_NOBACKSLASH then all chars below 255 will be
510 treated as printable and will be output as literals.
511 If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of
513 the string will be escaped, regardles of max. If the string is
514 utf8 and the chars value is >255 then it will be returned as a
515 plain hex sequence. Thus the output will either be a single
516 char, an octal escape sequence, a special escape like "\n" or a
517 3 or more digit hex value.
518 If PERL_PV_ESCAPE_RE is set then the escape char used will be a
520 '%' and not a '\\'. This is because regexes very often contain
521 backslashed sequences, whereas '%' is not a particularly common
522 character in patterns.
523 Returns a pointer to the escaped text as held by dsv.
525 char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
527 pv_pretty
529 Converts a string into something presentable, handling escaping
530 via pv_escape() and supporting quoting and ellipses.
531 If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
533 double quoted with any double quotes in the string escaped.
534 Otherwise if the PERL_PV_PRETTY_LTGT flag is set then the
535 result be wrapped in angle brackets.
536 If the PERL_PV_PRETTY_ELLIPSES flag is set and not all
538 characters in string were output then an ellipsis "..." will be
539 appended to the string. Note that this happens AFTER it has
540 been quoted.
541 If start_color is non-null then it will be inserted after the
543 opening quote (if there is one) but before the escaped text. If
544 end_color is non-null then it will be inserted after the
545 escaped text but before any quotes or ellipses.
546 Returns a pointer to the prettified text as held by dsv.
548 char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
550
552 gv_fetchmethod
553 See gv_fetchmethod_autoload.
554 GV* gv_fetchmethod(HV* stash, const char* name)
556 pack_cat
558 The engine implementing pack() Perl function. Note: parameters
559 next_in_list and flags are not used. This call should not be
560 used; use packlist instead.
561 void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
563 sv_2pvbyte_nolen
565 Return a pointer to the byte-encoded representation of the SV.
566 May cause the SV to be downgraded from UTF-8 as a side-effect.
567 Usually accessed via the "SvPVbyte_nolen" macro.
569 char* sv_2pvbyte_nolen(SV* sv)
571 sv_2pvutf8_nolen
573 Return a pointer to the UTF-8-encoded representation of the SV.
574 May cause the SV to be upgraded to UTF-8 as a side-effect.
575 Usually accessed via the "SvPVutf8_nolen" macro.
577 char* sv_2pvutf8_nolen(SV* sv)
579 sv_2pv_nolen
581 Like "sv_2pv()", but doesn't return the length too. You should
582 usually use the macro wrapper "SvPV_nolen(sv)" instead.
583 char* sv_2pv_nolen(SV* sv)
584 sv_catpvn_mg
586 Like "sv_catpvn", but also handles 'set' magic.
587 void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
589 sv_catsv_mg
591 Like "sv_catsv", but also handles 'set' magic.
592 void sv_catsv_mg(SV *dsv, SV *ssv)
594 sv_force_normal
596 Undo various types of fakery on an SV: if the PV is a shared
597 string, make a private copy; if we're a ref, stop refing; if
598 we're a glob, downgrade to an xpvmg. See also
599 "sv_force_normal_flags".
600 void sv_force_normal(SV *sv)
602 sv_iv A private implementation of the "SvIVx" macro for compilers
604 which can't cope with complex macro expressions. Always use the
605 macro instead.
606 IV sv_iv(SV* sv)
608 sv_nolocking
610 Dummy routine which "locks" an SV when there is no locking
611 module present. Exists to avoid test for a NULL function
612 pointer and because it could potentially warn under some level
613 of strict-ness.
614 "Superseded" by sv_nosharing().
616 void sv_nolocking(SV *sv)
618 sv_nounlocking
620 Dummy routine which "unlocks" an SV when there is no locking
621 module present. Exists to avoid test for a NULL function
622 pointer and because it could potentially warn under some level
623 of strict-ness.
624 "Superseded" by sv_nosharing().
626 void sv_nounlocking(SV *sv)
628 sv_nv A private implementation of the "SvNVx" macro for compilers
630 which can't cope with complex macro expressions. Always use the
631 macro instead.
632 NV sv_nv(SV* sv)
634 sv_pv Use the "SvPV_nolen" macro instead
636 char* sv_pv(SV *sv)
638 sv_pvbyte
640 Use "SvPVbyte_nolen" instead.
641 char* sv_pvbyte(SV *sv)
643 sv_pvbyten
645 A private implementation of the "SvPVbyte" macro for compilers
646 which can't cope with complex macro expressions. Always use the
647 macro instead.
648 char* sv_pvbyten(SV *sv, STRLEN *lp)
650 sv_pvn A private implementation of the "SvPV" macro for compilers
652 which can't cope with complex macro expressions. Always use the
653 macro instead.
654 char* sv_pvn(SV *sv, STRLEN *lp)
656 sv_pvutf8
658 Use the "SvPVutf8_nolen" macro instead
659 char* sv_pvutf8(SV *sv)
661 sv_pvutf8n
663 A private implementation of the "SvPVutf8" macro for compilers
664 which can't cope with complex macro expressions. Always use the
665 macro instead.
666 char* sv_pvutf8n(SV *sv, STRLEN *lp)
668 sv_taint
670 Taint an SV. Use "SvTAINTED_on" instead.
671 void sv_taint(SV* sv)
672 sv_unref
674 Unsets the RV status of the SV, and decrements the reference
675 count of whatever was being referenced by the RV. This can
676 almost be thought of as a reversal of "newSVrv". This is
677 "sv_unref_flags" with the "flag" being zero. See "SvROK_off".
678 void sv_unref(SV* sv)
680 sv_usepvn
682 Tells an SV to use "ptr" to find its string value. Implemented
683 by calling "sv_usepvn_flags" with "flags" of 0, hence does not
684 handle 'set' magic. See "sv_usepvn_flags".
685 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
687 sv_usepvn_mg
689 Like "sv_usepvn", but also handles 'set' magic.
690 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
692 sv_uv A private implementation of the "SvUVx" macro for compilers
694 which can't cope with complex macro expressions. Always use the
695 macro instead.
696 UV sv_uv(SV* sv)
698 unpack_str
700 The engine implementing unpack() Perl function. Note:
701 parameters strbeg, new_s and ocnt are not used. This call
702 should not be used, use unpackstring instead.
703 I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
705
707 PERL_SYS_INIT
708 Provides system-specific tune up of the C runtime environment
709 necessary to run Perl interpreters. This should be called only
710 once, before creating any Perl interpreters.
711 void PERL_SYS_INIT(int argc, char** argv)
713 PERL_SYS_INIT3
715 Provides system-specific tune up of the C runtime environment
716 necessary to run Perl interpreters. This should be called only
717 once, before creating any Perl interpreters.
718 void PERL_SYS_INIT3(int argc, char** argv, char** env)
720 PERL_SYS_TERM
722 Provides system-specific clean up of the C runtime environment
723 after running Perl interpreters. This should be called only
724 once, after freeing any remaining Perl interpreters.
725 void PERL_SYS_TERM()
727
729 find_runcv
730 Locate the CV corresponding to the currently executing sub or
731 eval. If db_seqp is non_null, skip CVs that are in the DB
732 package and populate *db_seqp with the cop sequence number at
733 the point that the DB:: code was entered. (allows debuggers to
734 eval in the scope of the breakpoint rather than in the scope of
735 the debugger itself).
736 CV* find_runcv(U32 *db_seqp)
738
740 packlist
741 The engine implementing pack() Perl function.
742 void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
744 unpackstring
746 The engine implementing unpack() Perl function. "unpackstring"
747 puts the extracted list items on the stack and returns the
748 number of elements. Issue "PUTBACK" before and "SPAGAIN" after
749 the call to this function.
750 I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
752
754 GvSV Return the SV from the GV.
755 SV* GvSV(GV* gv)
757 gv_const_sv
759 If "gv" is a typeglob whose subroutine entry is a constant sub
760 eligible for inlining, or "gv" is a placeholder reference that
761 would be promoted to such a typeglob, then returns the value
762 returned by the sub. Otherwise, returns NULL.
763 SV* gv_const_sv(GV* gv)
765 gv_fetchmeth
767 Returns the glob with the given "name" and a defined subroutine
768 or "NULL". The glob lives in the given "stash", or in the
769 stashes accessible via @ISA and UNIVERSAL::.
770 The argument "level" should be either 0 or -1. If "level==0",
772 as a side-effect creates a glob with the given "name" in the
773 given "stash" which in the case of success contains an alias
774 for the subroutine, and sets up caching info for this glob.
775 This function grants "SUPER" token as a postfix of the stash
777 name. The GV returned from "gv_fetchmeth" may be a method cache
778 entry, which is not visible to Perl code. So when calling
779 "call_sv", you should not use the GV directly; instead, you
780 should use the method's CV, which can be obtained from the GV
781 with the "GvCV" macro.
782 GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
784 gv_fetchmethod_autoload
786 Returns the glob which contains the subroutine to call to
787 invoke the method on the "stash". In fact in the presence of
788 autoloading this may be the glob for "AUTOLOAD". In this case
789 the corresponding variable $AUTOLOAD is already setup.
790 The third parameter of "gv_fetchmethod_autoload" determines
792 whether AUTOLOAD lookup is performed if the given method is not
793 present: non-zero means yes, look for AUTOLOAD; zero means no,
794 don't look for AUTOLOAD. Calling "gv_fetchmethod" is
795 equivalent to calling "gv_fetchmethod_autoload" with a non-zero
796 "autoload" parameter.
797 These functions grant "SUPER" token as a prefix of the method
799 name. Note that if you want to keep the returned glob for a
800 long time, you need to check for it being "AUTOLOAD", since at
801 the later time the call may load a different subroutine due to
802 $AUTOLOAD changing its value. Use the glob created via a side
803 effect to do this.
804 These functions have the same side-effects and as
806 "gv_fetchmeth" with "level==0". "name" should be writable if
807 contains ':' or ' ''. The warning against passing the GV
808 returned by "gv_fetchmeth" to "call_sv" apply equally to these
809 functions.
810 GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
812 gv_fetchmeth_autoload
814 Same as gv_fetchmeth(), but looks for autoloaded subroutines
815 too. Returns a glob for the subroutine.
816 For an autoloaded subroutine without a GV, will create a GV
818 even if "level < 0". For an autoloaded subroutine without a
819 stub, GvCV() of the result may be zero.
820 GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
822 gv_stashpv
824 Returns a pointer to the stash for a specified package. Uses
825 "strlen" to determine the length of "name", then calls
826 "gv_stashpvn()".
827 HV* gv_stashpv(const char* name, I32 flags)
829 gv_stashpvn
831 Returns a pointer to the stash for a specified package. The
832 "namelen" parameter indicates the length of the "name", in
833 bytes. "flags" is passed to "gv_fetchpvn_flags()", so if set
834 to "GV_ADD" then the package will be created if it does not
835 already exist. If the package does not exist and "flags" is 0
836 (or any other setting that does not create packages) then NULL
837 is returned.
838 HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
840 gv_stashpvs
842 Like "gv_stashpvn", but takes a literal string instead of a
843 string/length pair.
844 HV* gv_stashpvs(const char* name, I32 create)
846 gv_stashsv
848 Returns a pointer to the stash for a specified package. See
849 "gv_stashpvn".
850 HV* gv_stashsv(SV* sv, I32 flags)
852
854 Nullav Null AV pointer.
855 Nullch Null character pointer.
857 Nullcv Null CV pointer.
859 Nullhv Null HV pointer.
861 Nullsv Null SV pointer.
863
865 get_hv Returns the HV of the specified Perl hash. "flags" are passed
866 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
867 not exist then it will be created. If "flags" is zero and the
868 variable does not exist then NULL is returned.
869 NOTE: the perl_ form of this function is deprecated.
871 HV* get_hv(const char *name, I32 flags)
873 HEf_SVKEY
875 This flag, used in the length slot of hash entries and magic
876 structures, specifies the structure contains an "SV*" pointer
877 where a "char*" pointer is to be expected. (For information
878 only--not to be used).
879 HeHASH Returns the computed hash stored in the hash entry.
881 U32 HeHASH(HE* he)
883 HeKEY Returns the actual pointer stored in the key slot of the hash
885 entry. The pointer may be either "char*" or "SV*", depending on
886 the value of "HeKLEN()". Can be assigned to. The "HePV()" or
887 "HeSVKEY()" macros are usually preferable for finding the value
888 of a key.
889 void* HeKEY(HE* he)
891 HeKLEN If this is negative, and amounts to "HEf_SVKEY", it indicates
893 the entry holds an "SV*" key. Otherwise, holds the actual
894 length of the key. Can be assigned to. The "HePV()" macro is
895 usually preferable for finding key lengths.
896 STRLEN HeKLEN(HE* he)
898 HePV Returns the key slot of the hash entry as a "char*" value,
900 doing any necessary dereferencing of possibly "SV*" keys. The
901 length of the string is placed in "len" (this is a macro, so do
902 not use &len). If you do not care about what the length of the
903 key is, you may use the global variable "PL_na", though this is
904 rather less efficient than using a local variable. Remember
905 though, that hash keys in perl are free to contain embedded
906 nulls, so using "strlen()" or similar is not a good way to find
907 the length of hash keys. This is very similar to the "SvPV()"
908 macro described elsewhere in this document. See also "HeUTF8".
909 If you are using "HePV" to get values to pass to "newSVpvn()"
911 to create a new SV, you should consider using
912 "newSVhek(HeKEY_hek(he))" as it is more efficient.
913 char* HePV(HE* he, STRLEN len)
915 HeSVKEY Returns the key as an "SV*", or "NULL" if the hash entry does
917 not contain an "SV*" key.
918 SV* HeSVKEY(HE* he)
920 HeSVKEY_force
922 Returns the key as an "SV*". Will create and return a
923 temporary mortal "SV*" if the hash entry contains only a
924 "char*" key.
925 SV* HeSVKEY_force(HE* he)
927 HeSVKEY_set
929 Sets the key to a given "SV*", taking care to set the
930 appropriate flags to indicate the presence of an "SV*" key, and
931 returns the same "SV*".
932 SV* HeSVKEY_set(HE* he, SV* sv)
934 HeUTF8 Returns whether the "char *" value returned by "HePV" is
936 encoded in UTF-8, doing any necessary dereferencing of possibly
937 "SV*" keys. The value returned will be 0 or non-0, not
938 necessarily 1 (or even a value with any low bits set), so do
939 not blindly assign this to a "bool" variable, as "bool" may be
940 a typedef for "char".
941 char* HeUTF8(HE* he, STRLEN len)
943 HeVAL Returns the value slot (type "SV*") stored in the hash entry.
945 SV* HeVAL(HE* he)
947 HvNAME Returns the package name of a stash, or NULL if "stash" isn't a
949 stash. See "SvSTASH", "CvSTASH".
950 char* HvNAME(HV* stash)
952 hv_assert
954 Check that a hash is in an internally consistent state.
955 void hv_assert(HV *hv)
957 hv_clear
959 Clears a hash, making it empty.
960 void hv_clear(HV* hv)
962 hv_clear_placeholders
964 Clears any placeholders from a hash. If a restricted hash has
965 any of its keys marked as readonly and the key is subsequently
966 deleted, the key is not actually deleted but is marked by
967 assigning it a value of &PL_sv_placeholder. This tags it so it
968 will be ignored by future operations such as iterating over the
969 hash, but will still allow the hash to have a value reassigned
970 to the key at some future point. This function clears any such
971 placeholder keys from the hash. See Hash::Util::lock_keys()
972 for an example of its use.
973 void hv_clear_placeholders(HV *hv)
975 hv_delete
977 Deletes a key/value pair in the hash. The value SV is removed
978 from the hash and returned to the caller. The "klen" is the
979 length of the key. The "flags" value will normally be zero; if
980 set to G_DISCARD then NULL will be returned.
981 SV* hv_delete(HV *hv, const char *key, I32 klen, I32 flags)
983 hv_delete_ent
985 Deletes a key/value pair in the hash. The value SV is removed
986 from the hash and returned to the caller. The "flags" value
987 will normally be zero; if set to G_DISCARD then NULL will be
988 returned. "hash" can be a valid precomputed hash value, or 0
989 to ask for it to be computed.
990 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
992 hv_exists
994 Returns a boolean indicating whether the specified hash key
995 exists. The "klen" is the length of the key.
996 bool hv_exists(HV *hv, const char *key, I32 klen)
998 hv_exists_ent
1000 Returns a boolean indicating whether the specified hash key
1001 exists. "hash" can be a valid precomputed hash value, or 0 to
1002 ask for it to be computed.
1003 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
1005 hv_fetch
1007 Returns the SV which corresponds to the specified key in the
1008 hash. The "klen" is the length of the key. If "lval" is set
1009 then the fetch will be part of a store. Check that the return
1010 value is non-null before dereferencing it to an "SV*".
1011 See "Understanding the Magic of Tied Hashes and Arrays" in
1013 perlguts for more information on how to use this function on
1014 tied hashes.
1015 SV** hv_fetch(HV *hv, const char *key, I32 klen, I32 lval)
1017 hv_fetchs
1019 Like "hv_fetch", but takes a literal string instead of a
1020 string/length pair.
1021 SV** hv_fetchs(HV* tb, const char* key, I32 lval)
1023 hv_fetch_ent
1025 Returns the hash entry which corresponds to the specified key
1026 in the hash. "hash" must be a valid precomputed hash number
1027 for the given "key", or 0 if you want the function to compute
1028 it. IF "lval" is set then the fetch will be part of a store.
1029 Make sure the return value is non-null before accessing it.
1030 The return value when "tb" is a tied hash is a pointer to a
1031 static location, so be sure to make a copy of the structure if
1032 you need to store it somewhere.
1033 See "Understanding the Magic of Tied Hashes and Arrays" in
1035 perlguts for more information on how to use this function on
1036 tied hashes.
1037 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
1039 hv_iterinit
1041 Prepares a starting point to traverse a hash table. Returns
1042 the number of keys in the hash (i.e. the same as "HvKEYS(tb)").
1043 The return value is currently only meaningful for hashes
1044 without tie magic.
1045 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
1047 number of hash buckets that happen to be in use. If you still
1048 need that esoteric value, you can get it through the macro
1049 "HvFILL(tb)".
1050 I32 hv_iterinit(HV *hv)
1052 hv_iterkey
1054 Returns the key from the current position of the hash iterator.
1055 See "hv_iterinit".
1056 char* hv_iterkey(HE* entry, I32* retlen)
1058 hv_iterkeysv
1060 Returns the key as an "SV*" from the current position of the
1061 hash iterator. The return value will always be a mortal copy
1062 of the key. Also see "hv_iterinit".
1063 SV* hv_iterkeysv(HE* entry)
1065 hv_iternext
1067 Returns entries from a hash iterator. See "hv_iterinit".
1068 You may call "hv_delete" or "hv_delete_ent" on the hash entry
1070 that the iterator currently points to, without losing your
1071 place or invalidating your iterator. Note that in this case
1072 the current entry is deleted from the hash with your iterator
1073 holding the last reference to it. Your iterator is flagged to
1074 free the entry on the next call to "hv_iternext", so you must
1075 not discard your iterator immediately else the entry will leak
1076 - call "hv_iternext" to trigger the resource deallocation.
1077 HE* hv_iternext(HV *hv)
1079 hv_iternextsv
1081 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
1082 one operation.
1083 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
1085 hv_iternext_flags
1087 Returns entries from a hash iterator. See "hv_iterinit" and
1088 "hv_iternext". The "flags" value will normally be zero; if
1089 HV_ITERNEXT_WANTPLACEHOLDERS is set the placeholders keys (for
1090 restricted hashes) will be returned in addition to normal keys.
1091 By default placeholders are automatically skipped over.
1092 Currently a placeholder is implemented with a value that is
1093 &Perl_sv_placeholder. Note that the implementation of
1094 placeholders and restricted hashes may change, and the
1095 implementation currently is insufficiently abstracted for any
1096 change to be tidy.
1097 NOTE: this function is experimental and may change or be
1099 removed without notice.
1100 HE* hv_iternext_flags(HV *hv, I32 flags)
1102 hv_iterval
1104 Returns the value from the current position of the hash
1105 iterator. See "hv_iterkey".
1106 SV* hv_iterval(HV *hv, HE *entry)
1108 hv_magic
1110 Adds magic to a hash. See "sv_magic".
1111 void hv_magic(HV *hv, GV *gv, int how)
1113 hv_scalar
1115 Evaluates the hash in scalar context and returns the result.
1116 Handles magic when the hash is tied.
1117 SV* hv_scalar(HV *hv)
1119 hv_store
1121 Stores an SV in a hash. The hash key is specified as "key" and
1122 "klen" is the length of the key. The "hash" parameter is the
1123 precomputed hash value; if it is zero then Perl will compute
1124 it. The return value will be NULL if the operation failed or
1125 if the value did not need to be actually stored within the hash
1126 (as in the case of tied hashes). Otherwise it can be
1127 dereferenced to get the original "SV*". Note that the caller
1128 is responsible for suitably incrementing the reference count of
1129 "val" before the call, and decrementing it if the function
1130 returned NULL. Effectively a successful hv_store takes
1131 ownership of one reference to "val". This is usually what you
1132 want; a newly created SV has a reference count of one, so if
1133 all your code does is create SVs then store them in a hash,
1134 hv_store will own the only reference to the new SV, and your
1135 code doesn't need to do anything further to tidy up. hv_store
1136 is not implemented as a call to hv_store_ent, and does not
1137 create a temporary SV for the key, so if your key data is not
1138 already in SV form then use hv_store in preference to
1139 hv_store_ent.
1140 See "Understanding the Magic of Tied Hashes and Arrays" in
1142 perlguts for more information on how to use this function on
1143 tied hashes.
1144 SV** hv_store(HV *hv, const char *key, I32 klen, SV *val, U32 hash)
1146 hv_stores
1148 Like "hv_store", but takes a literal string instead of a
1149 string/length pair and omits the hash parameter.
1150 SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
1152 hv_store_ent
1154 Stores "val" in a hash. The hash key is specified as "key".
1155 The "hash" parameter is the precomputed hash value; if it is
1156 zero then Perl will compute it. The return value is the new
1157 hash entry so created. It will be NULL if the operation failed
1158 or if the value did not need to be actually stored within the
1159 hash (as in the case of tied hashes). Otherwise the contents
1160 of the return value can be accessed using the "He?" macros
1161 described here. Note that the caller is responsible for
1162 suitably incrementing the reference count of "val" before the
1163 call, and decrementing it if the function returned NULL.
1164 Effectively a successful hv_store_ent takes ownership of one
1165 reference to "val". This is usually what you want; a newly
1166 created SV has a reference count of one, so if all your code
1167 does is create SVs then store them in a hash, hv_store will own
1168 the only reference to the new SV, and your code doesn't need to
1169 do anything further to tidy up. Note that hv_store_ent only
1170 reads the "key"; unlike "val" it does not take ownership of it,
1171 so maintaining the correct reference count on "key" is entirely
1172 the caller's responsibility. hv_store is not implemented as a
1173 call to hv_store_ent, and does not create a temporary SV for
1174 the key, so if your key data is not already in SV form then use
1175 hv_store in preference to hv_store_ent.
1176 See "Understanding the Magic of Tied Hashes and Arrays" in
1178 perlguts for more information on how to use this function on
1179 tied hashes.
1180 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
1182 hv_undef
1184 Undefines the hash.
1185 void hv_undef(HV *hv)
1187 newHV Creates a new HV. The reference count is set to 1.
1189 HV* newHV()
1191
1193 mg_clear
1194 Clear something magical that the SV represents. See
1195 "sv_magic".
1196 int mg_clear(SV* sv)
1198 mg_copy Copies the magic from one SV to another. See "sv_magic".
1200 int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
1202 mg_find Finds the magic pointer for type matching the SV. See
1204 "sv_magic".
1205 MAGIC* mg_find(const SV* sv, int type)
1207 mg_free Free any magic storage used by the SV. See "sv_magic".
1209 int mg_free(SV* sv)
1211 mg_get Do magic after a value is retrieved from the SV. See
1213 "sv_magic".
1214 int mg_get(SV* sv)
1216 mg_length
1218 Report on the SV's length. See "sv_magic".
1219 U32 mg_length(SV* sv)
1221 mg_magical
1223 Turns on the magical status of an SV. See "sv_magic".
1224 void mg_magical(SV* sv)
1226 mg_set Do magic after a value is assigned to the SV. See "sv_magic".
1228 int mg_set(SV* sv)
1230 SvGETMAGIC
1232 Invokes "mg_get" on an SV if it has 'get' magic. This macro
1233 evaluates its argument more than once.
1234 void SvGETMAGIC(SV* sv)
1236 SvLOCK Arranges for a mutual exclusion lock to be obtained on sv if a
1238 suitable module has been loaded.
1239 void SvLOCK(SV* sv)
1241 SvSETMAGIC
1243 Invokes "mg_set" on an SV if it has 'set' magic. This macro
1244 evaluates its argument more than once.
1245 void SvSETMAGIC(SV* sv)
1247 SvSetMagicSV
1249 Like "SvSetSV", but does any set magic required afterwards.
1250 void SvSetMagicSV(SV* dsb, SV* ssv)
1252 SvSetMagicSV_nosteal
1254 Like "SvSetSV_nosteal", but does any set magic required
1255 afterwards.
1256 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
1258 SvSetSV Calls "sv_setsv" if dsv is not the same as ssv. May evaluate
1260 arguments more than once.
1261 void SvSetSV(SV* dsb, SV* ssv)
1263 SvSetSV_nosteal
1265 Calls a non-destructive version of "sv_setsv" if dsv is not the
1266 same as ssv. May evaluate arguments more than once.
1267 void SvSetSV_nosteal(SV* dsv, SV* ssv)
1269 SvSHARE Arranges for sv to be shared between threads if a suitable
1271 module has been loaded.
1272 void SvSHARE(SV* sv)
1274 SvUNLOCK
1276 Releases a mutual exclusion lock on sv if a suitable module has
1277 been loaded.
1278 void SvUNLOCK(SV* sv)
1280
1282 Copy The XSUB-writer's interface to the C "memcpy" function. The
1283 "src" is the source, "dest" is the destination, "nitems" is the
1284 number of items, and "type" is the type. May fail on
1285 overlapping copies. See also "Move".
1286 void Copy(void* src, void* dest, int nitems, type)
1288 CopyD Like "Copy" but returns dest. Useful for encouraging compilers
1290 to tail-call optimise.
1291 void * CopyD(void* src, void* dest, int nitems, type)
1293 Move The XSUB-writer's interface to the C "memmove" function. The
1295 "src" is the source, "dest" is the destination, "nitems" is the
1296 number of items, and "type" is the type. Can do overlapping
1297 moves. See also "Copy".
1298 void Move(void* src, void* dest, int nitems, type)
1300 MoveD Like "Move" but returns dest. Useful for encouraging compilers
1302 to tail-call optimise.
1303 void * MoveD(void* src, void* dest, int nitems, type)
1305 Newx The XSUB-writer's interface to the C "malloc" function.
1307 In 5.9.3, Newx() and friends replace the older New() API, and
1309 drops the first parameter, x, a debug aid which allowed callers
1310 to identify themselves. This aid has been superseded by a new
1311 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhack).
1312 The older API is still there for use in XS modules supporting
1313 older perls.
1314 void Newx(void* ptr, int nitems, type)
1316 Newxc The XSUB-writer's interface to the C "malloc" function, with
1318 cast. See also "Newx".
1319 void Newxc(void* ptr, int nitems, type, cast)
1321 Newxz The XSUB-writer's interface to the C "malloc" function. The
1323 allocated memory is zeroed with "memzero". See also "Newx".
1324 void Newxz(void* ptr, int nitems, type)
1326 Poison PoisonWith(0xEF) for catching access to freed memory.
1328 void Poison(void* dest, int nitems, type)
1330 PoisonFree
1332 PoisonWith(0xEF) for catching access to freed memory.
1333 void PoisonFree(void* dest, int nitems, type)
1335 PoisonNew
1337 PoisonWith(0xAB) for catching access to allocated but
1338 uninitialized memory.
1339 void PoisonNew(void* dest, int nitems, type)
1341 PoisonWith
1343 Fill up memory with a byte pattern (a byte repeated over and
1344 over again) that hopefully catches attempts to access
1345 uninitialized memory.
1346 void PoisonWith(void* dest, int nitems, type, U8 byte)
1348 Renew The XSUB-writer's interface to the C "realloc" function.
1350 void Renew(void* ptr, int nitems, type)
1352 Renewc The XSUB-writer's interface to the C "realloc" function, with
1354 cast.
1355 void Renewc(void* ptr, int nitems, type, cast)
1357 Safefree
1359 The XSUB-writer's interface to the C "free" function.
1360 void Safefree(void* ptr)
1362 savepv Perl's version of "strdup()". Returns a pointer to a newly
1364 allocated string which is a duplicate of "pv". The size of the
1365 string is determined by "strlen()". The memory allocated for
1366 the new string can be freed with the "Safefree()" function.
1367 char* savepv(const char* pv)
1369 savepvn Perl's version of what "strndup()" would be if it existed.
1371 Returns a pointer to a newly allocated string which is a
1372 duplicate of the first "len" bytes from "pv", plus a trailing
1373 NUL byte. The memory allocated for the new string can be freed
1374 with the "Safefree()" function.
1375 char* savepvn(const char* pv, I32 len)
1377 savepvs Like "savepvn", but takes a literal string instead of a
1379 string/length pair.
1380 char* savepvs(const char* s)
1382 savesharedpv
1384 A version of "savepv()" which allocates the duplicate string in
1385 memory which is shared between threads.
1386 char* savesharedpv(const char* pv)
1388 savesharedpvn
1390 A version of "savepvn()" which allocates the duplicate string
1391 in memory which is shared between threads. (With the specific
1392 difference that a NULL pointer is not acceptable)
1393 char* savesharedpvn(const char *const pv, const STRLEN len)
1395 savesvpv
1397 A version of "savepv()"/"savepvn()" which gets the string to
1398 duplicate from the passed in SV using "SvPV()"
1399 char* savesvpv(SV* sv)
1401 StructCopy
1403 This is an architecture-independent macro to copy one structure
1404 to another.
1405 void StructCopy(type src, type dest, type)
1407 Zero The XSUB-writer's interface to the C "memzero" function. The
1409 "dest" is the destination, "nitems" is the number of items, and
1410 "type" is the type.
1411 void Zero(void* dest, int nitems, type)
1413 ZeroD Like "Zero" but returns dest. Useful for encouraging compilers
1415 to tail-call optimise.
1416 void * ZeroD(void* dest, int nitems, type)
1418
1420 fbm_compile
1421 Analyses the string in order to make fast searches on it using
1422 fbm_instr() -- the Boyer-Moore algorithm.
1423 void fbm_compile(SV* sv, U32 flags)
1425 fbm_instr
1427 Returns the location of the SV in the string delimited by "str"
1428 and "strend". It returns "NULL" if the string can't be found.
1429 The "sv" does not have to be fbm_compiled, but the search will
1430 not be as fast then.
1431 char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlestr, U32 flags)
1433 form Takes a sprintf-style format pattern and conventional (non-SV)
1435 arguments and returns the formatted string.
1436 (char *) Perl_form(pTHX_ const char* pat, ...)
1438 can be used any place a string (char *) is required:
1440 char * s = Perl_form("%d.%d",major,minor);
1442 Uses a single private buffer so if you want to format several
1444 strings you must explicitly copy the earlier strings away (and
1445 free the copies when you are done).
1446 char* form(const char* pat, ...)
1448 getcwd_sv
1450 Fill the sv with current working directory
1451 int getcwd_sv(SV* sv)
1453 my_snprintf
1455 The C library "snprintf" functionality, if available and
1456 standards-compliant (uses "vsnprintf", actually). However, if
1457 the "vsnprintf" is not available, will unfortunately use the
1458 unsafe "vsprintf" which can overrun the buffer (there is an
1459 overrun check, but that may be too late). Consider using
1460 "sv_vcatpvf" instead, or getting "vsnprintf".
1461 int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
1463 my_sprintf
1465 The C library "sprintf", wrapped if necessary, to ensure that
1466 it will return the length of the string written to the buffer.
1467 Only rare pre-ANSI systems need the wrapper function - usually
1468 this is a direct call to "sprintf".
1469 int my_sprintf(char *buffer, const char *pat, ...)
1471 my_vsnprintf
1473 The C library "vsnprintf" if available and standards-compliant.
1474 However, if if the "vsnprintf" is not available, will
1475 unfortunately use the unsafe "vsprintf" which can overrun the
1476 buffer (there is an overrun check, but that may be too late).
1477 Consider using "sv_vcatpvf" instead, or getting "vsnprintf".
1478 int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
1480 new_version
1482 Returns a new version object based on the passed in SV:
1483 SV *sv = new_version(SV *ver);
1485 Does not alter the passed in ver SV. See "upg_version" if you
1487 want to upgrade the SV.
1488 SV* new_version(SV *ver)
1490 scan_version
1492 Returns a pointer to the next character after the parsed
1493 version string, as well as upgrading the passed in SV to an RV.
1494 Function must be called with an already existing SV like
1496 sv = newSV(0);
1498 s = scan_version(s, SV *sv, bool qv);
1499 Performs some preprocessing to the string to ensure that it has
1501 the correct characteristics of a version. Flags the object if
1502 it contains an underscore (which denotes this is an alpha
1503 version). The boolean qv denotes that the version should be
1504 interpreted as if it had multiple decimals, even if it doesn't.
1505 const char* scan_version(const char *s, SV *rv, bool qv)
1507 strEQ Test two strings to see if they are equal. Returns true or
1509 false.
1510 bool strEQ(char* s1, char* s2)
1512 strGE Test two strings to see if the first, "s1", is greater than or
1514 equal to the second, "s2". Returns true or false.
1515 bool strGE(char* s1, char* s2)
1517 strGT Test two strings to see if the first, "s1", is greater than the
1519 second, "s2". Returns true or false.
1520 bool strGT(char* s1, char* s2)
1522 strLE Test two strings to see if the first, "s1", is less than or
1524 equal to the second, "s2". Returns true or false.
1525 bool strLE(char* s1, char* s2)
1527 strLT Test two strings to see if the first, "s1", is less than the
1529 second, "s2". Returns true or false.
1530 bool strLT(char* s1, char* s2)
1532 strNE Test two strings to see if they are different. Returns true or
1534 false.
1535 bool strNE(char* s1, char* s2)
1537 strnEQ Test two strings to see if they are equal. The "len" parameter
1539 indicates the number of bytes to compare. Returns true or
1540 false. (A wrapper for "strncmp").
1541 bool strnEQ(char* s1, char* s2, STRLEN len)
1543 strnNE Test two strings to see if they are different. The "len"
1545 parameter indicates the number of bytes to compare. Returns
1546 true or false. (A wrapper for "strncmp").
1547 bool strnNE(char* s1, char* s2, STRLEN len)
1549 sv_destroyable
1551 Dummy routine which reports that object can be destroyed when
1552 there is no sharing module present. It ignores its single SV
1553 argument, and returns 'true'. Exists to avoid test for a NULL
1554 function pointer and because it could potentially warn under
1555 some level of strict-ness.
1556 bool sv_destroyable(SV *sv)
1558 sv_nosharing
1560 Dummy routine which "shares" an SV when there is no sharing
1561 module present. Or "locks" it. Or "unlocks" it. In other
1562 words, ignores its single SV argument. Exists to avoid test
1563 for a NULL function pointer and because it could potentially
1564 warn under some level of strict-ness.
1565 void sv_nosharing(SV *sv)
1567 upg_version
1569 In-place upgrade of the supplied SV to a version object.
1570 SV *sv = upg_version(SV *sv, bool qv);
1572 Returns a pointer to the upgraded SV. Set the boolean qv if
1574 you want to force this SV to be interpreted as an "extended"
1575 version.
1576 SV* upg_version(SV *ver, bool qv)
1578 vcmp Version object aware cmp. Both operands must already have been
1580 converted into version objects.
1581 int vcmp(SV *lhv, SV *rhv)
1583 vnormal Accepts a version object and returns the normalized string
1585 representation. Call like:
1586 sv = vnormal(rv);
1588 NOTE: you can pass either the object directly or the SV
1590 contained within the RV.
1591 SV* vnormal(SV *vs)
1593 vnumify Accepts a version object and returns the normalized floating
1595 point representation. Call like:
1596 sv = vnumify(rv);
1598 NOTE: you can pass either the object directly or the SV
1600 contained within the RV.
1601 SV* vnumify(SV *vs)
1603 vstringify
1605 In order to maintain maximum compatibility with earlier
1606 versions of Perl, this function will return either the floating
1607 point notation or the multiple dotted notation, depending on
1608 whether the original version contained 1 or more dots,
1609 respectively
1610 SV* vstringify(SV *vs)
1612 vverify Validates that the SV contains a valid version object.
1614 bool vverify(SV *vobj);
1616 Note that it only confirms the bare minimum structure (so as
1618 not to get confused by derived classes which may contain
1619 additional hash entries):
1620 bool vverify(SV *vs)
1622
1624 mro_get_linear_isa
1625 Returns either "mro_get_linear_isa_c3" or
1626 "mro_get_linear_isa_dfs" for the given stash, dependant upon
1627 which MRO is in effect for that stash. The return value is a
1628 read-only AV*.
1629 You are responsible for "SvREFCNT_inc()" on the return value if
1631 you plan to store it anywhere semi-permanently (otherwise it
1632 might be deleted out from under you the next time the cache is
1633 invalidated).
1634 AV* mro_get_linear_isa(HV* stash)
1636 mro_method_changed_in
1638 Invalidates method caching on any child classes of the given
1639 stash, so that they might notice the changes in this one.
1640 Ideally, all instances of "PL_sub_generation++" in perl source
1642 outside of "mro.c" should be replaced by calls to this.
1643 Perl automatically handles most of the common ways a method
1645 might be redefined. However, there are a few ways you could
1646 change a method in a stash without the cache code noticing, in
1647 which case you need to call this method afterwards:
1648 1) Directly manipulating the stash HV entries from XS code.
1650 2) Assigning a reference to a readonly scalar constant into a
1652 stash entry in order to create a constant subroutine (like
1653 constant.pm does).
1654 This same method is available from pure perl via,
1656 "mro::method_changed_in(classname)".
1657 void mro_method_changed_in(HV* stash)
1659
1661 dMULTICALL
1662 Declare local variables for a multicall. See "Lightweight
1663 Callbacks" in perlcall.
1664 dMULTICALL;
1666 MULTICALL
1668 Make a lightweight callback. See "Lightweight Callbacks" in
1669 perlcall.
1670 MULTICALL;
1672 POP_MULTICALL
1674 Closing bracket for a lightweight callback. See "Lightweight
1675 Callbacks" in perlcall.
1676 POP_MULTICALL;
1678 PUSH_MULTICALL
1680 Opening bracket for a lightweight callback. See "Lightweight
1681 Callbacks" in perlcall.
1682 PUSH_MULTICALL;
1684
1686 grok_bin
1687 converts a string representing a binary number to numeric form.
1688 On entry start and *len give the string to scan, *flags gives
1690 conversion flags, and result should be NULL or a pointer to an
1691 NV. The scan stops at the end of the string, or the first
1692 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
1693 in *flags, encountering an invalid character will also trigger
1694 a warning. On return *len is set to the length of the scanned
1695 string, and *flags gives output flags.
1696 If the value is <= "UV_MAX" it is returned as a UV, the output
1698 flags are clear, and nothing is written to *result. If the
1699 value is > UV_MAX "grok_bin" returns UV_MAX, sets
1700 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
1701 the value to *result (or the value is discarded if result is
1702 NULL).
1703 The binary number may optionally be prefixed with "0b" or "b"
1705 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
1706 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
1707 binary number may use '_' characters to separate digits.
1708 UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
1710 grok_hex
1712 converts a string representing a hex number to numeric form.
1713 On entry start and *len give the string to scan, *flags gives
1715 conversion flags, and result should be NULL or a pointer to an
1716 NV. The scan stops at the end of the string, or the first
1717 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
1718 in *flags, encountering an invalid character will also trigger
1719 a warning. On return *len is set to the length of the scanned
1720 string, and *flags gives output flags.
1721 If the value is <= UV_MAX it is returned as a UV, the output
1723 flags are clear, and nothing is written to *result. If the
1724 value is > UV_MAX "grok_hex" returns UV_MAX, sets
1725 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
1726 the value to *result (or the value is discarded if result is
1727 NULL).
1728 The hex number may optionally be prefixed with "0x" or "x"
1730 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
1731 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the hex
1732 number may use '_' characters to separate digits.
1733 UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
1735 grok_number
1737 Recognise (or not) a number. The type of the number is
1738 returned (0 if unrecognised), otherwise it is a bit-ORed
1739 combination of IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX,
1740 IS_NUMBER_NOT_INT, IS_NUMBER_NEG, IS_NUMBER_INFINITY,
1741 IS_NUMBER_NAN (defined in perl.h).
1742 If the value of the number can fit an in UV, it is returned in
1744 the *valuep IS_NUMBER_IN_UV will be set to indicate that
1745 *valuep is valid, IS_NUMBER_IN_UV will never be set unless
1746 *valuep is valid, but *valuep may have been assigned to during
1747 processing even though IS_NUMBER_IN_UV is not set on return.
1748 If valuep is NULL, IS_NUMBER_IN_UV will be set for the same
1749 cases as when valuep is non-NULL, but no actual assignment (or
1750 SEGV) will occur.
1751 IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing
1753 decimals were seen (in which case *valuep gives the true value
1754 truncated to an integer), and IS_NUMBER_NEG if the number is
1755 negative (in which case *valuep holds the absolute value).
1756 IS_NUMBER_IN_UV is not set if e notation was used or the number
1757 is larger than a UV.
1758 int grok_number(const char *pv, STRLEN len, UV *valuep)
1760 grok_numeric_radix
1762 Scan and skip for a numeric decimal separator (radix).
1763 bool grok_numeric_radix(const char **sp, const char *send)
1765 grok_oct
1767 converts a string representing an octal number to numeric form.
1768 On entry start and *len give the string to scan, *flags gives
1770 conversion flags, and result should be NULL or a pointer to an
1771 NV. The scan stops at the end of the string, or the first
1772 invalid character. Unless "PERL_SCAN_SILENT_ILLDIGIT" is set
1773 in *flags, encountering an invalid character will also trigger
1774 a warning. On return *len is set to the length of the scanned
1775 string, and *flags gives output flags.
1776 If the value is <= UV_MAX it is returned as a UV, the output
1778 flags are clear, and nothing is written to *result. If the
1779 value is > UV_MAX "grok_oct" returns UV_MAX, sets
1780 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
1781 the value to *result (or the value is discarded if result is
1782 NULL).
1783 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then the
1785 octal number may use '_' characters to separate digits.
1786 UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
1788 Perl_signbit
1790 Return a non-zero integer if the sign bit on an NV is set, and
1791 0 if it is not.
1792 If Configure detects this system has a signbit() that will work
1794 with our NVs, then we just use it via the #define in perl.h.
1795 Otherwise, fall back on this implementation. As a first pass,
1796 this gets everything right except -0.0. Alas, catching -0.0 is
1797 the main use for this function, so this is not too helpful yet.
1798 Still, at least we have the scaffolding in place to support
1799 other systems, should that prove useful.
1800 Configure notes: This function is called 'Perl_signbit'
1802 instead of a plain 'signbit' because it is easy to imagine a
1803 system having a signbit() function or macro that doesn't happen
1804 to work with our particular choice of NVs. We shouldn't just
1805 re-#define signbit as Perl_signbit and expect the standard
1806 system headers to be happy. Also, this is a no-context
1807 function (no pTHX_) because Perl_signbit() is usually
1808 re-#defined in perl.h as a simple macro call to the system's
1809 signbit(). Users should just always call Perl_signbit().
1810 NOTE: this function is experimental and may change or be
1812 removed without notice.
1813 int Perl_signbit(NV f)
1815 scan_bin
1817 For backwards compatibility. Use "grok_bin" instead.
1818 NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
1820 scan_hex
1822 For backwards compatibility. Use "grok_hex" instead.
1823 NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
1825 scan_oct
1827 For backwards compatibility. Use "grok_oct" instead.
1828 NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
1830
1832 cv_const_sv
1833 If "cv" is a constant sub eligible for inlining. returns the
1834 constant value returned by the sub. Otherwise, returns NULL.
1835 Constant subs can be created with "newCONSTSUB" or as described
1837 in "Constant Functions" in perlsub.
1838 SV* cv_const_sv(CV* cv)
1840 newCONSTSUB
1842 Creates a constant sub equivalent to Perl "sub FOO () { 123 }"
1843 which is eligible for inlining at compile-time.
1844 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
1846 newXS Used by "xsubpp" to hook up XSUBs as Perl subs. filename needs
1848 to be static storage, as it is used directly as CvFILE(),
1849 without a copy being made.
1850
1852 pad_sv Get the value at offset po in the current pad. Use macro
1853 PAD_SV instead of calling this function directly.
1854 SV* pad_sv(PADOFFSET po)
1856
1858 PL_modglobal
1859 "PL_modglobal" is a general purpose, interpreter global HV for
1860 use by extensions that need to keep information on a per-
1861 interpreter basis. In a pinch, it can also be used as a symbol
1862 table for extensions to share data among each other. It is a
1863 good idea to use keys prefixed by the package name of the
1864 extension that owns the data.
1865 HV* PL_modglobal
1867 PL_na A convenience variable which is typically used with "SvPV" when
1869 one doesn't care about the length of the string. It is usually
1870 more efficient to either declare a local variable and use that
1871 instead or to use the "SvPV_nolen" macro.
1872 STRLEN PL_na
1874 PL_sv_no
1876 This is the "false" SV. See "PL_sv_yes". Always refer to this
1877 as &PL_sv_no.
1878 SV PL_sv_no
1880 PL_sv_undef
1882 This is the "undef" SV. Always refer to this as &PL_sv_undef.
1883 SV PL_sv_undef
1885 PL_sv_yes
1887 This is the "true" SV. See "PL_sv_no". Always refer to this
1888 as &PL_sv_yes.
1889 SV PL_sv_yes
1891
1893 SvRX Convenience macro to get the REGEXP from a SV. This is
1894 approximately equivalent to the following snippet:
1895 if (SvMAGICAL(sv))
1897 mg_get(sv);
1898 if (SvROK(sv) &&
1899 (tmpsv = (SV*)SvRV(sv)) &&
1900 SvTYPE(tmpsv) == SVt_PVMG &&
1901 (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
1902 {
1903 return (REGEXP *)tmpmg->mg_obj;
1904 }
1905 NULL will be returned if a REGEXP* is not found.
1907 REGEXP * SvRX(SV *sv)
1909 SvRXOK Returns a boolean indicating whether the SV contains qr magic
1911 (PERL_MAGIC_qr).
1912 If you want to do something with the REGEXP* later use SvRX
1914 instead and check for NULL.
1915 bool SvRXOK(SV* sv)
1917
1919 dXCPT Set up necessary local variables for exception handling. See
1920 "Exception Handling" in perlguts.
1921 dXCPT;
1923 XCPT_CATCH
1925 Introduces a catch block. See "Exception Handling" in
1926 perlguts.
1927 XCPT_RETHROW
1929 Rethrows a previously caught exception. See "Exception
1930 Handling" in perlguts.
1931 XCPT_RETHROW;
1933 XCPT_TRY_END
1935 Ends a try block. See "Exception Handling" in perlguts.
1936 XCPT_TRY_START
1938 Starts a try block. See "Exception Handling" in perlguts.
1939
1941 dMARK Declare a stack marker variable, "mark", for the XSUB. See
1942 "MARK" and "dORIGMARK".
1943 dMARK;
1945 dORIGMARK
1947 Saves the original stack mark for the XSUB. See "ORIGMARK".
1948 dORIGMARK;
1950 dSP Declares a local copy of perl's stack pointer for the XSUB,
1952 available via the "SP" macro. See "SP".
1953 dSP;
1955 EXTEND Used to extend the argument stack for an XSUB's return values.
1957 Once used, guarantees that there is room for at least "nitems"
1958 to be pushed onto the stack.
1959 void EXTEND(SP, int nitems)
1961 MARK Stack marker variable for the XSUB. See "dMARK".
1963 mPUSHi Push an integer onto the stack. The stack must have room for
1965 this element. Does not use "TARG". See also "PUSHi",
1966 "mXPUSHi" and "XPUSHi".
1967 void mPUSHi(IV iv)
1969 mPUSHn Push a double onto the stack. The stack must have room for
1971 this element. Does not use "TARG". See also "PUSHn",
1972 "mXPUSHn" and "XPUSHn".
1973 void mPUSHn(NV nv)
1975 mPUSHp Push a string onto the stack. The stack must have room for
1977 this element. The "len" indicates the length of the string.
1978 Does not use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
1979 void mPUSHp(char* str, STRLEN len)
1981 mPUSHs Push an SV onto the stack and mortalizes the SV. The stack
1983 must have room for this element. Does not use "TARG". See
1984 also "PUSHs" and "mXPUSHs".
1985 void mPUSHs(SV* sv)
1987 mPUSHu Push an unsigned integer onto the stack. The stack must have
1989 room for this element. Does not use "TARG". See also "PUSHu",
1990 "mXPUSHu" and "XPUSHu".
1991 void mPUSHu(UV uv)
1993 mXPUSHi Push an integer onto the stack, extending the stack if
1995 necessary. Does not use "TARG". See also "XPUSHi", "mPUSHi"
1996 and "PUSHi".
1997 void mXPUSHi(IV iv)
1999 mXPUSHn Push a double onto the stack, extending the stack if necessary.
2001 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
2002 void mXPUSHn(NV nv)
2004 mXPUSHp Push a string onto the stack, extending the stack if necessary.
2006 The "len" indicates the length of the string. Does not use
2007 "TARG". See also "XPUSHp", "mPUSHp" and "PUSHp".
2008 void mXPUSHp(char* str, STRLEN len)
2010 mXPUSHs Push an SV onto the stack, extending the stack if necessary and
2012 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
2013 "mPUSHs".
2014 void mXPUSHs(SV* sv)
2016 mXPUSHu Push an unsigned integer onto the stack, extending the stack if
2018 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu"
2019 and "PUSHu".
2020 void mXPUSHu(UV uv)
2022 ORIGMARK
2024 The original stack mark for the XSUB. See "dORIGMARK".
2025 POPi Pops an integer off the stack.
2027 IV POPi
2029 POPl Pops a long off the stack.
2031 long POPl
2033 POPn Pops a double off the stack.
2035 NV POPn
2037 POPp Pops a string off the stack. Deprecated. New code should use
2039 POPpx.
2040 char* POPp
2042 POPpbytex
2044 Pops a string off the stack which must consist of bytes i.e.
2045 characters < 256.
2046 char* POPpbytex
2048 POPpx Pops a string off the stack.
2050 char* POPpx
2052 POPs Pops an SV off the stack.
2054 SV* POPs
2056 PUSHi Push an integer onto the stack. The stack must have room for
2058 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
2059 or "dXSTARG" should be called to declare it. Do not call
2060 multiple "TARG"-oriented macros to return lists from XSUB's -
2061 see "mPUSHi" instead. See also "XPUSHi" and "mXPUSHi".
2062 void PUSHi(IV iv)
2064 PUSHMARK
2066 Opening bracket for arguments on a callback. See "PUTBACK" and
2067 perlcall.
2068 void PUSHMARK(SP)
2070 PUSHmortal
2072 Push a new mortal SV onto the stack. The stack must have room
2073 for this element. Does not use "TARG". See also "PUSHs",
2074 "XPUSHmortal" and "XPUSHs".
2075 void PUSHmortal()
2077 PUSHn Push a double onto the stack. The stack must have room for
2079 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
2080 or "dXSTARG" should be called to declare it. Do not call
2081 multiple "TARG"-oriented macros to return lists from XSUB's -
2082 see "mPUSHn" instead. See also "XPUSHn" and "mXPUSHn".
2083 void PUSHn(NV nv)
2085 PUSHp Push a string onto the stack. The stack must have room for
2087 this element. The "len" indicates the length of the string.
2088 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
2089 should be called to declare it. Do not call multiple
2090 "TARG"-oriented macros to return lists from XSUB's - see
2091 "mPUSHp" instead. See also "XPUSHp" and "mXPUSHp".
2092 void PUSHp(char* str, STRLEN len)
2094 PUSHs Push an SV onto the stack. The stack must have room for this
2096 element. Does not handle 'set' magic. Does not use "TARG".
2097 See also "PUSHmortal", "XPUSHs" and "XPUSHmortal".
2098 void PUSHs(SV* sv)
2100 PUSHu Push an unsigned integer onto the stack. The stack must have
2102 room for this element. Handles 'set' magic. Uses "TARG", so
2103 "dTARGET" or "dXSTARG" should be called to declare it. Do not
2104 call multiple "TARG"-oriented macros to return lists from
2105 XSUB's - see "mPUSHu" instead. See also "XPUSHu" and
2106 "mXPUSHu".
2107 void PUSHu(UV uv)
2109 PUTBACK Closing bracket for XSUB arguments. This is usually handled by
2111 "xsubpp". See "PUSHMARK" and perlcall for other uses.
2112 PUTBACK;
2114 SP Stack pointer. This is usually handled by "xsubpp". See "dSP"
2116 and "SPAGAIN".
2117 SPAGAIN Refetch the stack pointer. Used after a callback. See
2119 perlcall.
2120 SPAGAIN;
2122 XPUSHi Push an integer onto the stack, extending the stack if
2124 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
2125 "dXSTARG" should be called to declare it. Do not call multiple
2126 "TARG"-oriented macros to return lists from XSUB's - see
2127 "mXPUSHi" instead. See also "PUSHi" and "mPUSHi".
2128 void XPUSHi(IV iv)
2130 XPUSHmortal
2132 Push a new mortal SV onto the stack, extending the stack if
2133 necessary. Does not use "TARG". See also "XPUSHs",
2134 "PUSHmortal" and "PUSHs".
2135 void XPUSHmortal()
2137 XPUSHn Push a double onto the stack, extending the stack if necessary.
2139 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
2140 should be called to declare it. Do not call multiple
2141 "TARG"-oriented macros to return lists from XSUB's - see
2142 "mXPUSHn" instead. See also "PUSHn" and "mPUSHn".
2143 void XPUSHn(NV nv)
2145 XPUSHp Push a string onto the stack, extending the stack if necessary.
2147 The "len" indicates the length of the string. Handles 'set'
2148 magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be called
2149 to declare it. Do not call multiple "TARG"-oriented macros to
2150 return lists from XSUB's - see "mXPUSHp" instead. See also
2151 "PUSHp" and "mPUSHp".
2152 void XPUSHp(char* str, STRLEN len)
2154 XPUSHs Push an SV onto the stack, extending the stack if necessary.
2156 Does not handle 'set' magic. Does not use "TARG". See also
2157 "XPUSHmortal", "PUSHs" and "PUSHmortal".
2158 void XPUSHs(SV* sv)
2160 XPUSHu Push an unsigned integer onto the stack, extending the stack if
2162 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
2163 "dXSTARG" should be called to declare it. Do not call multiple
2164 "TARG"-oriented macros to return lists from XSUB's - see
2165 "mXPUSHu" instead. See also "PUSHu" and "mPUSHu".
2166 void XPUSHu(UV uv)
2168 XSRETURN
2170 Return from XSUB, indicating number of items on the stack.
2171 This is usually handled by "xsubpp".
2172 void XSRETURN(int nitems)
2174 XSRETURN_EMPTY
2176 Return an empty list from an XSUB immediately.
2177 XSRETURN_EMPTY;
2179 XSRETURN_IV
2181 Return an integer from an XSUB immediately. Uses "XST_mIV".
2182 void XSRETURN_IV(IV iv)
2184 XSRETURN_NO
2186 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
2187 XSRETURN_NO;
2189 XSRETURN_NV
2191 Return a double from an XSUB immediately. Uses "XST_mNV".
2192 void XSRETURN_NV(NV nv)
2194 XSRETURN_PV
2196 Return a copy of a string from an XSUB immediately. Uses
2197 "XST_mPV".
2198 void XSRETURN_PV(char* str)
2200 XSRETURN_UNDEF
2202 Return &PL_sv_undef from an XSUB immediately. Uses
2203 "XST_mUNDEF".
2204 XSRETURN_UNDEF;
2206 XSRETURN_UV
2208 Return an integer from an XSUB immediately. Uses "XST_mUV".
2209 void XSRETURN_UV(IV uv)
2211 XSRETURN_YES
2213 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
2214 XSRETURN_YES;
2216 XST_mIV Place an integer into the specified position "pos" on the
2218 stack. The value is stored in a new mortal SV.
2219 void XST_mIV(int pos, IV iv)
2221 XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
2223 void XST_mNO(int pos)
2225 XST_mNV Place a double into the specified position "pos" on the stack.
2227 The value is stored in a new mortal SV.
2228 void XST_mNV(int pos, NV nv)
2230 XST_mPV Place a copy of a string into the specified position "pos" on
2232 the stack. The value is stored in a new mortal SV.
2233 void XST_mPV(int pos, char* str)
2235 XST_mUNDEF
2237 Place &PL_sv_undef into the specified position "pos" on the
2238 stack.
2239 void XST_mUNDEF(int pos)
2241 XST_mYES
2243 Place &PL_sv_yes into the specified position "pos" on the
2244 stack.
2245 void XST_mYES(int pos)
2247
2249 svtype An enum of flags for Perl types. These are found in the file
2250 sv.h in the "svtype" enum. Test these flags with the "SvTYPE"
2251 macro.
2252 SVt_IV Integer type flag for scalars. See "svtype".
2254 SVt_NV Double type flag for scalars. See "svtype".
2256 SVt_PV Pointer type flag for scalars. See "svtype".
2258 SVt_PVAV
2260 Type flag for arrays. See "svtype".
2261 SVt_PVCV
2263 Type flag for code refs. See "svtype".
2264 SVt_PVHV
2266 Type flag for hashes. See "svtype".
2267 SVt_PVMG
2269 Type flag for blessed scalars. See "svtype".
2270
2272 croak_xs_usage
2273 A specialised variant of "croak()" for emitting the usage
2274 message for xsubs
2275 croak_xs_usage(cv, "eee_yow");
2277 works out the package name and subroutine name from "cv", and
2279 then calls "croak()". Hence if "cv" is &ouch::awk, it would
2280 call "croak" as:
2281 Perl_croak(aTHX_ "Usage %s::%s(%s)", "ouch" "awk", "eee_yow");
2283 void croak_xs_usage(const CV *const cv, const char *const params)
2285 get_sv Returns the SV of the specified Perl scalar. "flags" are
2287 passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
2288 variable does not exist then it will be created. If "flags" is
2289 zero and the variable does not exist then NULL is returned.
2290 NOTE: the perl_ form of this function is deprecated.
2292 SV* get_sv(const char *name, I32 flags)
2294 newRV_inc
2296 Creates an RV wrapper for an SV. The reference count for the
2297 original SV is incremented.
2298 SV* newRV_inc(SV* sv)
2300 newSVpvn_utf8
2302 Creates a new SV and copies a string into it. If utf8 is true,
2303 calls "SvUTF8_on" on the new SV. Implemented as a wrapper
2304 around "newSVpvn_flags".
2305 SV* newSVpvn_utf8(NULLOK const char* s, STRLEN len, U32 utf8)
2307 SvCUR Returns the length of the string which is in the SV. See
2309 "SvLEN".
2310 STRLEN SvCUR(SV* sv)
2312 SvCUR_set
2314 Set the current length of the string which is in the SV. See
2315 "SvCUR" and "SvIV_set".
2316 void SvCUR_set(SV* sv, STRLEN len)
2318 SvEND Returns a pointer to the last character in the string which is
2320 in the SV. See "SvCUR". Access the character as *(SvEND(sv)).
2321 char* SvEND(SV* sv)
2323 SvGAMAGIC
2325 Returns true if the SV has get magic or overloading. If either
2326 is true then the scalar is active data, and has the potential
2327 to return a new value every time it is accessed. Hence you must
2328 be careful to only read it once per user logical operation and
2329 work with that returned value. If neither is true then the
2330 scalar's value cannot change unless written to.
2331 U32 SvGAMAGIC(SV* sv)
2333 SvGROW Expands the character buffer in the SV so that it has room for
2335 the indicated number of bytes (remember to reserve space for an
2336 extra trailing NUL character). Calls "sv_grow" to perform the
2337 expansion if necessary. Returns a pointer to the character
2338 buffer.
2339 char * SvGROW(SV* sv, STRLEN len)
2341 SvIOK Returns a U32 value indicating whether the SV contains an
2343 integer.
2344 U32 SvIOK(SV* sv)
2346 SvIOKp Returns a U32 value indicating whether the SV contains an
2348 integer. Checks the private setting. Use "SvIOK" instead.
2349 U32 SvIOKp(SV* sv)
2351 SvIOK_notUV
2353 Returns a boolean indicating whether the SV contains a signed
2354 integer.
2355 bool SvIOK_notUV(SV* sv)
2357 SvIOK_off
2359 Unsets the IV status of an SV.
2360 void SvIOK_off(SV* sv)
2362 SvIOK_on
2364 Tells an SV that it is an integer.
2365 void SvIOK_on(SV* sv)
2367 SvIOK_only
2369 Tells an SV that it is an integer and disables all other OK
2370 bits.
2371 void SvIOK_only(SV* sv)
2373 SvIOK_only_UV
2375 Tells and SV that it is an unsigned integer and disables all
2376 other OK bits.
2377 void SvIOK_only_UV(SV* sv)
2379 SvIOK_UV
2381 Returns a boolean indicating whether the SV contains an
2382 unsigned integer.
2383 bool SvIOK_UV(SV* sv)
2385 SvIsCOW Returns a boolean indicating whether the SV is Copy-On-Write.
2387 (either shared hash key scalars, or full Copy On Write scalars
2388 if 5.9.0 is configured for COW)
2389 bool SvIsCOW(SV* sv)
2391 SvIsCOW_shared_hash
2393 Returns a boolean indicating whether the SV is Copy-On-Write
2394 shared hash key scalar.
2395 bool SvIsCOW_shared_hash(SV* sv)
2397 SvIV Coerces the given SV to an integer and returns it. See "SvIVx"
2399 for a version which guarantees to evaluate sv only once.
2400 IV SvIV(SV* sv)
2402 SvIVX Returns the raw value in the SV's IV slot, without checks or
2404 conversions. Only use when you are sure SvIOK is true. See
2405 also "SvIV()".
2406 IV SvIVX(SV* sv)
2408 SvIVx Coerces the given SV to an integer and returns it. Guarantees
2410 to evaluate "sv" only once. Only use this if "sv" is an
2411 expression with side effects, otherwise use the more efficient
2412 "SvIV".
2413 IV SvIVx(SV* sv)
2415 SvIV_nomg
2417 Like "SvIV" but doesn't process magic.
2418 IV SvIV_nomg(SV* sv)
2420 SvIV_set
2422 Set the value of the IV pointer in sv to val. It is possible
2423 to perform the same function of this macro with an lvalue
2424 assignment to "SvIVX". With future Perls, however, it will be
2425 more efficient to use "SvIV_set" instead of the lvalue
2426 assignment to "SvIVX".
2427 void SvIV_set(SV* sv, IV val)
2429 SvLEN Returns the size of the string buffer in the SV, not including
2431 any part attributable to "SvOOK". See "SvCUR".
2432 STRLEN SvLEN(SV* sv)
2434 SvLEN_set
2436 Set the actual length of the string which is in the SV. See
2437 "SvIV_set".
2438 void SvLEN_set(SV* sv, STRLEN len)
2440 SvMAGIC_set
2442 Set the value of the MAGIC pointer in sv to val. See
2443 "SvIV_set".
2444 void SvMAGIC_set(SV* sv, MAGIC* val)
2446 SvNIOK Returns a U32 value indicating whether the SV contains a
2448 number, integer or double.
2449 U32 SvNIOK(SV* sv)
2451 SvNIOKp Returns a U32 value indicating whether the SV contains a
2453 number, integer or double. Checks the private setting. Use
2454 "SvNIOK" instead.
2455 U32 SvNIOKp(SV* sv)
2457 SvNIOK_off
2459 Unsets the NV/IV status of an SV.
2460 void SvNIOK_off(SV* sv)
2462 SvNOK Returns a U32 value indicating whether the SV contains a
2464 double.
2465 U32 SvNOK(SV* sv)
2467 SvNOKp Returns a U32 value indicating whether the SV contains a
2469 double. Checks the private setting. Use "SvNOK" instead.
2470 U32 SvNOKp(SV* sv)
2472 SvNOK_off
2474 Unsets the NV status of an SV.
2475 void SvNOK_off(SV* sv)
2477 SvNOK_on
2479 Tells an SV that it is a double.
2480 void SvNOK_on(SV* sv)
2482 SvNOK_only
2484 Tells an SV that it is a double and disables all other OK bits.
2485 void SvNOK_only(SV* sv)
2487 SvNV Coerce the given SV to a double and return it. See "SvNVx" for
2489 a version which guarantees to evaluate sv only once.
2490 NV SvNV(SV* sv)
2492 SvNVX Returns the raw value in the SV's NV slot, without checks or
2494 conversions. Only use when you are sure SvNOK is true. See
2495 also "SvNV()".
2496 NV SvNVX(SV* sv)
2498 SvNVx Coerces the given SV to a double and returns it. Guarantees to
2500 evaluate "sv" only once. Only use this if "sv" is an expression
2501 with side effects, otherwise use the more efficient "SvNV".
2502 NV SvNVx(SV* sv)
2504 SvNV_set
2506 Set the value of the NV pointer in sv to val. See "SvIV_set".
2507 void SvNV_set(SV* sv, NV val)
2509 SvOK Returns a U32 value indicating whether the value is defined.
2511 This is only meaningful for scalars.
2512 U32 SvOK(SV* sv)
2514 SvOOK Returns a U32 indicating whether the SvIVX is a valid offset
2516 value for the SvPVX. This hack is used internally to speed up
2517 removal of characters from the beginning of a SvPV. When SvOOK
2518 is true, then the start of the allocated string buffer is
2519 really (SvPVX - SvIVX).
2520 U32 SvOOK(SV* sv)
2522 SvPOK Returns a U32 value indicating whether the SV contains a
2524 character string.
2525 U32 SvPOK(SV* sv)
2527 SvPOKp Returns a U32 value indicating whether the SV contains a
2529 character string. Checks the private setting. Use "SvPOK"
2530 instead.
2531 U32 SvPOKp(SV* sv)
2533 SvPOK_off
2535 Unsets the PV status of an SV.
2536 void SvPOK_off(SV* sv)
2538 SvPOK_on
2540 Tells an SV that it is a string.
2541 void SvPOK_on(SV* sv)
2543 SvPOK_only
2545 Tells an SV that it is a string and disables all other OK bits.
2546 Will also turn off the UTF-8 status.
2547 void SvPOK_only(SV* sv)
2549 SvPOK_only_UTF8
2551 Tells an SV that it is a string and disables all other OK bits,
2552 and leaves the UTF-8 status as it was.
2553 void SvPOK_only_UTF8(SV* sv)
2555 SvPV Returns a pointer to the string in the SV, or a stringified
2557 form of the SV if the SV does not contain a string. The SV may
2558 cache the stringified version becoming "SvPOK". Handles 'get'
2559 magic. See also "SvPVx" for a version which guarantees to
2560 evaluate sv only once.
2561 char* SvPV(SV* sv, STRLEN len)
2563 SvPVbyte
2565 Like "SvPV", but converts sv to byte representation first if
2566 necessary.
2567 char* SvPVbyte(SV* sv, STRLEN len)
2569 SvPVbytex
2571 Like "SvPV", but converts sv to byte representation first if
2572 necessary. Guarantees to evaluate sv only once; use the more
2573 efficient "SvPVbyte" otherwise.
2574 char* SvPVbytex(SV* sv, STRLEN len)
2576 SvPVbytex_force
2578 Like "SvPV_force", but converts sv to byte representation first
2579 if necessary. Guarantees to evaluate sv only once; use the
2580 more efficient "SvPVbyte_force" otherwise.
2581 char* SvPVbytex_force(SV* sv, STRLEN len)
2583 SvPVbyte_force
2585 Like "SvPV_force", but converts sv to byte representation first
2586 if necessary.
2587 char* SvPVbyte_force(SV* sv, STRLEN len)
2589 SvPVbyte_nolen
2591 Like "SvPV_nolen", but converts sv to byte representation first
2592 if necessary.
2593 char* SvPVbyte_nolen(SV* sv)
2595 SvPVutf8
2597 Like "SvPV", but converts sv to utf8 first if necessary.
2598 char* SvPVutf8(SV* sv, STRLEN len)
2600 SvPVutf8x
2602 Like "SvPV", but converts sv to utf8 first if necessary.
2603 Guarantees to evaluate sv only once; use the more efficient
2604 "SvPVutf8" otherwise.
2605 char* SvPVutf8x(SV* sv, STRLEN len)
2607 SvPVutf8x_force
2609 Like "SvPV_force", but converts sv to utf8 first if necessary.
2610 Guarantees to evaluate sv only once; use the more efficient
2611 "SvPVutf8_force" otherwise.
2612 char* SvPVutf8x_force(SV* sv, STRLEN len)
2614 SvPVutf8_force
2616 Like "SvPV_force", but converts sv to utf8 first if necessary.
2617 char* SvPVutf8_force(SV* sv, STRLEN len)
2619 SvPVutf8_nolen
2621 Like "SvPV_nolen", but converts sv to utf8 first if necessary.
2622 char* SvPVutf8_nolen(SV* sv)
2624 SvPVX Returns a pointer to the physical string in the SV. The SV
2626 must contain a string.
2627 char* SvPVX(SV* sv)
2629 SvPVx A version of "SvPV" which guarantees to evaluate "sv" only
2631 once. Only use this if "sv" is an expression with side
2632 effects, otherwise use the more efficient "SvPVX".
2633 char* SvPVx(SV* sv, STRLEN len)
2635 SvPV_force
2637 Like "SvPV" but will force the SV into containing just a string
2638 ("SvPOK_only"). You want force if you are going to update the
2639 "SvPVX" directly.
2640 char* SvPV_force(SV* sv, STRLEN len)
2642 SvPV_force_nomg
2644 Like "SvPV" but will force the SV into containing just a string
2645 ("SvPOK_only"). You want force if you are going to update the
2646 "SvPVX" directly. Doesn't process magic.
2647 char* SvPV_force_nomg(SV* sv, STRLEN len)
2649 SvPV_nolen
2651 Returns a pointer to the string in the SV, or a stringified
2652 form of the SV if the SV does not contain a string. The SV may
2653 cache the stringified form becoming "SvPOK". Handles 'get'
2654 magic.
2655 char* SvPV_nolen(SV* sv)
2657 SvPV_nomg
2659 Like "SvPV" but doesn't process magic.
2660 char* SvPV_nomg(SV* sv, STRLEN len)
2662 SvPV_set
2664 Set the value of the PV pointer in sv to val. See "SvIV_set".
2665 void SvPV_set(SV* sv, char* val)
2667 SvREFCNT
2669 Returns the value of the object's reference count.
2670 U32 SvREFCNT(SV* sv)
2672 SvREFCNT_dec
2674 Decrements the reference count of the given SV.
2675 void SvREFCNT_dec(SV* sv)
2677 SvREFCNT_inc
2679 Increments the reference count of the given SV.
2680 All of the following SvREFCNT_inc* macros are optimized
2682 versions of SvREFCNT_inc, and can be replaced with
2683 SvREFCNT_inc.
2684 SV* SvREFCNT_inc(SV* sv)
2686 SvREFCNT_inc_NN
2688 Same as SvREFCNT_inc, but can only be used if you know sv is
2689 not NULL. Since we don't have to check the NULLness, it's
2690 faster and smaller.
2691 SV* SvREFCNT_inc_NN(SV* sv)
2693 SvREFCNT_inc_simple
2695 Same as SvREFCNT_inc, but can only be used with expressions
2696 without side effects. Since we don't have to store a temporary
2697 value, it's faster.
2698 SV* SvREFCNT_inc_simple(SV* sv)
2700 SvREFCNT_inc_simple_NN
2702 Same as SvREFCNT_inc_simple, but can only be used if you know
2703 sv is not NULL. Since we don't have to check the NULLness,
2704 it's faster and smaller.
2705 SV* SvREFCNT_inc_simple_NN(SV* sv)
2707 SvREFCNT_inc_simple_void
2709 Same as SvREFCNT_inc_simple, but can only be used if you don't
2710 need the return value. The macro doesn't need to return a
2711 meaningful value.
2712 void SvREFCNT_inc_simple_void(SV* sv)
2714 SvREFCNT_inc_simple_void_NN
2716 Same as SvREFCNT_inc, but can only be used if you don't need
2717 the return value, and you know that sv is not NULL. The macro
2718 doesn't need to return a meaningful value, or check for
2719 NULLness, so it's smaller and faster.
2720 void SvREFCNT_inc_simple_void_NN(SV* sv)
2722 SvREFCNT_inc_void
2724 Same as SvREFCNT_inc, but can only be used if you don't need
2725 the return value. The macro doesn't need to return a
2726 meaningful value.
2727 void SvREFCNT_inc_void(SV* sv)
2729 SvREFCNT_inc_void_NN
2731 Same as SvREFCNT_inc, but can only be used if you don't need
2732 the return value, and you know that sv is not NULL. The macro
2733 doesn't need to return a meaningful value, or check for
2734 NULLness, so it's smaller and faster.
2735 void SvREFCNT_inc_void_NN(SV* sv)
2737 SvROK Tests if the SV is an RV.
2739 U32 SvROK(SV* sv)
2741 SvROK_off
2743 Unsets the RV status of an SV.
2744 void SvROK_off(SV* sv)
2746 SvROK_on
2748 Tells an SV that it is an RV.
2749 void SvROK_on(SV* sv)
2751 SvRV Dereferences an RV to return the SV.
2753 SV* SvRV(SV* sv)
2755 SvRV_set
2757 Set the value of the RV pointer in sv to val. See "SvIV_set".
2758 void SvRV_set(SV* sv, SV* val)
2760 SvSTASH Returns the stash of the SV.
2762 HV* SvSTASH(SV* sv)
2764 SvSTASH_set
2766 Set the value of the STASH pointer in sv to val. See
2767 "SvIV_set".
2768 void SvSTASH_set(SV* sv, HV* val)
2770 SvTAINT Taints an SV if tainting is enabled.
2772 void SvTAINT(SV* sv)
2774 SvTAINTED
2776 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE
2777 if not.
2778 bool SvTAINTED(SV* sv)
2780 SvTAINTED_off
2782 Untaints an SV. Be very careful with this routine, as it short-
2783 circuits some of Perl's fundamental security features. XS
2784 module authors should not use this function unless they fully
2785 understand all the implications of unconditionally untainting
2786 the value. Untainting should be done in the standard perl
2787 fashion, via a carefully crafted regexp, rather than directly
2788 untainting variables.
2789 void SvTAINTED_off(SV* sv)
2791 SvTAINTED_on
2793 Marks an SV as tainted if tainting is enabled.
2794 void SvTAINTED_on(SV* sv)
2796 SvTRUE Returns a boolean indicating whether Perl would evaluate the SV
2798 as true or false. See SvOK() for a defined/undefined test.
2799 Does not handle 'get' magic.
2800 bool SvTRUE(SV* sv)
2802 SvTYPE Returns the type of the SV. See "svtype".
2804 svtype SvTYPE(SV* sv)
2806 SvUOK Returns a boolean indicating whether the SV contains an
2808 unsigned integer.
2809 bool SvUOK(SV* sv)
2811 SvUPGRADE
2813 Used to upgrade an SV to a more complex form. Uses
2814 "sv_upgrade" to perform the upgrade if necessary. See
2815 "svtype".
2816 void SvUPGRADE(SV* sv, svtype type)
2818 SvUTF8 Returns a U32 value indicating whether the SV contains UTF-8
2820 encoded data. Call this after SvPV() in case any call to
2821 string overloading updates the internal flag.
2822 U32 SvUTF8(SV* sv)
2824 SvUTF8_off
2826 Unsets the UTF-8 status of an SV.
2827 void SvUTF8_off(SV *sv)
2829 SvUTF8_on
2831 Turn on the UTF-8 status of an SV (the data is not changed,
2832 just the flag). Do not use frivolously.
2833 void SvUTF8_on(SV *sv)
2835 SvUV Coerces the given SV to an unsigned integer and returns it.
2837 See "SvUVx" for a version which guarantees to evaluate sv only
2838 once.
2839 UV SvUV(SV* sv)
2841 SvUVX Returns the raw value in the SV's UV slot, without checks or
2843 conversions. Only use when you are sure SvIOK is true. See
2844 also "SvUV()".
2845 UV SvUVX(SV* sv)
2847 SvUVx Coerces the given SV to an unsigned integer and returns it.
2849 Guarantees to "sv" only once. Only use this if "sv" is an
2850 expression with side effects, otherwise use the more efficient
2851 "SvUV".
2852 UV SvUVx(SV* sv)
2854 SvUV_nomg
2856 Like "SvUV" but doesn't process magic.
2857 UV SvUV_nomg(SV* sv)
2859 SvUV_set
2861 Set the value of the UV pointer in sv to val. See "SvIV_set".
2862 void SvUV_set(SV* sv, UV val)
2864 SvVOK Returns a boolean indicating whether the SV contains a
2866 v-string.
2867 bool SvVOK(SV* sv)
2869 sv_catpvn_nomg
2871 Like "sv_catpvn" but doesn't process magic.
2872 void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
2874 sv_catsv_nomg
2876 Like "sv_catsv" but doesn't process magic.
2877 void sv_catsv_nomg(SV* dsv, SV* ssv)
2879 sv_derived_from
2881 Returns a boolean indicating whether the SV is derived from the
2882 specified class at the C level. To check derivation at the
2883 Perl level, call "isa()" as a normal Perl method.
2884 bool sv_derived_from(SV* sv, const char* name)
2886 sv_does Returns a boolean indicating whether the SV performs a
2888 specific, named role. The SV can be a Perl object or the name
2889 of a Perl class.
2890 bool sv_does(SV* sv, const char* name)
2892 sv_report_used
2894 Dump the contents of all SVs not yet freed. (Debugging aid).
2895 void sv_report_used()
2897 sv_setsv_nomg
2899 Like "sv_setsv" but doesn't process magic.
2900 void sv_setsv_nomg(SV* dsv, SV* ssv)
2902 sv_utf8_upgrade_nomg
2904 Like sv_utf8_upgrade, but doesn't do magic on "sv"
2905 STRLEN sv_utf8_upgrade_nomg(NN SV *sv)
2907
2909 looks_like_number
2910 Test if the content of an SV looks like a number (or is a
2911 number). "Inf" and "Infinity" are treated as numbers (so will
2912 not issue a non-numeric warning), even if your atof() doesn't
2913 grok them.
2914 I32 looks_like_number(SV* sv)
2916 newRV_noinc
2918 Creates an RV wrapper for an SV. The reference count for the
2919 original SV is not incremented.
2920 SV* newRV_noinc(SV* sv)
2922 newSV Creates a new SV. A non-zero "len" parameter indicates the
2924 number of bytes of preallocated string space the SV should
2925 have. An extra byte for a trailing NUL is also reserved.
2926 (SvPOK is not set for the SV even if string space is
2927 allocated.) The reference count for the new SV is set to 1.
2928 In 5.9.3, newSV() replaces the older NEWSV() API, and drops the
2930 first parameter, x, a debug aid which allowed callers to
2931 identify themselves. This aid has been superseded by a new
2932 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhack).
2933 The older API is still there for use in XS modules supporting
2934 older perls.
2935 SV* newSV(STRLEN len)
2937 newSVhek
2939 Creates a new SV from the hash key structure. It will generate
2940 scalars that point to the shared string table where possible.
2941 Returns a new (undefined) SV if the hek is NULL.
2942 SV* newSVhek(const HEK *hek)
2944 newSViv Creates a new SV and copies an integer into it. The reference
2946 count for the SV is set to 1.
2947 SV* newSViv(IV i)
2949 newSVnv Creates a new SV and copies a floating point value into it.
2951 The reference count for the SV is set to 1.
2952 SV* newSVnv(NV n)
2954 newSVpv Creates a new SV and copies a string into it. The reference
2956 count for the SV is set to 1. If "len" is zero, Perl will
2957 compute the length using strlen(). For efficiency, consider
2958 using "newSVpvn" instead.
2959 SV* newSVpv(const char* s, STRLEN len)
2961 newSVpvf
2963 Creates a new SV and initializes it with the string formatted
2964 like "sprintf".
2965 SV* newSVpvf(const char* pat, ...)
2967 newSVpvn
2969 Creates a new SV and copies a string into it. The reference
2970 count for the SV is set to 1. Note that if "len" is zero, Perl
2971 will create a zero length string. You are responsible for
2972 ensuring that the source string is at least "len" bytes long.
2973 If the "s" argument is NULL the new SV will be undefined.
2974 SV* newSVpvn(const char* s, STRLEN len)
2976 newSVpvn_flags
2978 Creates a new SV and copies a string into it. The reference
2979 count for the SV is set to 1. Note that if "len" is zero, Perl
2980 will create a zero length string. You are responsible for
2981 ensuring that the source string is at least "len" bytes long.
2982 If the "s" argument is NULL the new SV will be undefined.
2983 Currently the only flag bits accepted are "SVf_UTF8" and
2984 "SVs_TEMP". If "SVs_TEMP" is set, then "sv2mortal()" is called
2985 on the result before returning. If "SVf_UTF8" is set, then it
2986 will be set on the new SV. "newSVpvn_utf8()" is a convenience
2987 wrapper for this function, defined as
2988 #define newSVpvn_utf8(s, len, u) \
2990 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
2991 SV* newSVpvn_flags(const char* s, STRLEN len, U32 flags)
2993 newSVpvn_share
2995 Creates a new SV with its SvPVX_const pointing to a shared
2996 string in the string table. If the string does not already
2997 exist in the table, it is created first. Turns on READONLY and
2998 FAKE. If the "hash" parameter is non-zero, that value is used;
2999 otherwise the hash is computed. The string's hash can be later
3000 be retrieved from the SV with the "SvSHARED_HASH()" macro. The
3001 idea here is that as the string table is used for shared hash
3002 keys these strings will have SvPVX_const == HeKEY and hash
3003 lookup will avoid string compare.
3004 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
3006 newSVpvs
3008 Like "newSVpvn", but takes a literal string instead of a
3009 string/length pair.
3010 SV* newSVpvs(const char* s)
3012 newSVpvs_flags
3014 Like "newSVpvn_flags", but takes a literal string instead of a
3015 string/length pair.
3016 SV* newSVpvs_flags(const char* s, U32 flags)
3018 newSVpvs_share
3020 Like "newSVpvn_share", but takes a literal string instead of a
3021 string/length pair and omits the hash parameter.
3022 SV* newSVpvs_share(const char* s)
3024 newSVrv Creates a new SV for the RV, "rv", to point to. If "rv" is not
3026 an RV then it will be upgraded to one. If "classname" is non-
3027 null then the new SV will be blessed in the specified package.
3028 The new SV is returned and its reference count is 1.
3029 SV* newSVrv(SV* rv, const char* classname)
3031 newSVsv Creates a new SV which is an exact duplicate of the original
3033 SV. (Uses "sv_setsv").
3034 SV* newSVsv(SV* old)
3036 newSVuv Creates a new SV and copies an unsigned integer into it. The
3038 reference count for the SV is set to 1.
3039 SV* newSVuv(UV u)
3041 newSV_type
3043 Creates a new SV, of the type specified. The reference count
3044 for the new SV is set to 1.
3045 SV* newSV_type(svtype type)
3047 sv_2bool
3049 This function is only called on magical items, and is only used
3050 by sv_true() or its macro equivalent.
3051 bool sv_2bool(SV* sv)
3053 sv_2cv Using various gambits, try to get a CV from an SV; in addition,
3055 try if possible to set *st and *gvp to the stash and GV
3056 associated with it. The flags in "lref" are passed to
3057 sv_fetchsv.
3058 CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
3060 sv_2io Using various gambits, try to get an IO from an SV: the IO slot
3062 if its a GV; or the recursive result if we're an RV; or the IO
3063 slot of the symbol named after the PV if we're a string.
3064 IO* sv_2io(SV* sv)
3066 sv_2iv_flags
3068 Return the integer value of an SV, doing any necessary string
3069 conversion. If flags includes SV_GMAGIC, does an mg_get()
3070 first. Normally used via the "SvIV(sv)" and "SvIVx(sv)"
3071 macros.
3072 IV sv_2iv_flags(SV* sv, I32 flags)
3074 sv_2mortal
3076 Marks an existing SV as mortal. The SV will be destroyed
3077 "soon", either by an explicit call to FREETMPS, or by an
3078 implicit call at places such as statement boundaries. SvTEMP()
3079 is turned on which means that the SV's string buffer can be
3080 "stolen" if this SV is copied. See also "sv_newmortal" and
3081 "sv_mortalcopy".
3082 SV* sv_2mortal(SV* sv)
3084 sv_2nv Return the num value of an SV, doing any necessary string or
3086 integer conversion, magic etc. Normally used via the "SvNV(sv)"
3087 and "SvNVx(sv)" macros.
3088 NV sv_2nv(SV* sv)
3090 sv_2pvbyte
3092 Return a pointer to the byte-encoded representation of the SV,
3093 and set *lp to its length. May cause the SV to be downgraded
3094 from UTF-8 as a side-effect.
3095 Usually accessed via the "SvPVbyte" macro.
3097 char* sv_2pvbyte(SV* sv, STRLEN* lp)
3099 sv_2pvutf8
3101 Return a pointer to the UTF-8-encoded representation of the SV,
3102 and set *lp to its length. May cause the SV to be upgraded to
3103 UTF-8 as a side-effect.
3104 Usually accessed via the "SvPVutf8" macro.
3106 char* sv_2pvutf8(SV* sv, STRLEN* lp)
3108 sv_2pv_flags
3110 Returns a pointer to the string value of an SV, and sets *lp to
3111 its length. If flags includes SV_GMAGIC, does an mg_get()
3112 first. Coerces sv to a string if necessary. Normally invoked
3113 via the "SvPV_flags" macro. "sv_2pv()" and "sv_2pv_nomg"
3114 usually end up here too.
3115 char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
3117 sv_2uv_flags
3119 Return the unsigned integer value of an SV, doing any necessary
3120 string conversion. If flags includes SV_GMAGIC, does an
3121 mg_get() first. Normally used via the "SvUV(sv)" and
3122 "SvUVx(sv)" macros.
3123 UV sv_2uv_flags(SV* sv, I32 flags)
3125 sv_backoff
3127 Remove any string offset. You should normally use the
3128 "SvOOK_off" macro wrapper instead.
3129 int sv_backoff(SV* sv)
3131 sv_bless
3133 Blesses an SV into a specified package. The SV must be an RV.
3134 The package must be designated by its stash (see
3135 "gv_stashpv()"). The reference count of the SV is unaffected.
3136 SV* sv_bless(SV* sv, HV* stash)
3138 sv_catpv
3140 Concatenates the string onto the end of the string which is in
3141 the SV. If the SV has the UTF-8 status set, then the bytes
3142 appended should be valid UTF-8. Handles 'get' magic, but not
3143 'set' magic. See "sv_catpv_mg".
3144 void sv_catpv(SV* sv, const char* ptr)
3146 sv_catpvf
3148 Processes its arguments like "sprintf" and appends the
3149 formatted output to an SV. If the appended data contains
3150 "wide" characters (including, but not limited to, SVs with a
3151 UTF-8 PV formatted with %s, and characters >255 formatted with
3152 %c), the original SV might get upgraded to UTF-8. Handles
3153 'get' magic, but not 'set' magic. See "sv_catpvf_mg". If the
3154 original SV was UTF-8, the pattern should be valid UTF-8; if
3155 the original SV was bytes, the pattern should be too.
3156 void sv_catpvf(SV* sv, const char* pat, ...)
3158 sv_catpvf_mg
3160 Like "sv_catpvf", but also handles 'set' magic.
3161 void sv_catpvf_mg(SV *sv, const char* pat, ...)
3163 sv_catpvn
3165 Concatenates the string onto the end of the string which is in
3166 the SV. The "len" indicates number of bytes to copy. If the
3167 SV has the UTF-8 status set, then the bytes appended should be
3168 valid UTF-8. Handles 'get' magic, but not 'set' magic. See
3169 "sv_catpvn_mg".
3170 void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
3172 sv_catpvn_flags
3174 Concatenates the string onto the end of the string which is in
3175 the SV. The "len" indicates number of bytes to copy. If the
3176 SV has the UTF-8 status set, then the bytes appended should be
3177 valid UTF-8. If "flags" has "SV_GMAGIC" bit set, will "mg_get"
3178 on "dsv" if appropriate, else not. "sv_catpvn" and
3179 "sv_catpvn_nomg" are implemented in terms of this function.
3180 void sv_catpvn_flags(SV *dstr, const char *sstr, STRLEN len, I32 flags)
3182 sv_catpvs
3184 Like "sv_catpvn", but takes a literal string instead of a
3185 string/length pair.
3186 void sv_catpvs(SV* sv, const char* s)
3188 sv_catpv_mg
3190 Like "sv_catpv", but also handles 'set' magic.
3191 void sv_catpv_mg(SV *sv, const char *ptr)
3193 sv_catsv
3195 Concatenates the string from SV "ssv" onto the end of the
3196 string in SV "dsv". Modifies "dsv" but not "ssv". Handles
3197 'get' magic, but not 'set' magic. See "sv_catsv_mg".
3198 void sv_catsv(SV *dstr, SV *sstr)
3200 sv_catsv_flags
3202 Concatenates the string from SV "ssv" onto the end of the
3203 string in SV "dsv". Modifies "dsv" but not "ssv". If "flags"
3204 has "SV_GMAGIC" bit set, will "mg_get" on the SVs if
3205 appropriate, else not. "sv_catsv" and "sv_catsv_nomg" are
3206 implemented in terms of this function.
3207 void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
3209 sv_chop Efficient removal of characters from the beginning of the
3211 string buffer. SvPOK(sv) must be true and the "ptr" must be a
3212 pointer to somewhere inside the string buffer. The "ptr"
3213 becomes the first character of the adjusted string. Uses the
3214 "OOK hack". Beware: after this function returns, "ptr" and
3215 SvPVX_const(sv) may no longer refer to the same chunk of data.
3216 void sv_chop(SV* sv, const char* ptr)
3218 sv_clear
3220 Clear an SV: call any destructors, free up any memory used by
3221 the body, and free the body itself. The SV's head is not freed,
3222 although its type is set to all 1's so that it won't
3223 inadvertently be assumed to be live during global destruction
3224 etc. This function should only be called when REFCNT is zero.
3225 Most of the time you'll want to call "sv_free()" (or its macro
3226 wrapper "SvREFCNT_dec") instead.
3227 void sv_clear(SV* sv)
3229 sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1
3231 indicating whether the string in "sv1" is less than, equal to,
3232 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
3233 aware, handles get magic, and will coerce its args to strings
3234 if necessary. See also "sv_cmp_locale".
3235 I32 sv_cmp(SV* sv1, SV* sv2)
3237 sv_cmp_locale
3239 Compares the strings in two SVs in a locale-aware manner. Is
3240 UTF-8 and 'use bytes' aware, handles get magic, and will coerce
3241 its args to strings if necessary. See also "sv_cmp".
3242 I32 sv_cmp_locale(SV* sv1, SV* sv2)
3244 sv_collxfrm
3246 Add Collate Transform magic to an SV if it doesn't already have
3247 it.
3248 Any scalar variable may carry PERL_MAGIC_collxfrm magic that
3250 contains the scalar data of the variable, but transformed to
3251 such a format that a normal memory comparison can be used to
3252 compare the data according to the locale settings.
3253 char* sv_collxfrm(SV* sv, STRLEN* nxp)
3255 sv_copypv
3257 Copies a stringified representation of the source SV into the
3258 destination SV. Automatically performs any necessary mg_get
3259 and coercion of numeric values into strings. Guaranteed to
3260 preserve UTF8 flag even from overloaded objects. Similar in
3261 nature to sv_2pv[_flags] but operates directly on an SV instead
3262 of just the string. Mostly uses sv_2pv_flags to do its work,
3263 except when that would lose the UTF-8'ness of the PV.
3264 void sv_copypv(SV* dsv, SV* ssv)
3266 sv_dec Auto-decrement of the value in the SV, doing string to numeric
3268 conversion if necessary. Handles 'get' magic.
3269 void sv_dec(SV* sv)
3271 sv_eq Returns a boolean indicating whether the strings in the two SVs
3273 are identical. Is UTF-8 and 'use bytes' aware, handles get
3274 magic, and will coerce its args to strings if necessary.
3275 I32 sv_eq(SV* sv1, SV* sv2)
3277 sv_force_normal_flags
3279 Undo various types of fakery on an SV: if the PV is a shared
3280 string, make a private copy; if we're a ref, stop refing; if
3281 we're a glob, downgrade to an xpvmg; if we're a copy-on-write
3282 scalar, this is the on-write time when we do the copy, and is
3283 also used locally. If "SV_COW_DROP_PV" is set then a copy-on-
3284 write scalar drops its PV buffer (if any) and becomes SvPOK_off
3285 rather than making a copy. (Used where this scalar is about to
3286 be set to some other value.) In addition, the "flags" parameter
3287 gets passed to "sv_unref_flags()" when unrefing.
3288 "sv_force_normal" calls this function with flags set to 0.
3289 void sv_force_normal_flags(SV *sv, U32 flags)
3291 sv_free Decrement an SV's reference count, and if it drops to zero,
3293 call "sv_clear" to invoke destructors and free up any memory
3294 used by the body; finally, deallocate the SV's head itself.
3295 Normally called via a wrapper macro "SvREFCNT_dec".
3296 void sv_free(SV* sv)
3298 sv_gets Get a line from the filehandle and store it into the SV,
3300 optionally appending to the currently-stored string.
3301 char* sv_gets(SV* sv, PerlIO* fp, I32 append)
3303 sv_grow Expands the character buffer in the SV. If necessary, uses
3305 "sv_unref" and upgrades the SV to "SVt_PV". Returns a pointer
3306 to the character buffer. Use the "SvGROW" wrapper instead.
3307 char* sv_grow(SV* sv, STRLEN newlen)
3309 sv_inc Auto-increment of the value in the SV, doing string to numeric
3311 conversion if necessary. Handles 'get' magic.
3312 void sv_inc(SV* sv)
3314 sv_insert
3316 Inserts a string at the specified offset/length within the SV.
3317 Similar to the Perl substr() function. Handles get magic.
3318 void sv_insert(SV *bigstr, STRLEN offset, STRLEN len, const char *little, STRLEN littlelen)
3320 sv_insert_flags
3322 Same as "sv_insert", but the extra "flags" are passed the
3323 "SvPV_force_flags" that applies to "bigstr".
3324 void sv_insert_flags(SV *const bigstr, const STRLEN offset, const STRLEN len, const char *const little, const STRLEN littlelen, const U32 flags)
3326 sv_isa Returns a boolean indicating whether the SV is blessed into the
3328 specified class. This does not check for subtypes; use
3329 "sv_derived_from" to verify an inheritance relationship.
3330 int sv_isa(SV* sv, const char* name)
3332 sv_isobject
3334 Returns a boolean indicating whether the SV is an RV pointing
3335 to a blessed object. If the SV is not an RV, or if the object
3336 is not blessed, then this will return false.
3337 int sv_isobject(SV* sv)
3339 sv_len Returns the length of the string in the SV. Handles magic and
3341 type coercion. See also "SvCUR", which gives raw access to the
3342 xpv_cur slot.
3343 STRLEN sv_len(SV* sv)
3345 sv_len_utf8
3347 Returns the number of characters in the string in an SV,
3348 counting wide UTF-8 bytes as a single character. Handles magic
3349 and type coercion.
3350 STRLEN sv_len_utf8(SV* sv)
3352 sv_magic
3354 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
3355 necessary, then adds a new magic item of type "how" to the head
3356 of the magic list.
3357 See "sv_magicext" (which "sv_magic" now calls) for a
3359 description of the handling of the "name" and "namlen"
3360 arguments.
3361 You need to use "sv_magicext" to add magic to SvREADONLY SVs
3363 and also to add more than one instance of the same 'how'.
3364 void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
3366 sv_magicext
3368 Adds magic to an SV, upgrading it if necessary. Applies the
3369 supplied vtable and returns a pointer to the magic added.
3370 Note that "sv_magicext" will allow things that "sv_magic" will
3372 not. In particular, you can add magic to SvREADONLY SVs, and
3373 add more than one instance of the same 'how'.
3374 If "namlen" is greater than zero then a "savepvn" copy of
3376 "name" is stored, if "namlen" is zero then "name" is stored as-
3377 is and - as another special case - if "(name && namlen ==
3378 HEf_SVKEY)" then "name" is assumed to contain an "SV*" and is
3379 stored as-is with its REFCNT incremented.
3380 (This is now used as a subroutine by "sv_magic".)
3382 MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen)
3384 sv_mortalcopy
3386 Creates a new SV which is a copy of the original SV (using
3387 "sv_setsv"). The new SV is marked as mortal. It will be
3388 destroyed "soon", either by an explicit call to FREETMPS, or by
3389 an implicit call at places such as statement boundaries. See
3390 also "sv_newmortal" and "sv_2mortal".
3391 SV* sv_mortalcopy(SV* oldsv)
3393 sv_newmortal
3395 Creates a new null SV which is mortal. The reference count of
3396 the SV is set to 1. It will be destroyed "soon", either by an
3397 explicit call to FREETMPS, or by an implicit call at places
3398 such as statement boundaries. See also "sv_mortalcopy" and
3399 "sv_2mortal".
3400 SV* sv_newmortal()
3402 sv_newref
3404 Increment an SV's reference count. Use the "SvREFCNT_inc()"
3405 wrapper instead.
3406 SV* sv_newref(SV* sv)
3408 sv_pos_b2u
3410 Converts the value pointed to by offsetp from a count of bytes
3411 from the start of the string, to a count of the equivalent
3412 number of UTF-8 chars. Handles magic and type coercion.
3413 void sv_pos_b2u(SV* sv, I32* offsetp)
3415 sv_pos_u2b
3417 Converts the value pointed to by offsetp from a count of UTF-8
3418 chars from the start of the string, to a count of the
3419 equivalent number of bytes; if lenp is non-zero, it does the
3420 same to lenp, but this time starting from the offset, rather
3421 than from the start of the string. Handles magic and type
3422 coercion.
3423 void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
3425 sv_pvbyten_force
3427 The backend for the "SvPVbytex_force" macro. Always use the
3428 macro instead.
3429 char* sv_pvbyten_force(SV* sv, STRLEN* lp)
3431 sv_pvn_force
3433 Get a sensible string out of the SV somehow. A private
3434 implementation of the "SvPV_force" macro for compilers which
3435 can't cope with complex macro expressions. Always use the macro
3436 instead.
3437 char* sv_pvn_force(SV* sv, STRLEN* lp)
3439 sv_pvn_force_flags
3441 Get a sensible string out of the SV somehow. If "flags" has
3442 "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate, else
3443 not. "sv_pvn_force" and "sv_pvn_force_nomg" are implemented in
3444 terms of this function. You normally want to use the various
3445 wrapper macros instead: see "SvPV_force" and "SvPV_force_nomg"
3446 char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
3448 sv_pvutf8n_force
3450 The backend for the "SvPVutf8x_force" macro. Always use the
3451 macro instead.
3452 char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
3454 sv_reftype
3456 Returns a string describing what the SV is a reference to.
3457 const char* sv_reftype(const SV* sv, int ob)
3459 sv_replace
3461 Make the first argument a copy of the second, then delete the
3462 original. The target SV physically takes over ownership of the
3463 body of the source SV and inherits its flags; however, the
3464 target keeps any magic it owns, and any magic in the source is
3465 discarded. Note that this is a rather specialist SV copying
3466 operation; most of the time you'll want to use "sv_setsv" or
3467 one of its many macro front-ends.
3468 void sv_replace(SV* sv, SV* nsv)
3470 sv_reset
3472 Underlying implementation for the "reset" Perl function. Note
3473 that the perl-level function is vaguely deprecated.
3474 void sv_reset(const char* s, HV* stash)
3476 sv_rvweaken
3478 Weaken a reference: set the "SvWEAKREF" flag on this RV; give
3479 the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
3480 already; and push a back-reference to this RV onto the array of
3481 backreferences associated with that magic. If the RV is
3482 magical, set magic will be called after the RV is cleared.
3483 SV* sv_rvweaken(SV *sv)
3485 sv_setiv
3487 Copies an integer into the given SV, upgrading first if
3488 necessary. Does not handle 'set' magic. See also
3489 "sv_setiv_mg".
3490 void sv_setiv(SV* sv, IV num)
3492 sv_setiv_mg
3494 Like "sv_setiv", but also handles 'set' magic.
3495 void sv_setiv_mg(SV *sv, IV i)
3497 sv_setnv
3499 Copies a double into the given SV, upgrading first if
3500 necessary. Does not handle 'set' magic. See also
3501 "sv_setnv_mg".
3502 void sv_setnv(SV* sv, NV num)
3504 sv_setnv_mg
3506 Like "sv_setnv", but also handles 'set' magic.
3507 void sv_setnv_mg(SV *sv, NV num)
3509 sv_setpv
3511 Copies a string into an SV. The string must be null-
3512 terminated. Does not handle 'set' magic. See "sv_setpv_mg".
3513 void sv_setpv(SV* sv, const char* ptr)
3515 sv_setpvf
3517 Works like "sv_catpvf" but copies the text into the SV instead
3518 of appending it. Does not handle 'set' magic. See
3519 "sv_setpvf_mg".
3520 void sv_setpvf(SV* sv, const char* pat, ...)
3522 sv_setpvf_mg
3524 Like "sv_setpvf", but also handles 'set' magic.
3525 void sv_setpvf_mg(SV *sv, const char* pat, ...)
3527 sv_setpviv
3529 Copies an integer into the given SV, also updating its string
3530 value. Does not handle 'set' magic. See "sv_setpviv_mg".
3531 void sv_setpviv(SV* sv, IV num)
3533 sv_setpviv_mg
3535 Like "sv_setpviv", but also handles 'set' magic.
3536 void sv_setpviv_mg(SV *sv, IV iv)
3538 sv_setpvn
3540 Copies a string into an SV. The "len" parameter indicates the
3541 number of bytes to be copied. If the "ptr" argument is NULL
3542 the SV will become undefined. Does not handle 'set' magic.
3543 See "sv_setpvn_mg".
3544 void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
3546 sv_setpvn_mg
3548 Like "sv_setpvn", but also handles 'set' magic.
3549 void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
3551 sv_setpvs
3553 Like "sv_setpvn", but takes a literal string instead of a
3554 string/length pair.
3555 void sv_setpvs(SV* sv, const char* s)
3557 sv_setpv_mg
3559 Like "sv_setpv", but also handles 'set' magic.
3560 void sv_setpv_mg(SV *sv, const char *ptr)
3562 sv_setref_iv
3564 Copies an integer into a new SV, optionally blessing the SV.
3565 The "rv" argument will be upgraded to an RV. That RV will be
3566 modified to point to the new SV. The "classname" argument
3567 indicates the package for the blessing. Set "classname" to
3568 "NULL" to avoid the blessing. The new SV will have a reference
3569 count of 1, and the RV will be returned.
3570 SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
3572 sv_setref_nv
3574 Copies a double into a new SV, optionally blessing the SV. The
3575 "rv" argument will be upgraded to an RV. That RV will be
3576 modified to point to the new SV. The "classname" argument
3577 indicates the package for the blessing. Set "classname" to
3578 "NULL" to avoid the blessing. The new SV will have a reference
3579 count of 1, and the RV will be returned.
3580 SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
3582 sv_setref_pv
3584 Copies a pointer into a new SV, optionally blessing the SV.
3585 The "rv" argument will be upgraded to an RV. That RV will be
3586 modified to point to the new SV. If the "pv" argument is NULL
3587 then "PL_sv_undef" will be placed into the SV. The "classname"
3588 argument indicates the package for the blessing. Set
3589 "classname" to "NULL" to avoid the blessing. The new SV will
3590 have a reference count of 1, and the RV will be returned.
3591 Do not use with other Perl types such as HV, AV, SV, CV,
3593 because those objects will become corrupted by the pointer copy
3594 process.
3595 Note that "sv_setref_pvn" copies the string while this copies
3597 the pointer.
3598 SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
3600 sv_setref_pvn
3602 Copies a string into a new SV, optionally blessing the SV. The
3603 length of the string must be specified with "n". The "rv"
3604 argument will be upgraded to an RV. That RV will be modified
3605 to point to the new SV. The "classname" argument indicates the
3606 package for the blessing. Set "classname" to "NULL" to avoid
3607 the blessing. The new SV will have a reference count of 1, and
3608 the RV will be returned.
3609 Note that "sv_setref_pv" copies the pointer while this copies
3611 the string.
3612 SV* sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n)
3614 sv_setref_uv
3616 Copies an unsigned integer into a new SV, optionally blessing
3617 the SV. The "rv" argument will be upgraded to an RV. That RV
3618 will be modified to point to the new SV. The "classname"
3619 argument indicates the package for the blessing. Set
3620 "classname" to "NULL" to avoid the blessing. The new SV will
3621 have a reference count of 1, and the RV will be returned.
3622 SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
3624 sv_setsv
3626 Copies the contents of the source SV "ssv" into the destination
3627 SV "dsv". The source SV may be destroyed if it is mortal, so
3628 don't use this function if the source SV needs to be reused.
3629 Does not handle 'set' magic. Loosely speaking, it performs a
3630 copy-by-value, obliterating any previous content of the
3631 destination.
3632 You probably want to use one of the assortment of wrappers,
3634 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
3635 "SvSetMagicSV_nosteal".
3636 void sv_setsv(SV *dstr, SV *sstr)
3638 sv_setsv_flags
3640 Copies the contents of the source SV "ssv" into the destination
3641 SV "dsv". The source SV may be destroyed if it is mortal, so
3642 don't use this function if the source SV needs to be reused.
3643 Does not handle 'set' magic. Loosely speaking, it performs a
3644 copy-by-value, obliterating any previous content of the
3645 destination. If the "flags" parameter has the "SV_GMAGIC" bit
3646 set, will "mg_get" on "ssv" if appropriate, else not. If the
3647 "flags" parameter has the "NOSTEAL" bit set then the buffers of
3648 temps will not be stolen. <sv_setsv> and "sv_setsv_nomg" are
3649 implemented in terms of this function.
3650 You probably want to use one of the assortment of wrappers,
3652 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
3653 "SvSetMagicSV_nosteal".
3654 This is the primary function for copying scalars, and most
3656 other copy-ish functions and macros use this underneath.
3657 void sv_setsv_flags(SV *dstr, SV *sstr, I32 flags)
3659 sv_setsv_mg
3661 Like "sv_setsv", but also handles 'set' magic.
3662 void sv_setsv_mg(SV *dstr, SV *sstr)
3664 sv_setuv
3666 Copies an unsigned integer into the given SV, upgrading first
3667 if necessary. Does not handle 'set' magic. See also
3668 "sv_setuv_mg".
3669 void sv_setuv(SV* sv, UV num)
3671 sv_setuv_mg
3673 Like "sv_setuv", but also handles 'set' magic.
3674 void sv_setuv_mg(SV *sv, UV u)
3676 sv_tainted
3678 Test an SV for taintedness. Use "SvTAINTED" instead.
3679 bool sv_tainted(SV* sv)
3680 sv_true Returns true if the SV has a true value by Perl's rules. Use
3682 the "SvTRUE" macro instead, which may call "sv_true()" or may
3683 instead use an in-line version.
3684 I32 sv_true(SV *sv)
3686 sv_unmagic
3688 Removes all magic of type "type" from an SV.
3689 int sv_unmagic(SV* sv, int type)
3691 sv_unref_flags
3693 Unsets the RV status of the SV, and decrements the reference
3694 count of whatever was being referenced by the RV. This can
3695 almost be thought of as a reversal of "newSVrv". The "cflags"
3696 argument can contain "SV_IMMEDIATE_UNREF" to force the
3697 reference count to be decremented (otherwise the decrementing
3698 is conditional on the reference count being different from one
3699 or the reference being a readonly SV). See "SvROK_off".
3700 void sv_unref_flags(SV *ref, U32 flags)
3702 sv_untaint
3704 Untaint an SV. Use "SvTAINTED_off" instead.
3705 void sv_untaint(SV* sv)
3706 sv_upgrade
3708 Upgrade an SV to a more complex form. Generally adds a new
3709 body type to the SV, then copies across as much information as
3710 possible from the old body. You generally want to use the
3711 "SvUPGRADE" macro wrapper. See also "svtype".
3712 void sv_upgrade(SV* sv, svtype new_type)
3714 sv_usepvn_flags
3716 Tells an SV to use "ptr" to find its string value. Normally
3717 the string is stored inside the SV but sv_usepvn allows the SV
3718 to use an outside string. The "ptr" should point to memory
3719 that was allocated by "malloc". The string length, "len", must
3720 be supplied. By default this function will realloc (i.e. move)
3721 the memory pointed to by "ptr", so that pointer should not be
3722 freed or used by the programmer after giving it to sv_usepvn,
3723 and neither should any pointers from "behind" that pointer
3724 (e.g. ptr + 1) be used.
3725 If "flags" & SV_SMAGIC is true, will call SvSETMAGIC. If
3727 "flags" & SV_HAS_TRAILING_NUL is true, then "ptr[len]" must be
3728 NUL, and the realloc will be skipped. (i.e. the buffer is
3729 actually at least 1 byte longer than "len", and already meets
3730 the requirements for storing in "SvPVX")
3731 void sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
3733 sv_utf8_decode
3735 If the PV of the SV is an octet sequence in UTF-8 and contains
3736 a multiple-byte character, the "SvUTF8" flag is turned on so
3737 that it looks like a character. If the PV contains only single-
3738 byte characters, the "SvUTF8" flag stays being off. Scans PV
3739 for validity and returns false if the PV is invalid UTF-8.
3740 NOTE: this function is experimental and may change or be
3742 removed without notice.
3743 bool sv_utf8_decode(SV *sv)
3745 sv_utf8_downgrade
3747 Attempts to convert the PV of an SV from characters to bytes.
3748 If the PV contains a character that cannot fit in a byte, this
3749 conversion will fail; in this case, either returns false or, if
3750 "fail_ok" is not true, croaks.
3751 This is not as a general purpose Unicode to byte encoding
3753 interface: use the Encode extension for that.
3754 NOTE: this function is experimental and may change or be
3756 removed without notice.
3757 bool sv_utf8_downgrade(SV *sv, bool fail_ok)
3759 sv_utf8_encode
3761 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
3762 flag off so that it looks like octets again.
3763 void sv_utf8_encode(SV *sv)
3765 sv_utf8_upgrade
3767 Converts the PV of an SV to its UTF-8-encoded form. Forces the
3768 SV to string form if it is not already. Will "mg_get" on "sv"
3769 if appropriate. Always sets the SvUTF8 flag to avoid future
3770 validity checks even if the whole string is the same in UTF-8
3771 as not. Returns the number of bytes in the converted string
3772 This is not as a general purpose byte encoding to Unicode
3774 interface: use the Encode extension for that.
3775 STRLEN sv_utf8_upgrade(SV *sv)
3777 sv_utf8_upgrade_flags
3779 Converts the PV of an SV to its UTF-8-encoded form. Forces the
3780 SV to string form if it is not already. Always sets the SvUTF8
3781 flag to avoid future validity checks even if all the bytes are
3782 invariant in UTF-8. If "flags" has "SV_GMAGIC" bit set, will
3783 "mg_get" on "sv" if appropriate, else not. Returns the number
3784 of bytes in the converted string "sv_utf8_upgrade" and
3785 "sv_utf8_upgrade_nomg" are implemented in terms of this
3786 function.
3787 This is not as a general purpose byte encoding to Unicode
3789 interface: use the Encode extension for that.
3790 STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
3792 sv_utf8_upgrade_nomg
3794 Like sv_utf8_upgrade, but doesn't do magic on "sv"
3795 STRLEN sv_utf8_upgrade_nomg(SV *sv)
3797 sv_vcatpvf
3799 Processes its arguments like "vsprintf" and appends the
3800 formatted output to an SV. Does not handle 'set' magic. See
3801 "sv_vcatpvf_mg".
3802 Usually used via its frontend "sv_catpvf".
3804 void sv_vcatpvf(SV* sv, const char* pat, va_list* args)
3806 sv_vcatpvfn
3808 Processes its arguments like "vsprintf" and appends the
3809 formatted output to an SV. Uses an array of SVs if the C style
3810 variable argument list is missing (NULL). When running with
3811 taint checks enabled, indicates via "maybe_tainted" if results
3812 are untrustworthy (often due to the use of locales).
3813 Usually used via one of its frontends "sv_vcatpvf" and
3815 "sv_vcatpvf_mg".
3816 void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3818 sv_vcatpvf_mg
3820 Like "sv_vcatpvf", but also handles 'set' magic.
3821 Usually used via its frontend "sv_catpvf_mg".
3823 void sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
3825 sv_vsetpvf
3827 Works like "sv_vcatpvf" but copies the text into the SV instead
3828 of appending it. Does not handle 'set' magic. See
3829 "sv_vsetpvf_mg".
3830 Usually used via its frontend "sv_setpvf".
3832 void sv_vsetpvf(SV* sv, const char* pat, va_list* args)
3834 sv_vsetpvfn
3836 Works like "sv_vcatpvfn" but copies the text into the SV
3837 instead of appending it.
3838 Usually used via one of its frontends "sv_vsetpvf" and
3840 "sv_vsetpvf_mg".
3841 void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
3843 sv_vsetpvf_mg
3845 Like "sv_vsetpvf", but also handles 'set' magic.
3846 Usually used via its frontend "sv_setpvf_mg".
3848 void sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
3850
3852 bytes_from_utf8
3853 Converts a string "s" of length "len" from UTF-8 into native
3854 byte encoding. Unlike "utf8_to_bytes" but like
3855 "bytes_to_utf8", returns a pointer to the newly-created string,
3856 and updates "len" to contain the new length. Returns the
3857 original string if no conversion occurs, "len" is unchanged. Do
3858 nothing if "is_utf8" points to 0. Sets "is_utf8" to 0 if "s" is
3859 converted or consisted entirely of characters that are
3860 invariant in utf8 (i.e., US-ASCII on non-EBCDIC machines).
3861 NOTE: this function is experimental and may change or be
3863 removed without notice.
3864 U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
3866 bytes_to_utf8
3868 Converts a string "s" of length "len" from the native encoding
3869 into UTF-8. Returns a pointer to the newly-created string, and
3870 sets "len" to reflect the new length.
3871 A NUL character will be written after the end of the string.
3873 If you want to convert to UTF-8 from encodings other than the
3875 native (Latin1 or EBCDIC), see sv_recode_to_utf8().
3876 NOTE: this function is experimental and may change or be
3878 removed without notice.
3879 U8* bytes_to_utf8(const U8 *s, STRLEN *len)
3881 ibcmp_utf8
3883 Return true if the strings s1 and s2 differ case-insensitively,
3884 false if not (if they are equal case-insensitively). If u1 is
3885 true, the string s1 is assumed to be in UTF-8-encoded Unicode.
3886 If u2 is true, the string s2 is assumed to be in UTF-8-encoded
3887 Unicode. If u1 or u2 are false, the respective string is
3888 assumed to be in native 8-bit encoding.
3889 If the pe1 and pe2 are non-NULL, the scanning pointers will be
3891 copied in there (they will point at the beginning of the next
3892 character). If the pointers behind pe1 or pe2 are non-NULL,
3893 they are the end pointers beyond which scanning will not
3894 continue under any circumstances. If the byte lengths l1 and
3895 l2 are non-zero, s1+l1 and s2+l2 will be used as goal end
3896 pointers that will also stop the scan, and which qualify
3897 towards defining a successful match: all the scans that define
3898 an explicit length must reach their goal pointers for a match
3899 to succeed).
3900 For case-insensitiveness, the "casefolding" of Unicode is used
3902 instead of upper/lowercasing both the characters, see
3903 http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
3904 I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1, const char *s2, char **pe2, UV l2, bool u2)
3906 is_utf8_char
3908 Tests if some arbitrary number of bytes begins in a valid UTF-8
3909 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
3910 machines) character is a valid UTF-8 character. The actual
3911 number of bytes in the UTF-8 character will be returned if it
3912 is valid, otherwise 0.
3913 STRLEN is_utf8_char(const U8 *s)
3915 is_utf8_string
3917 Returns true if first "len" bytes of the given string form a
3918 valid UTF-8 string, false otherwise. Note that 'a valid UTF-8
3919 string' does not mean 'a string that contains code points above
3920 0x7F encoded in UTF-8' because a valid ASCII string is a valid
3921 UTF-8 string.
3922 See also is_utf8_string_loclen() and is_utf8_string_loc().
3924 bool is_utf8_string(const U8 *s, STRLEN len)
3926 is_utf8_string_loc
3928 Like is_utf8_string() but stores the location of the failure
3929 (in the case of "utf8ness failure") or the location s+len (in
3930 the case of "utf8ness success") in the "ep".
3931 See also is_utf8_string_loclen() and is_utf8_string().
3933 bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
3935 is_utf8_string_loclen
3937 Like is_utf8_string() but stores the location of the failure
3938 (in the case of "utf8ness failure") or the location s+len (in
3939 the case of "utf8ness success") in the "ep", and the number of
3940 UTF-8 encoded characters in the "el".
3941 See also is_utf8_string_loc() and is_utf8_string().
3943 bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
3945 pv_uni_display
3947 Build to the scalar dsv a displayable version of the string
3948 spv, length len, the displayable version being at most pvlim
3949 bytes long (if longer, the rest is truncated and "..." will be
3950 appended).
3951 The flags argument can have UNI_DISPLAY_ISPRINT set to display
3953 isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
3954 to display the \\[nrfta\\] as the backslashed versions (like
3955 '\n') (UNI_DISPLAY_BACKSLASH is preferred over
3956 UNI_DISPLAY_ISPRINT for \\). UNI_DISPLAY_QQ (and its alias
3957 UNI_DISPLAY_REGEX) have both UNI_DISPLAY_BACKSLASH and
3958 UNI_DISPLAY_ISPRINT turned on.
3959 The pointer to the PV of the dsv is returned.
3961 char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
3963 sv_cat_decode
3965 The encoding is assumed to be an Encode object, the PV of the
3966 ssv is assumed to be octets in that encoding and decoding the
3967 input starts from the position which (PV + *offset) pointed to.
3968 The dsv will be concatenated the decoded UTF-8 string from ssv.
3969 Decoding will terminate when the string tstr appears in
3970 decoding output or the input ends on the PV of the ssv. The
3971 value which the offset points will be modified to the last
3972 input position on the ssv.
3973 Returns TRUE if the terminator was found, else returns FALSE.
3975 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
3977 sv_recode_to_utf8
3979 The encoding is assumed to be an Encode object, on entry the PV
3980 of the sv is assumed to be octets in that encoding, and the sv
3981 will be converted into Unicode (and UTF-8).
3982 If the sv already is UTF-8 (or if it is not POK), or if the
3984 encoding is not a reference, nothing is done to the sv. If the
3985 encoding is not an "Encode::XS" Encoding object, bad things
3986 will happen. (See lib/encoding.pm and Encode).
3987 The PV of the sv is returned.
3989 char* sv_recode_to_utf8(SV* sv, SV *encoding)
3991 sv_uni_display
3993 Build to the scalar dsv a displayable version of the scalar sv,
3994 the displayable version being at most pvlim bytes long (if
3995 longer, the rest is truncated and "..." will be appended).
3996 The flags argument is as in pv_uni_display().
3998 The pointer to the PV of the dsv is returned.
4000 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
4002 to_utf8_case
4004 The "p" contains the pointer to the UTF-8 string encoding the
4005 character that is being converted.
4006 The "ustrp" is a pointer to the character buffer to put the
4008 conversion result to. The "lenp" is a pointer to the length of
4009 the result.
4010 The "swashp" is a pointer to the swash to use.
4012 Both the special and normal mappings are stored
4014 lib/unicore/To/Foo.pl, and loaded by SWASHNEW, using
4015 lib/utf8_heavy.pl. The special (usually, but not always, a
4016 multicharacter mapping), is tried first.
4017 The "special" is a string like "utf8::ToSpecLower", which means
4019 the hash %utf8::ToSpecLower. The access to the hash is through
4020 Perl_to_utf8_case().
4021 The "normal" is a string like "ToLower" which means the swash
4023 %utf8::ToLower.
4024 UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
4026 to_utf8_fold
4028 Convert the UTF-8 encoded character at p to its foldcase
4029 version and store that in UTF-8 in ustrp and its length in
4030 bytes in lenp. Note that the ustrp needs to be at least
4031 UTF8_MAXBYTES_CASE+1 bytes since the foldcase version may be
4032 longer than the original character (up to three characters).
4033 The first character of the foldcased version is returned (but
4035 note, as explained above, that there may be more.)
4036 UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
4038 to_utf8_lower
4040 Convert the UTF-8 encoded character at p to its lowercase
4041 version and store that in UTF-8 in ustrp and its length in
4042 bytes in lenp. Note that the ustrp needs to be at least
4043 UTF8_MAXBYTES_CASE+1 bytes since the lowercase version may be
4044 longer than the original character.
4045 The first character of the lowercased version is returned (but
4047 note, as explained above, that there may be more.)
4048 UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
4050 to_utf8_title
4052 Convert the UTF-8 encoded character at p to its titlecase
4053 version and store that in UTF-8 in ustrp and its length in
4054 bytes in lenp. Note that the ustrp needs to be at least
4055 UTF8_MAXBYTES_CASE+1 bytes since the titlecase version may be
4056 longer than the original character.
4057 The first character of the titlecased version is returned (but
4059 note, as explained above, that there may be more.)
4060 UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
4062 to_utf8_upper
4064 Convert the UTF-8 encoded character at p to its uppercase
4065 version and store that in UTF-8 in ustrp and its length in
4066 bytes in lenp. Note that the ustrp needs to be at least
4067 UTF8_MAXBYTES_CASE+1 bytes since the uppercase version may be
4068 longer than the original character.
4069 The first character of the uppercased version is returned (but
4071 note, as explained above, that there may be more.)
4072 UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
4074 utf8n_to_uvchr
4076 flags
4077 Returns the native character value of the first character in
4079 the string "s" which is assumed to be in UTF-8 encoding;
4080 "retlen" will be set to the length, in bytes, of that
4081 character.
4082 Allows length and flags to be passed to low level routine.
4084 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
4086 utf8n_to_uvuni
4088 Bottom level UTF-8 decode routine. Returns the Unicode code
4089 point value of the first character in the string "s" which is
4090 assumed to be in UTF-8 encoding and no longer than "curlen";
4091 "retlen" will be set to the length, in bytes, of that
4092 character.
4093 If "s" does not point to a well-formed UTF-8 character, the
4095 behaviour is dependent on the value of "flags": if it contains
4096 UTF8_CHECK_ONLY, it is assumed that the caller will raise a
4097 warning, and this function will silently just set "retlen" to
4098 "-1" and return zero. If the "flags" does not contain
4099 UTF8_CHECK_ONLY, warnings about malformations will be given,
4100 "retlen" will be set to the expected length of the UTF-8
4101 character in bytes, and zero will be returned.
4102 The "flags" can also contain various flags to allow deviations
4104 from the strict UTF-8 encoding (see utf8.h).
4105 Most code should use utf8_to_uvchr() rather than call this
4107 directly.
4108 UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
4110 utf8_distance
4112 Returns the number of UTF-8 characters between the UTF-8
4113 pointers "a" and "b".
4114 WARNING: use only if you *know* that the pointers point inside
4116 the same UTF-8 buffer.
4117 IV utf8_distance(const U8 *a, const U8 *b)
4119 utf8_hop
4121 Return the UTF-8 pointer "s" displaced by "off" characters,
4122 either forward or backward.
4123 WARNING: do not use the following unless you *know* "off" is
4125 within the UTF-8 data pointed to by "s" *and* that on entry "s"
4126 is aligned on the first byte of character or just after the
4127 last byte of a character.
4128 U8* utf8_hop(const U8 *s, I32 off)
4130 utf8_length
4132 Return the length of the UTF-8 char encoded string "s" in
4133 characters. Stops at "e" (inclusive). If "e < s" or if the
4134 scan would end up past "e", croaks.
4135 STRLEN utf8_length(const U8* s, const U8 *e)
4137 utf8_to_bytes
4139 Converts a string "s" of length "len" from UTF-8 into native
4140 byte encoding. Unlike "bytes_to_utf8", this over-writes the
4141 original string, and updates len to contain the new length.
4142 Returns zero on failure, setting "len" to -1.
4143 If you need a copy of the string, see "bytes_from_utf8".
4145 NOTE: this function is experimental and may change or be
4147 removed without notice.
4148 U8* utf8_to_bytes(U8 *s, STRLEN *len)
4150 utf8_to_uvchr
4152 Returns the native character value of the first character in
4153 the string "s" which is assumed to be in UTF-8 encoding;
4154 "retlen" will be set to the length, in bytes, of that
4155 character.
4156 If "s" does not point to a well-formed UTF-8 character, zero is
4158 returned and retlen is set, if possible, to -1.
4159 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
4161 utf8_to_uvuni
4163 Returns the Unicode code point of the first character in the
4164 string "s" which is assumed to be in UTF-8 encoding; "retlen"
4165 will be set to the length, in bytes, of that character.
4166 This function should only be used when the returned UV is
4168 considered an index into the Unicode semantic tables (e.g.
4169 swashes).
4170 If "s" does not point to a well-formed UTF-8 character, zero is
4172 returned and retlen is set, if possible, to -1.
4173 UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
4175 uvchr_to_utf8
4177 Adds the UTF-8 representation of the Native codepoint "uv" to
4178 the end of the string "d"; "d" should be have at least
4179 "UTF8_MAXBYTES+1" free bytes available. The return value is the
4180 pointer to the byte after the end of the new character. In
4181 other words,
4182 d = uvchr_to_utf8(d, uv);
4184 is the recommended wide native character-aware way of saying
4186 *(d++) = uv;
4188 U8* uvchr_to_utf8(U8 *d, UV uv)
4190 uvuni_to_utf8_flags
4192 Adds the UTF-8 representation of the Unicode codepoint "uv" to
4193 the end of the string "d"; "d" should be have at least
4194 "UTF8_MAXBYTES+1" free bytes available. The return value is the
4195 pointer to the byte after the end of the new character. In
4196 other words,
4197 d = uvuni_to_utf8_flags(d, uv, flags);
4199 or, in most cases,
4201 d = uvuni_to_utf8(d, uv);
4203 (which is equivalent to)
4205 d = uvuni_to_utf8_flags(d, uv, 0);
4207 is the recommended Unicode-aware way of saying
4209 *(d++) = uv;
4211 U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
4213
4215 ax Variable which is setup by "xsubpp" to indicate the stack base
4216 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
4217 The "dMARK" macro must be called prior to setup the "MARK"
4218 variable.
4219 I32 ax
4221 CLASS Variable which is setup by "xsubpp" to indicate the class name
4223 for a C++ XS constructor. This is always a "char*". See
4224 "THIS".
4225 char* CLASS
4227 dAX Sets up the "ax" variable. This is usually handled
4229 automatically by "xsubpp" by calling "dXSARGS".
4230 dAX;
4232 dAXMARK Sets up the "ax" variable and stack marker variable "mark".
4234 This is usually handled automatically by "xsubpp" by calling
4235 "dXSARGS".
4236 dAXMARK;
4238 dITEMS Sets up the "items" variable. This is usually handled
4240 automatically by "xsubpp" by calling "dXSARGS".
4241 dITEMS;
4243 dUNDERBAR
4245 Sets up the "padoff_du" variable for an XSUB that wishes to use
4246 "UNDERBAR".
4247 dUNDERBAR;
4249 dXSARGS Sets up stack and mark pointers for an XSUB, calling dSP and
4251 dMARK. Sets up the "ax" and "items" variables by calling "dAX"
4252 and "dITEMS". This is usually handled automatically by
4253 "xsubpp".
4254 dXSARGS;
4256 dXSI32 Sets up the "ix" variable for an XSUB which has aliases. This
4258 is usually handled automatically by "xsubpp".
4259 dXSI32;
4261 items Variable which is setup by "xsubpp" to indicate the number of
4263 items on the stack. See "Variable-length Parameter Lists" in
4264 perlxs.
4265 I32 items
4267 ix Variable which is setup by "xsubpp" to indicate which of an
4269 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword"
4270 in perlxs.
4271 I32 ix
4273 newXSproto
4275 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
4276 prototypes to the subs.
4277 RETVAL Variable which is setup by "xsubpp" to hold the return value
4279 for an XSUB. This is always the proper type for the XSUB. See
4280 "The RETVAL Variable" in perlxs.
4281 (whatever) RETVAL
4283 ST Used to access elements on the XSUB's stack.
4285 SV* ST(int ix)
4287 THIS Variable which is setup by "xsubpp" to designate the object in
4289 a C++ XSUB. This is always the proper type for the C++ object.
4290 See "CLASS" and "Using XS With C++" in perlxs.
4291 (whatever) THIS
4293 UNDERBAR
4295 The SV* corresponding to the $_ variable. Works even if there
4296 is a lexical $_ in scope.
4297 XS Macro to declare an XSUB and its C parameter list. This is
4299 handled by "xsubpp".
4300 XS_VERSION
4302 The version identifier for an XS module. This is usually
4303 handled automatically by "ExtUtils::MakeMaker". See
4304 "XS_VERSION_BOOTCHECK".
4305 XS_VERSION_BOOTCHECK
4307 Macro to verify that a PM module's $VERSION variable matches
4308 the XS module's "XS_VERSION" variable. This is usually handled
4309 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
4310 perlxs.
4311 XS_VERSION_BOOTCHECK;
4313
4315 croak This is the XSUB-writer's interface to Perl's "die" function.
4316 Normally call this function the same way you call the C
4317 "printf" function. Calling "croak" returns control directly to
4318 Perl, sidestepping the normal C order of execution. See "warn".
4319 If you want to throw an exception object, assign the object to
4321 $@ and then pass "NULL" to croak():
4322 errsv = get_sv("@", GV_ADD);
4324 sv_setsv(errsv, exception_object);
4325 croak(NULL);
4326 void croak(const char* pat, ...)
4328 warn This is the XSUB-writer's interface to Perl's "warn" function.
4330 Call this function the same way you call the C "printf"
4331 function. See "croak".
4332 void warn(const char* pat, ...)
4334
4336 Until May 1997, this document was maintained by Jeff Okamoto
4337 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
4338 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
4340 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
4341 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
4342 Stephen McCamant, and Gurusamy Sarathy.
4343 API Listing originally by Dean Roehrich <roehrich@cray.com>.
4345 Updated to be autogenerated from comments in the source by Benjamin
4347 Stuhl.
4348
4350 perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
4351perl v5.10.1 2017-03-22 PERLAPI(1)