1PERLAPI(1) Perl Programmers Reference Guide PERLAPI(1)
2
3
4
6 perlapi - autogenerated documentation for the perl public API
7
9 This file contains most of the documentation of the perl public API, as
10 generated by embed.pl. Specifically, it is a listing of functions,
11 macros, flags, and variables that may be used by extension writers.
12 Some specialized items are instead documented in config.h, perlapio,
13 perlcall, perlclib, perlfilter, perlguts, perlmroapi, perlxs,
14 perlxstut, and warnings.
15
16 At the end is a list of functions which have yet to be documented.
17 Patches welcome! The interfaces of these are subject to change without
18 notice.
19
20 Anything not listed here is not part of the public API, and should not
21 be used by extension writers at all. For these reasons, blindly using
22 functions listed in proto.h is to be avoided when writing extensions.
23
24 In Perl, unlike C, a string of characters may generally contain
25 embedded "NUL" characters. Sometimes in the documentation a Perl
26 string is referred to as a "buffer" to distinguish it from a C string,
27 but sometimes they are both just referred to as strings.
28
29 Note that all Perl API global variables must be referenced with the
30 "PL_" prefix. Again, those not listed here are not to be used by
31 extension writers, and can be changed or removed without notice; same
32 with macros. Some macros are provided for compatibility with the
33 older, unadorned names, but this support may be disabled in a future
34 release.
35
36 Perl was originally written to handle US-ASCII only (that is characters
37 whose ordinal numbers are in the range 0 - 127). And documentation and
38 comments may still use the term ASCII, when sometimes in fact the
39 entire range from 0 - 255 is meant.
40
41 The non-ASCII characters below 256 can have various meanings, depending
42 on various things. (See, most notably, perllocale.) But usually the
43 whole range can be referred to as ISO-8859-1. Often, the term
44 "Latin-1" (or "Latin1") is used as an equivalent for ISO-8859-1. But
45 some people treat "Latin1" as referring just to the characters in the
46 range 128 through 255, or somethimes from 160 through 255. This
47 documentation uses "Latin1" and "Latin-1" to refer to all 256
48 characters.
49
50 Note that Perl can be compiled and run under either ASCII or EBCDIC
51 (See perlebcdic). Most of the documentation (and even comments in the
52 code) ignore the EBCDIC possibility. For almost all purposes the
53 differences are transparent. As an example, under EBCDIC, instead of
54 UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so whenever
55 this documentation refers to "utf8" (and variants of that name,
56 including in function names), it also (essentially transparently) means
57 "UTF-EBCDIC". But the ordinals of characters differ between ASCII,
58 EBCDIC, and the UTF- encodings, and a string encoded in UTF-EBCDIC may
59 occupy a different number of bytes than in UTF-8.
60
61 The listing below is alphabetical, case insensitive.
62
64 av_clear
65 Frees the all the elements of an array, leaving it empty. The
66 XS equivalent of "@array = ()". See also "av_undef".
67
68 Note that it is possible that the actions of a destructor
69 called directly or indirectly by freeing an element of the
70 array could cause the reference count of the array itself to be
71 reduced (e.g. by deleting an entry in the symbol table). So it
72 is a possibility that the AV could have been freed (or even
73 reallocated) on return from the call unless you hold a
74 reference to it.
75
76 void av_clear(AV *av)
77
78 av_create_and_push
79 NOTE: this function is experimental and may change or be
80 removed without notice.
81
82 Push an SV onto the end of the array, creating the array if
83 necessary. A small internal helper function to remove a
84 commonly duplicated idiom.
85
86 NOTE: this function must be explicitly called as
87 Perl_av_create_and_push with an aTHX_ parameter.
88
89 void Perl_av_create_and_push(pTHX_ AV **const avp,
90 SV *const val)
91
92 av_create_and_unshift_one
93 NOTE: this function is experimental and may change or be
94 removed without notice.
95
96 Unshifts an SV onto the beginning of the array, creating the
97 array if necessary. A small internal helper function to remove
98 a commonly duplicated idiom.
99
100 NOTE: this function must be explicitly called as
101 Perl_av_create_and_unshift_one with an aTHX_ parameter.
102
103 SV** Perl_av_create_and_unshift_one(pTHX_
104 AV **const avp,
105 SV *const val)
106
107 av_delete
108 Deletes the element indexed by "key" from the array, makes the
109 element mortal, and returns it. If "flags" equals "G_DISCARD",
110 the element is freed and NULL is returned. NULL is also
111 returned if "key" is out of range.
112
113 Perl equivalent: "splice(@myarray, $key, 1, undef)" (with the
114 "splice" in void context if "G_DISCARD" is present).
115
116 SV* av_delete(AV *av, SSize_t key, I32 flags)
117
118 av_exists
119 Returns true if the element indexed by "key" has been
120 initialized.
121
122 This relies on the fact that uninitialized array elements are
123 set to "NULL".
124
125 Perl equivalent: "exists($myarray[$key])".
126
127 bool av_exists(AV *av, SSize_t key)
128
129 av_extend
130 Pre-extend an array so that it is capable of storing values at
131 indexes "0..key". Thus "av_extend(av,99)" guarantees that the
132 array can store 100 elements, i.e. that "av_store(av, 0, sv)"
133 through "av_store(av, 99, sv)" on a plain array will work
134 without any further memory allocation.
135
136 If the av argument is a tied array then will call the "EXTEND"
137 tied array method with an argument of "(key+1)".
138
139 void av_extend(AV *av, SSize_t key)
140
141 av_fetch
142 Returns the SV at the specified index in the array. The "key"
143 is the index. If lval is true, you are guaranteed to get a
144 real SV back (in case it wasn't real before), which you can
145 then modify. Check that the return value is non-null before
146 dereferencing it to a "SV*".
147
148 See "Understanding the Magic of Tied Hashes and Arrays" in
149 perlguts for more information on how to use this function on
150 tied arrays.
151
152 The rough perl equivalent is $myarray[$key].
153
154 SV** av_fetch(AV *av, SSize_t key, I32 lval)
155
156 AvFILL Same as "av_top_index()" or "av_tindex()".
157
158 int AvFILL(AV* av)
159
160 av_fill Set the highest index in the array to the given number,
161 equivalent to Perl's "$#array = $fill;".
162
163 The number of elements in the array will be "fill + 1" after
164 "av_fill()" returns. If the array was previously shorter, then
165 the additional elements appended are set to NULL. If the array
166 was longer, then the excess elements are freed.
167 "av_fill(av, -1)" is the same as "av_clear(av)".
168
169 void av_fill(AV *av, SSize_t fill)
170
171 av_len Same as "av_top_index". Note that, unlike what the name
172 implies, it returns the highest index in the array. This is
173 unlike "sv_len", which returns what you would expect.
174
175 To get the true number of elements in the array, instead use
176 "av_count".
177
178 SSize_t av_len(AV *av)
179
180 av_make Creates a new AV and populates it with a list of SVs. The SVs
181 are copied into the array, so they may be freed after the call
182 to "av_make". The new AV will have a reference count of 1.
183
184 Perl equivalent: "my @new_array = ($scalar1, $scalar2,
185 $scalar3...);"
186
187 AV* av_make(SSize_t size, SV **strp)
188
189 av_pop Removes one SV from the end of the array, reducing its size by
190 one and returning the SV (transferring control of one reference
191 count) to the caller. Returns &PL_sv_undef if the array is
192 empty.
193
194 Perl equivalent: "pop(@myarray);"
195
196 SV* av_pop(AV *av)
197
198 av_push Pushes an SV (transferring control of one reference count) onto
199 the end of the array. The array will grow automatically to
200 accommodate the addition.
201
202 Perl equivalent: "push @myarray, $val;".
203
204 void av_push(AV *av, SV *val)
205
206 av_shift
207 Removes one SV from the start of the array, reducing its size
208 by one and returning the SV (transferring control of one
209 reference count) to the caller. Returns &PL_sv_undef if the
210 array is empty.
211
212 Perl equivalent: "shift(@myarray);"
213
214 SV* av_shift(AV *av)
215
216 av_store
217 Stores an SV in an array. The array index is specified as
218 "key". The return value will be "NULL" if the operation failed
219 or if the value did not need to be actually stored within the
220 array (as in the case of tied arrays). Otherwise, it can be
221 dereferenced to get the "SV*" that was stored there (= "val")).
222
223 Note that the caller is responsible for suitably incrementing
224 the reference count of "val" before the call, and decrementing
225 it if the function returned "NULL".
226
227 Approximate Perl equivalent: "splice(@myarray, $key, 1, $val)".
228
229 See "Understanding the Magic of Tied Hashes and Arrays" in
230 perlguts for more information on how to use this function on
231 tied arrays.
232
233 SV** av_store(AV *av, SSize_t key, SV *val)
234
235 av_tindex
236 Same as "av_top_index()".
237
238 SSize_t av_tindex(AV *av)
239
240 av_top_index
241 Returns the highest index in the array. The number of elements
242 in the array is "av_top_index(av) + 1". Returns -1 if the
243 array is empty.
244
245 The Perl equivalent for this is $#myarray.
246
247 (A slightly shorter form is "av_tindex".)
248
249 SSize_t av_top_index(AV *av)
250
251 av_undef
252 Undefines the array. The XS equivalent of "undef(@array)".
253
254 As well as freeing all the elements of the array (like
255 "av_clear()"), this also frees the memory used by the av to
256 store its list of scalars.
257
258 See "av_clear" for a note about the array possibly being
259 invalid on return.
260
261 void av_undef(AV *av)
262
263 av_unshift
264 Unshift the given number of "undef" values onto the beginning
265 of the array. The array will grow automatically to accommodate
266 the addition.
267
268 Perl equivalent: "unshift @myarray, ((undef) x $num);"
269
270 void av_unshift(AV *av, SSize_t num)
271
272 get_av Returns the AV of the specified Perl global or package array
273 with the given name (so it won't work on lexical variables).
274 "flags" are passed to "gv_fetchpv". If "GV_ADD" is set and the
275 Perl variable does not exist then it will be created. If
276 "flags" is zero and the variable does not exist then NULL is
277 returned.
278
279 Perl equivalent: "@{"$name"}".
280
281 NOTE: the perl_ form of this function is deprecated.
282
283 AV* get_av(const char *name, I32 flags)
284
285 newAV Creates a new AV. The reference count is set to 1.
286
287 Perl equivalent: "my @array;".
288
289 AV* newAV()
290
291 sortsv In-place sort an array of SV pointers with the given comparison
292 routine.
293
294 Currently this always uses mergesort. See "sortsv_flags" for a
295 more flexible routine.
296
297 void sortsv(SV** array, size_t num_elts,
298 SVCOMPARE_t cmp)
299
301 call_argv
302 Performs a callback to the specified named and package-scoped
303 Perl subroutine with "argv" (a "NULL"-terminated array of
304 strings) as arguments. See perlcall.
305
306 Approximate Perl equivalent: "&{"$sub_name"}(@$argv)".
307
308 NOTE: the perl_ form of this function is deprecated.
309
310 I32 call_argv(const char* sub_name, I32 flags,
311 char** argv)
312
313 call_method
314 Performs a callback to the specified Perl method. The blessed
315 object must be on the stack. See perlcall.
316
317 NOTE: the perl_ form of this function is deprecated.
318
319 I32 call_method(const char* methname, I32 flags)
320
321 call_pv Performs a callback to the specified Perl sub. See perlcall.
322
323 NOTE: the perl_ form of this function is deprecated.
324
325 I32 call_pv(const char* sub_name, I32 flags)
326
327 call_sv Performs a callback to the Perl sub specified by the SV.
328
329 If neither the "G_METHOD" nor "G_METHOD_NAMED" flag is
330 supplied, the SV may be any of a CV, a GV, a reference to a CV,
331 a reference to a GV or "SvPV(sv)" will be used as the name of
332 the sub to call.
333
334 If the "G_METHOD" flag is supplied, the SV may be a reference
335 to a CV or "SvPV(sv)" will be used as the name of the method to
336 call.
337
338 If the "G_METHOD_NAMED" flag is supplied, "SvPV(sv)" will be
339 used as the name of the method to call.
340
341 Some other values are treated specially for internal use and
342 should not be depended on.
343
344 See perlcall.
345
346 NOTE: the perl_ form of this function is deprecated.
347
348 I32 call_sv(SV* sv, volatile I32 flags)
349
350 ENTER Opening bracket on a callback. See "LEAVE" and perlcall.
351
352 ENTER;
353
354 ENTER_with_name
355 Same as "ENTER", but when debugging is enabled it also
356 associates the given literal string with the new scope.
357
358 ENTER_with_name("name");
359
360 eval_pv Tells Perl to "eval" the given string in scalar context and
361 return an SV* result.
362
363 NOTE: the perl_ form of this function is deprecated.
364
365 SV* eval_pv(const char* p, I32 croak_on_error)
366
367 eval_sv Tells Perl to "eval" the string in the SV. It supports the
368 same flags as "call_sv", with the obvious exception of
369 "G_EVAL". See perlcall.
370
371 The "G_RETHROW" flag can be used if you only need eval_sv() to
372 execute code specified by a string, but not catch any errors.
373
374 NOTE: the perl_ form of this function is deprecated.
375
376 I32 eval_sv(SV* sv, I32 flags)
377
378 FREETMPS
379 Closing bracket for temporaries on a callback. See "SAVETMPS"
380 and perlcall.
381
382 FREETMPS;
383
384 LEAVE Closing bracket on a callback. See "ENTER" and perlcall.
385
386 LEAVE;
387
388 LEAVE_with_name
389 Same as "LEAVE", but when debugging is enabled it first checks
390 that the scope has the given name. "name" must be a literal
391 string.
392
393 LEAVE_with_name("name");
394
395 SAVETMPS
396 Opening bracket for temporaries on a callback. See "FREETMPS"
397 and perlcall.
398
399 SAVETMPS;
400
402 Perl uses "full" Unicode case mappings. This means that converting a
403 single character to another case may result in a sequence of more than
404 one character. For example, the uppercase of "ss" (LATIN SMALL LETTER
405 SHARP S) is the two character sequence "SS". This presents some
406 complications The lowercase of all characters in the range 0..255 is
407 a single character, and thus "toLOWER_L1" is furnished. But,
408 "toUPPER_L1" can't exist, as it couldn't return a valid result for all
409 legal inputs. Instead "toUPPER_uvchr" has an API that does allow every
410 possible legal result to be returned.) Likewise no other function that
411 is crippled by not being able to give the correct results for the full
412 range of possible inputs has been implemented here.
413
414 toFOLD Converts the specified character to foldcase. If the input is
415 anything but an ASCII uppercase character, that input character
416 itself is returned. Variant "toFOLD_A" is equivalent. (There
417 is no equivalent "to_FOLD_L1" for the full Latin1 range, as the
418 full generality of "toFOLD_uvchr" is needed there.)
419
420 U8 toFOLD(U8 ch)
421
422 toFOLD_utf8
423 Converts the first UTF-8 encoded character in the sequence
424 starting at "p" and extending no further than "e - 1" to its
425 foldcase version, and stores that in UTF-8 in "s", and its
426 length in bytes in "lenp". Note that the buffer pointed to by
427 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
428 foldcase version may be longer than the original character.
429
430 The first code point of the foldcased version is returned (but
431 note, as explained at the top of this section, that there may
432 be more).
433
434 It will not attempt to read beyond "e - 1", provided that the
435 constraint "s < e" is true (this is asserted for in
436 "-DDEBUGGING" builds). If the UTF-8 for the input character is
437 malformed in some way, the program may croak, or the function
438 may return the REPLACEMENT CHARACTER, at the discretion of the
439 implementation, and subject to change in future releases.
440
441 UV toFOLD_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
442
443 toFOLD_utf8_safe
444 Same as "toFOLD_utf8".
445
446 UV toFOLD_utf8_safe(U8* p, U8* e, U8* s,
447 STRLEN* lenp)
448
449 toFOLD_uvchr
450 Converts the code point "cp" to its foldcase version, and
451 stores that in UTF-8 in "s", and its length in bytes in "lenp".
452 The code point is interpreted as native if less than 256;
453 otherwise as Unicode. Note that the buffer pointed to by "s"
454 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
455 foldcase version may be longer than the original character.
456
457 The first code point of the foldcased version is returned (but
458 note, as explained at the top of this section, that there may
459 be more).
460
461 UV toFOLD_uvchr(UV cp, U8* s, STRLEN* lenp)
462
463 toLOWER Converts the specified character to lowercase. If the input is
464 anything but an ASCII uppercase character, that input character
465 itself is returned. Variant "toLOWER_A" is equivalent.
466
467 U8 toLOWER(U8 ch)
468
469 toLOWER_L1
470 Converts the specified Latin1 character to lowercase. The
471 results are undefined if the input doesn't fit in a byte.
472
473 U8 toLOWER_L1(U8 ch)
474
475 toLOWER_LC
476 Converts the specified character to lowercase using the current
477 locale's rules, if possible; otherwise returns the input
478 character itself.
479
480 U8 toLOWER_LC(U8 ch)
481
482 toLOWER_utf8
483 Converts the first UTF-8 encoded character in the sequence
484 starting at "p" and extending no further than "e - 1" to its
485 lowercase version, and stores that in UTF-8 in "s", and its
486 length in bytes in "lenp". Note that the buffer pointed to by
487 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
488 lowercase version may be longer than the original character.
489
490 The first code point of the lowercased version is returned (but
491 note, as explained at the top of this section, that there may
492 be more). It will not attempt to read beyond "e - 1", provided
493 that the constraint "s < e" is true (this is asserted for in
494 "-DDEBUGGING" builds). If the UTF-8 for the input character is
495 malformed in some way, the program may croak, or the function
496 may return the REPLACEMENT CHARACTER, at the discretion of the
497 implementation, and subject to change in future releases.
498
499 UV toLOWER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
500
501 toLOWER_utf8_safe
502 Same as "toLOWER_utf8".
503
504 UV toLOWER_utf8_safe(U8* p, U8* e, U8* s,
505 STRLEN* lenp)
506
507 toLOWER_uvchr
508 Converts the code point "cp" to its lowercase version, and
509 stores that in UTF-8 in "s", and its length in bytes in "lenp".
510 The code point is interpreted as native if less than 256;
511 otherwise as Unicode. Note that the buffer pointed to by "s"
512 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
513 lowercase version may be longer than the original character.
514
515 The first code point of the lowercased version is returned (but
516 note, as explained at the top of this section, that there may
517 be more).
518
519 UV toLOWER_uvchr(UV cp, U8* s, STRLEN* lenp)
520
521 toTITLE Converts the specified character to titlecase. If the input is
522 anything but an ASCII lowercase character, that input character
523 itself is returned. Variant "toTITLE_A" is equivalent. (There
524 is no "toTITLE_L1" for the full Latin1 range, as the full
525 generality of "toTITLE_uvchr" is needed there. Titlecase is
526 not a concept used in locale handling, so there is no
527 functionality for that.)
528
529 U8 toTITLE(U8 ch)
530
531 toTITLE_utf8
532 Converts the first UTF-8 encoded character in the sequence
533 starting at "p" and extending no further than "e - 1" to its
534 titlecase version, and stores that in UTF-8 in "s", and its
535 length in bytes in "lenp". Note that the buffer pointed to by
536 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
537 titlecase version may be longer than the original character.
538
539 The first code point of the titlecased version is returned (but
540 note, as explained at the top of this section, that there may
541 be more).
542
543 It will not attempt to read beyond "e - 1", provided that the
544 constraint "s < e" is true (this is asserted for in
545 "-DDEBUGGING" builds). If the UTF-8 for the input character is
546 malformed in some way, the program may croak, or the function
547 may return the REPLACEMENT CHARACTER, at the discretion of the
548 implementation, and subject to change in future releases.
549
550 UV toTITLE_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
551
552 toTITLE_utf8_safe
553 Same as "toTITLE_utf8".
554
555 UV toTITLE_utf8_safe(U8* p, U8* e, U8* s,
556 STRLEN* lenp)
557
558 toTITLE_uvchr
559 Converts the code point "cp" to its titlecase version, and
560 stores that in UTF-8 in "s", and its length in bytes in "lenp".
561 The code point is interpreted as native if less than 256;
562 otherwise as Unicode. Note that the buffer pointed to by "s"
563 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
564 titlecase version may be longer than the original character.
565
566 The first code point of the titlecased version is returned (but
567 note, as explained at the top of this section, that there may
568 be more).
569
570 UV toTITLE_uvchr(UV cp, U8* s, STRLEN* lenp)
571
572 toUPPER Converts the specified character to uppercase. If the input is
573 anything but an ASCII lowercase character, that input character
574 itself is returned. Variant "toUPPER_A" is equivalent.
575
576 U8 toUPPER(int ch)
577
578 toUPPER_utf8
579 Converts the first UTF-8 encoded character in the sequence
580 starting at "p" and extending no further than "e - 1" to its
581 uppercase version, and stores that in UTF-8 in "s", and its
582 length in bytes in "lenp". Note that the buffer pointed to by
583 "s" needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
584 uppercase version may be longer than the original character.
585
586 The first code point of the uppercased version is returned (but
587 note, as explained at the top of this section, that there may
588 be more).
589
590 It will not attempt to read beyond "e - 1", provided that the
591 constraint "s < e" is true (this is asserted for in
592 "-DDEBUGGING" builds). If the UTF-8 for the input character is
593 malformed in some way, the program may croak, or the function
594 may return the REPLACEMENT CHARACTER, at the discretion of the
595 implementation, and subject to change in future releases.
596
597 UV toUPPER_utf8(U8* p, U8* e, U8* s, STRLEN* lenp)
598
599 toUPPER_utf8_safe
600 Same as "toUPPER_utf8".
601
602 UV toUPPER_utf8_safe(U8* p, U8* e, U8* s,
603 STRLEN* lenp)
604
605 toUPPER_uvchr
606 Converts the code point "cp" to its uppercase version, and
607 stores that in UTF-8 in "s", and its length in bytes in "lenp".
608 The code point is interpreted as native if less than 256;
609 otherwise as Unicode. Note that the buffer pointed to by "s"
610 needs to be at least "UTF8_MAXBYTES_CASE+1" bytes since the
611 uppercase version may be longer than the original character.
612
613 The first code point of the uppercased version is returned (but
614 note, as explained at the top of this section, that there may
615 be more.)
616
617 UV toUPPER_uvchr(UV cp, U8* s, STRLEN* lenp)
618
619 WIDEST_UTYPE
620 Yields the widest unsigned integer type on the platform,
621 currently either "U32" or 64. This can be used in declarations
622 such as
623
624 WIDEST_UTYPE my_uv;
625
626 or casts
627
628 my_uv = (WIDEST_UTYPE) val;
629
631 This section is about functions (really macros) that classify
632 characters into types, such as punctuation versus alphabetic, etc.
633 Most of these are analogous to regular expression character classes.
634 (See "POSIX Character Classes" in perlrecharclass.) There are several
635 variants for each class. (Not all macros have all variants; each item
636 below lists the ones valid for it.) None are affected by "use bytes",
637 and only the ones with "LC" in the name are affected by the current
638 locale.
639
640 The base function, e.g., "isALPHA()", takes any signed or unsigned
641 value, treating it as a code point, and returns a boolean as to whether
642 or not the character represented by it is (or on non-ASCII platforms,
643 corresponds to) an ASCII character in the named class based on
644 platform, Unicode, and Perl rules. If the input is a number that
645 doesn't fit in an octet, FALSE is returned.
646
647 Variant "isFOO_A" (e.g., "isALPHA_A()") is identical to the base
648 function with no suffix "_A". This variant is used to emphasize by its
649 name that only ASCII-range characters can return TRUE.
650
651 Variant "isFOO_L1" imposes the Latin-1 (or EBCDIC equivalent) character
652 set onto the platform. That is, the code points that are ASCII are
653 unaffected, since ASCII is a subset of Latin-1. But the non-ASCII code
654 points are treated as if they are Latin-1 characters. For example,
655 "isWORDCHAR_L1()" will return true when called with the code point
656 0xDF, which is a word character in both ASCII and EBCDIC (though it
657 represents different characters in each). If the input is a number
658 that doesn't fit in an octet, FALSE is returned. (Perl's documentation
659 uses a colloquial definition of Latin-1, to include all code points
660 below 256.)
661
662 Variant "isFOO_uvchr" is exactly like the "isFOO_L1" variant, for
663 inputs below 256, but if the code point is larger than 255, Unicode
664 rules are used to determine if it is in the character class. For
665 example, "isWORDCHAR_uvchr(0x100)" returns TRUE, since 0x100 is LATIN
666 CAPITAL LETTER A WITH MACRON in Unicode, and is a word character.
667
668 Variants "isFOO_utf8" and "isFOO_utf8_safe" are like "isFOO_uvchr", but
669 are used for UTF-8 encoded strings. The two forms are different names
670 for the same thing. Each call to one of these classifies the first
671 character of the string starting at "p". The second parameter, "e",
672 points to anywhere in the string beyond the first character, up to one
673 byte past the end of the entire string. Although both variants are
674 identical, the suffix "_safe" in one name emphasizes that it will not
675 attempt to read beyond "e - 1", provided that the constraint "s < e" is
676 true (this is asserted for in "-DDEBUGGING" builds). If the UTF-8 for
677 the input character is malformed in some way, the program may croak, or
678 the function may return FALSE, at the discretion of the implementation,
679 and subject to change in future releases.
680
681 Variant "isFOO_LC" is like the "isFOO_A" and "isFOO_L1" variants, but
682 the result is based on the current locale, which is what "LC" in the
683 name stands for. If Perl can determine that the current locale is a
684 UTF-8 locale, it uses the published Unicode rules; otherwise, it uses
685 the C library function that gives the named classification. For
686 example, "isDIGIT_LC()" when not in a UTF-8 locale returns the result
687 of calling "isdigit()". FALSE is always returned if the input won't
688 fit into an octet. On some platforms where the C library function is
689 known to be defective, Perl changes its result to follow the POSIX
690 standard's rules.
691
692 Variant "isFOO_LC_uvchr" acts exactly like "isFOO_LC" for inputs less
693 than 256, but for larger ones it returns the Unicode classification of
694 the code point.
695
696 Variants "isFOO_LC_utf8" and "isFOO_LC_utf8_safe" are like
697 "isFOO_LC_uvchr", but are used for UTF-8 encoded strings. The two
698 forms are different names for the same thing. Each call to one of
699 these classifies the first character of the string starting at "p".
700 The second parameter, "e", points to anywhere in the string beyond the
701 first character, up to one byte past the end of the entire string.
702 Although both variants are identical, the suffix "_safe" in one name
703 emphasizes that it will not attempt to read beyond "e - 1", provided
704 that the constraint "s < e" is true (this is asserted for in
705 "-DDEBUGGING" builds). If the UTF-8 for the input character is
706 malformed in some way, the program may croak, or the function may
707 return FALSE, at the discretion of the implementation, and subject to
708 change in future releases.
709
710 isALPHA Returns a boolean indicating whether the specified input is one
711 of "[A-Za-z]", analogous to "m/[[:alpha:]]/". See the top of
712 this section for an explanation of variants "isALPHA_A",
713 "isALPHA_L1", "isALPHA_uvchr", "isALPHA_utf8",
714 "isALPHA_utf8_safe", "isALPHA_LC", "isALPHA_LC_uvchr",
715 "isALPHA_LC_utf8", and "isALPHA_LC_utf8_safe".
716
717 bool isALPHA(int ch)
718
719 isALPHANUMERIC
720 Returns a boolean indicating whether the specified character is
721 one of "[A-Za-z0-9]", analogous to "m/[[:alnum:]]/". See the
722 top of this section for an explanation of variants
723 "isALPHANUMERIC_A", "isALPHANUMERIC_L1",
724 "isALPHANUMERIC_uvchr", "isALPHANUMERIC_utf8",
725 "isALPHANUMERIC_utf8_safe", "isALPHANUMERIC_LC",
726 "isALPHANUMERIC_LC_uvchr", "isALPHANUMERIC_LC_utf8", and
727 "isALPHANUMERIC_LC_utf8_safe".
728
729 A (discouraged from use) synonym is "isALNUMC" (where the "C"
730 suffix means this corresponds to the C language alphanumeric
731 definition). Also there are the variants "isALNUMC_A",
732 "isALNUMC_L1" "isALNUMC_LC", and "isALNUMC_LC_uvchr".
733
734 bool isALPHANUMERIC(int ch)
735
736 isASCII Returns a boolean indicating whether the specified character is
737 one of the 128 characters in the ASCII character set, analogous
738 to "m/[[:ascii:]]/". On non-ASCII platforms, it returns TRUE
739 iff this character corresponds to an ASCII character. Variants
740 "isASCII_A()" and "isASCII_L1()" are identical to "isASCII()".
741 See the top of this section for an explanation of variants
742 "isASCII_uvchr", "isASCII_utf8", "isASCII_utf8_safe",
743 "isASCII_LC", "isASCII_LC_uvchr", "isASCII_LC_utf8", and
744 "isASCII_LC_utf8_safe". Note, however, that some platforms do
745 not have the C library routine "isascii()". In these cases,
746 the variants whose names contain "LC" are the same as the
747 corresponding ones without.
748
749 bool isASCII(int ch)
750
751 isBLANK Returns a boolean indicating whether the specified character is
752 a character considered to be a blank, analogous to
753 "m/[[:blank:]]/". See the top of this section for an
754 explanation of variants "isBLANK_A", "isBLANK_L1",
755 "isBLANK_uvchr", "isBLANK_utf8", "isBLANK_utf8_safe",
756 "isBLANK_LC", "isBLANK_LC_uvchr", "isBLANK_LC_utf8", and
757 "isBLANK_LC_utf8_safe". Note, however, that some platforms do
758 not have the C library routine "isblank()". In these cases,
759 the variants whose names contain "LC" are the same as the
760 corresponding ones without.
761
762 bool isBLANK(char ch)
763
764 isCNTRL Returns a boolean indicating whether the specified character is
765 a control character, analogous to "m/[[:cntrl:]]/". See the
766 top of this section for an explanation of variants "isCNTRL_A",
767 "isCNTRL_L1", "isCNTRL_uvchr", "isCNTRL_utf8",
768 "isCNTRL_utf8_safe", "isCNTRL_LC", "isCNTRL_LC_uvchr",
769 "isCNTRL_LC_utf8" and "isCNTRL_LC_utf8_safe". On EBCDIC
770 platforms, you almost always want to use the "isCNTRL_L1"
771 variant.
772
773 bool isCNTRL(char ch)
774
775 isDIGIT Returns a boolean indicating whether the specified character is
776 a digit, analogous to "m/[[:digit:]]/". Variants "isDIGIT_A"
777 and "isDIGIT_L1" are identical to "isDIGIT". See the top of
778 this section for an explanation of variants "isDIGIT_uvchr",
779 "isDIGIT_utf8", "isDIGIT_utf8_safe", "isDIGIT_LC",
780 "isDIGIT_LC_uvchr", "isDIGIT_LC_utf8", and
781 "isDIGIT_LC_utf8_safe".
782
783 bool isDIGIT(char ch)
784
785 isGRAPH Returns a boolean indicating whether the specified character is
786 a graphic character, analogous to "m/[[:graph:]]/". See the
787 top of this section for an explanation of variants "isGRAPH_A",
788 "isGRAPH_L1", "isGRAPH_uvchr", "isGRAPH_utf8",
789 "isGRAPH_utf8_safe", "isGRAPH_LC", "isGRAPH_LC_uvchr",
790 "isGRAPH_LC_utf8_safe", and "isGRAPH_LC_utf8_safe".
791
792 bool isGRAPH(char ch)
793
794 isIDCONT
795 Returns a boolean indicating whether the specified character
796 can be the second or succeeding character of an identifier.
797 This is very close to, but not quite the same as the official
798 Unicode property "XID_Continue". The difference is that this
799 returns true only if the input character also matches
800 "isWORDCHAR". See the top of this section for an explanation
801 of variants "isIDCONT_A", "isIDCONT_L1", "isIDCONT_uvchr",
802 "isIDCONT_utf8", "isIDCONT_utf8_safe", "isIDCONT_LC",
803 "isIDCONT_LC_uvchr", "isIDCONT_LC_utf8", and
804 "isIDCONT_LC_utf8_safe".
805
806 bool isIDCONT(char ch)
807
808 isIDFIRST
809 Returns a boolean indicating whether the specified character
810 can be the first character of an identifier. This is very
811 close to, but not quite the same as the official Unicode
812 property "XID_Start". The difference is that this returns true
813 only if the input character also matches "isWORDCHAR". See the
814 top of this section for an explanation of variants
815 "isIDFIRST_A", "isIDFIRST_L1", "isIDFIRST_uvchr",
816 "isIDFIRST_utf8", "isIDFIRST_utf8_safe", "isIDFIRST_LC",
817 "isIDFIRST_LC_uvchr", "isIDFIRST_LC_utf8", and
818 "isIDFIRST_LC_utf8_safe".
819
820 bool isIDFIRST(char ch)
821
822 isLOWER Returns a boolean indicating whether the specified character is
823 a lowercase character, analogous to "m/[[:lower:]]/". See the
824 top of this section for an explanation of variants "isLOWER_A",
825 "isLOWER_L1", "isLOWER_uvchr", "isLOWER_utf8",
826 "isLOWER_utf8_safe", "isLOWER_LC", "isLOWER_LC_uvchr",
827 "isLOWER_LC_utf8", and "isLOWER_LC_utf8_safe".
828
829 bool isLOWER(char ch)
830
831 isOCTAL Returns a boolean indicating whether the specified character is
832 an octal digit, [0-7]. The only two variants are "isOCTAL_A"
833 and "isOCTAL_L1"; each is identical to "isOCTAL".
834
835 bool isOCTAL(char ch)
836
837 isPRINT Returns a boolean indicating whether the specified character is
838 a printable character, analogous to "m/[[:print:]]/". See the
839 top of this section for an explanation of variants "isPRINT_A",
840 "isPRINT_L1", "isPRINT_uvchr", "isPRINT_utf8",
841 "isPRINT_utf8_safe", "isPRINT_LC", "isPRINT_LC_uvchr",
842 "isPRINT_LC_utf8", and "isPRINT_LC_utf8_safe".
843
844 bool isPRINT(char ch)
845
846 isPSXSPC
847 (short for Posix Space) Starting in 5.18, this is identical in
848 all its forms to the corresponding "isSPACE()" macros. The
849 locale forms of this macro are identical to their corresponding
850 "isSPACE()" forms in all Perl releases. In releases prior to
851 5.18, the non-locale forms differ from their "isSPACE()" forms
852 only in that the "isSPACE()" forms don't match a Vertical Tab,
853 and the "isPSXSPC()" forms do. Otherwise they are identical.
854 Thus this macro is analogous to what "m/[[:space:]]/" matches
855 in a regular expression. See the top of this section for an
856 explanation of variants "isPSXSPC_A", "isPSXSPC_L1",
857 "isPSXSPC_uvchr", "isPSXSPC_utf8", "isPSXSPC_utf8_safe",
858 "isPSXSPC_LC", "isPSXSPC_LC_uvchr", "isPSXSPC_LC_utf8", and
859 "isPSXSPC_LC_utf8_safe".
860
861 bool isPSXSPC(char ch)
862
863 isPUNCT Returns a boolean indicating whether the specified character is
864 a punctuation character, analogous to "m/[[:punct:]]/". Note
865 that the definition of what is punctuation isn't as
866 straightforward as one might desire. See "POSIX Character
867 Classes" in perlrecharclass for details. See the top of this
868 section for an explanation of variants "isPUNCT_A",
869 "isPUNCT_L1", "isPUNCT_uvchr", "isPUNCT_utf8",
870 "isPUNCT_utf8_safe", "isPUNCT_LC", "isPUNCT_LC_uvchr",
871 "isPUNCT_LC_utf8", and "isPUNCT_LC_utf8_safe".
872
873 bool isPUNCT(char ch)
874
875 isSPACE Returns a boolean indicating whether the specified character is
876 a whitespace character. This is analogous to what "m/\s/"
877 matches in a regular expression. Starting in Perl 5.18 this
878 also matches what "m/[[:space:]]/" does. Prior to 5.18, only
879 the locale forms of this macro (the ones with "LC" in their
880 names) matched precisely what "m/[[:space:]]/" does. In those
881 releases, the only difference, in the non-locale variants, was
882 that "isSPACE()" did not match a vertical tab. (See "isPSXSPC"
883 for a macro that matches a vertical tab in all releases.) See
884 the top of this section for an explanation of variants
885 "isSPACE_A", "isSPACE_L1", "isSPACE_uvchr", "isSPACE_utf8",
886 "isSPACE_utf8_safe", "isSPACE_LC", "isSPACE_LC_uvchr",
887 "isSPACE_LC_utf8", and "isSPACE_LC_utf8_safe".
888
889 bool isSPACE(char ch)
890
891 isUPPER Returns a boolean indicating whether the specified character is
892 an uppercase character, analogous to "m/[[:upper:]]/". See the
893 top of this section for an explanation of variants "isUPPER_A",
894 "isUPPER_L1", "isUPPER_uvchr", "isUPPER_utf8",
895 "isUPPER_utf8_safe", "isUPPER_LC", "isUPPER_LC_uvchr",
896 "isUPPER_LC_utf8", and "isUPPER_LC_utf8_safe".
897
898 bool isUPPER(char ch)
899
900 isWORDCHAR
901 Returns a boolean indicating whether the specified character is
902 a character that is a word character, analogous to what "m/\w/"
903 and "m/[[:word:]]/" match in a regular expression. A word
904 character is an alphabetic character, a decimal digit, a
905 connecting punctuation character (such as an underscore), or a
906 "mark" character that attaches to one of those (like some sort
907 of accent). "isALNUM()" is a synonym provided for backward
908 compatibility, even though a word character includes more than
909 the standard C language meaning of alphanumeric. See the top
910 of this section for an explanation of variants "isWORDCHAR_A",
911 "isWORDCHAR_L1", "isWORDCHAR_uvchr", "isWORDCHAR_utf8", and
912 "isWORDCHAR_utf8_safe". "isWORDCHAR_LC",
913 "isWORDCHAR_LC_uvchr", "isWORDCHAR_LC_utf8", and
914 "isWORDCHAR_LC_utf8_safe" are also as described there, but
915 additionally include the platform's native underscore.
916
917 bool isWORDCHAR(char ch)
918
919 isXDIGIT
920 Returns a boolean indicating whether the specified character is
921 a hexadecimal digit. In the ASCII range these are
922 "[0-9A-Fa-f]". Variants "isXDIGIT_A()" and "isXDIGIT_L1()" are
923 identical to "isXDIGIT()". See the top of this section for an
924 explanation of variants "isXDIGIT_uvchr", "isXDIGIT_utf8",
925 "isXDIGIT_utf8_safe", "isXDIGIT_LC", "isXDIGIT_LC_uvchr",
926 "isXDIGIT_LC_utf8", and "isXDIGIT_LC_utf8_safe".
927
928 bool isXDIGIT(char ch)
929
931 perl_clone
932 Create and return a new interpreter by cloning the current one.
933
934 "perl_clone" takes these flags as parameters:
935
936 "CLONEf_COPY_STACKS" - is used to, well, copy the stacks also,
937 without it we only clone the data and zero the stacks, with it
938 we copy the stacks and the new perl interpreter is ready to run
939 at the exact same point as the previous one. The pseudo-fork
940 code uses "COPY_STACKS" while the threads->create doesn't.
941
942 "CLONEf_KEEP_PTR_TABLE" - "perl_clone" keeps a ptr_table with
943 the pointer of the old variable as a key and the new variable
944 as a value, this allows it to check if something has been
945 cloned and not clone it again, but rather just use the value
946 and increase the refcount. If "KEEP_PTR_TABLE" is not set then
947 "perl_clone" will kill the ptr_table using the function
948 "ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;". A reason
949 to keep it around is if you want to dup some of your own
950 variables which are outside the graph that perl scans.
951
952 "CLONEf_CLONE_HOST" - This is a win32 thing, it is ignored on
953 unix, it tells perl's win32host code (which is c++) to clone
954 itself, this is needed on win32 if you want to run two threads
955 at the same time, if you just want to do some stuff in a
956 separate perl interpreter and then throw it away and return to
957 the original one, you don't need to do anything.
958
959 PerlInterpreter* perl_clone(
960 PerlInterpreter *proto_perl,
961 UV flags
962 )
963
965 BhkDISABLE
966 NOTE: this function is experimental and may change or be
967 removed without notice.
968
969 Temporarily disable an entry in this BHK structure, by clearing
970 the appropriate flag. "which" is a preprocessor token
971 indicating which entry to disable.
972
973 void BhkDISABLE(BHK *hk, which)
974
975 BhkENABLE
976 NOTE: this function is experimental and may change or be
977 removed without notice.
978
979 Re-enable an entry in this BHK structure, by setting the
980 appropriate flag. "which" is a preprocessor token indicating
981 which entry to enable. This will assert (under -DDEBUGGING) if
982 the entry doesn't contain a valid pointer.
983
984 void BhkENABLE(BHK *hk, which)
985
986 BhkENTRY_set
987 NOTE: this function is experimental and may change or be
988 removed without notice.
989
990 Set an entry in the BHK structure, and set the flags to
991 indicate it is valid. "which" is a preprocessing token
992 indicating which entry to set. The type of "ptr" depends on
993 the entry.
994
995 void BhkENTRY_set(BHK *hk, which, void *ptr)
996
997 blockhook_register
998 NOTE: this function is experimental and may change or be
999 removed without notice.
1000
1001 Register a set of hooks to be called when the Perl lexical
1002 scope changes at compile time. See "Compile-time scope hooks"
1003 in perlguts.
1004
1005 NOTE: this function must be explicitly called as
1006 Perl_blockhook_register with an aTHX_ parameter.
1007
1008 void Perl_blockhook_register(pTHX_ BHK *hk)
1009
1011 cophh_2hv
1012 NOTE: this function is experimental and may change or be
1013 removed without notice.
1014
1015 Generates and returns a standard Perl hash representing the
1016 full set of key/value pairs in the cop hints hash "cophh".
1017 "flags" is currently unused and must be zero.
1018
1019 HV * cophh_2hv(const COPHH *cophh, U32 flags)
1020
1021 cophh_copy
1022 NOTE: this function is experimental and may change or be
1023 removed without notice.
1024
1025 Make and return a complete copy of the cop hints hash "cophh".
1026
1027 COPHH * cophh_copy(COPHH *cophh)
1028
1029 cophh_delete_pv
1030 NOTE: this function is experimental and may change or be
1031 removed without notice.
1032
1033 Like "cophh_delete_pvn", but takes a nul-terminated string
1034 instead of a string/length pair.
1035
1036 COPHH * cophh_delete_pv(const COPHH *cophh,
1037 const char *key, U32 hash,
1038 U32 flags)
1039
1040 cophh_delete_pvn
1041 NOTE: this function is experimental and may change or be
1042 removed without notice.
1043
1044 Delete a key and its associated value from the cop hints hash
1045 "cophh", and returns the modified hash. The returned hash
1046 pointer is in general not the same as the hash pointer that was
1047 passed in. The input hash is consumed by the function, and the
1048 pointer to it must not be subsequently used. Use "cophh_copy"
1049 if you need both hashes.
1050
1051 The key is specified by "keypv" and "keylen". If "flags" has
1052 the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1053 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1054 precomputed hash of the key string, or zero if it has not been
1055 precomputed.
1056
1057 COPHH * cophh_delete_pvn(COPHH *cophh,
1058 const char *keypv,
1059 STRLEN keylen, U32 hash,
1060 U32 flags)
1061
1062 cophh_delete_pvs
1063 NOTE: this function is experimental and may change or be
1064 removed without notice.
1065
1066 Like "cophh_delete_pvn", but takes a literal string instead of
1067 a string/length pair, and no precomputed hash.
1068
1069 COPHH * cophh_delete_pvs(const COPHH *cophh, "key",
1070 U32 flags)
1071
1072 cophh_delete_sv
1073 NOTE: this function is experimental and may change or be
1074 removed without notice.
1075
1076 Like "cophh_delete_pvn", but takes a Perl scalar instead of a
1077 string/length pair.
1078
1079 COPHH * cophh_delete_sv(const COPHH *cophh, SV *key,
1080 U32 hash, U32 flags)
1081
1082 cophh_fetch_pv
1083 NOTE: this function is experimental and may change or be
1084 removed without notice.
1085
1086 Like "cophh_fetch_pvn", but takes a nul-terminated string
1087 instead of a string/length pair.
1088
1089 SV * cophh_fetch_pv(const COPHH *cophh,
1090 const char *key, U32 hash,
1091 U32 flags)
1092
1093 cophh_fetch_pvn
1094 NOTE: this function is experimental and may change or be
1095 removed without notice.
1096
1097 Look up the entry in the cop hints hash "cophh" with the key
1098 specified by "keypv" and "keylen". If "flags" has the
1099 "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1100 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1101 precomputed hash of the key string, or zero if it has not been
1102 precomputed. Returns a mortal scalar copy of the value
1103 associated with the key, or &PL_sv_placeholder if there is no
1104 value associated with the key.
1105
1106 SV * cophh_fetch_pvn(const COPHH *cophh,
1107 const char *keypv,
1108 STRLEN keylen, U32 hash,
1109 U32 flags)
1110
1111 cophh_fetch_pvs
1112 NOTE: this function is experimental and may change or be
1113 removed without notice.
1114
1115 Like "cophh_fetch_pvn", but takes a literal string instead of a
1116 string/length pair, and no precomputed hash.
1117
1118 SV * cophh_fetch_pvs(const COPHH *cophh, "key",
1119 U32 flags)
1120
1121 cophh_fetch_sv
1122 NOTE: this function is experimental and may change or be
1123 removed without notice.
1124
1125 Like "cophh_fetch_pvn", but takes a Perl scalar instead of a
1126 string/length pair.
1127
1128 SV * cophh_fetch_sv(const COPHH *cophh, SV *key,
1129 U32 hash, U32 flags)
1130
1131 cophh_free
1132 NOTE: this function is experimental and may change or be
1133 removed without notice.
1134
1135 Discard the cop hints hash "cophh", freeing all resources
1136 associated with it.
1137
1138 void cophh_free(COPHH *cophh)
1139
1140 cophh_new_empty
1141 NOTE: this function is experimental and may change or be
1142 removed without notice.
1143
1144 Generate and return a fresh cop hints hash containing no
1145 entries.
1146
1147 COPHH * cophh_new_empty()
1148
1149 cophh_store_pv
1150 NOTE: this function is experimental and may change or be
1151 removed without notice.
1152
1153 Like "cophh_store_pvn", but takes a nul-terminated string
1154 instead of a string/length pair.
1155
1156 COPHH * cophh_store_pv(const COPHH *cophh,
1157 const char *key, U32 hash,
1158 SV *value, U32 flags)
1159
1160 cophh_store_pvn
1161 NOTE: this function is experimental and may change or be
1162 removed without notice.
1163
1164 Stores a value, associated with a key, in the cop hints hash
1165 "cophh", and returns the modified hash. The returned hash
1166 pointer is in general not the same as the hash pointer that was
1167 passed in. The input hash is consumed by the function, and the
1168 pointer to it must not be subsequently used. Use "cophh_copy"
1169 if you need both hashes.
1170
1171 The key is specified by "keypv" and "keylen". If "flags" has
1172 the "COPHH_KEY_UTF8" bit set, the key octets are interpreted as
1173 UTF-8, otherwise they are interpreted as Latin-1. "hash" is a
1174 precomputed hash of the key string, or zero if it has not been
1175 precomputed.
1176
1177 "value" is the scalar value to store for this key. "value" is
1178 copied by this function, which thus does not take ownership of
1179 any reference to it, and later changes to the scalar will not
1180 be reflected in the value visible in the cop hints hash.
1181 Complex types of scalar will not be stored with referential
1182 integrity, but will be coerced to strings.
1183
1184 COPHH * cophh_store_pvn(COPHH *cophh, const char *keypv,
1185 STRLEN keylen, U32 hash,
1186 SV *value, U32 flags)
1187
1188 cophh_store_pvs
1189 NOTE: this function is experimental and may change or be
1190 removed without notice.
1191
1192 Like "cophh_store_pvn", but takes a literal string instead of a
1193 string/length pair, and no precomputed hash.
1194
1195 COPHH * cophh_store_pvs(const COPHH *cophh, "key",
1196 SV *value, U32 flags)
1197
1198 cophh_store_sv
1199 NOTE: this function is experimental and may change or be
1200 removed without notice.
1201
1202 Like "cophh_store_pvn", but takes a Perl scalar instead of a
1203 string/length pair.
1204
1205 COPHH * cophh_store_sv(const COPHH *cophh, SV *key,
1206 U32 hash, SV *value, U32 flags)
1207
1209 cop_hints_2hv
1210 Generates and returns a standard Perl hash representing the
1211 full set of hint entries in the cop "cop". "flags" is
1212 currently unused and must be zero.
1213
1214 HV * cop_hints_2hv(const COP *cop, U32 flags)
1215
1216 cop_hints_fetch_pv
1217 Like "cop_hints_fetch_pvn", but takes a nul-terminated string
1218 instead of a string/length pair.
1219
1220 SV * cop_hints_fetch_pv(const COP *cop,
1221 const char *key, U32 hash,
1222 U32 flags)
1223
1224 cop_hints_fetch_pvn
1225 Look up the hint entry in the cop "cop" with the key specified
1226 by "keypv" and "keylen". If "flags" has the "COPHH_KEY_UTF8"
1227 bit set, the key octets are interpreted as UTF-8, otherwise
1228 they are interpreted as Latin-1. "hash" is a precomputed hash
1229 of the key string, or zero if it has not been precomputed.
1230 Returns a mortal scalar copy of the value associated with the
1231 key, or &PL_sv_placeholder if there is no value associated with
1232 the key.
1233
1234 SV * cop_hints_fetch_pvn(const COP *cop,
1235 const char *keypv,
1236 STRLEN keylen, U32 hash,
1237 U32 flags)
1238
1239 cop_hints_fetch_pvs
1240 Like "cop_hints_fetch_pvn", but takes a literal string instead
1241 of a string/length pair, and no precomputed hash.
1242
1243 SV * cop_hints_fetch_pvs(const COP *cop, "key",
1244 U32 flags)
1245
1246 cop_hints_fetch_sv
1247 Like "cop_hints_fetch_pvn", but takes a Perl scalar instead of
1248 a string/length pair.
1249
1250 SV * cop_hints_fetch_sv(const COP *cop, SV *key,
1251 U32 hash, U32 flags)
1252
1253 CopLABEL
1254 Returns the label attached to a cop.
1255
1256 const char * CopLABEL(COP *const cop)
1257
1258 CopLABEL_len
1259 Returns the label attached to a cop, and stores its length in
1260 bytes into *len.
1261
1262 const char * CopLABEL_len(COP *const cop, STRLEN *len)
1263
1264 CopLABEL_len_flags
1265 Returns the label attached to a cop, and stores its length in
1266 bytes into *len. Upon return, *flags will be set to either
1267 "SVf_UTF8" or 0.
1268
1269 const char * CopLABEL_len_flags(COP *const cop,
1270 STRLEN *len, U32 *flags)
1271
1273 custom_op_register
1274 Register a custom op. See "Custom Operators" in perlguts.
1275
1276 NOTE: this function must be explicitly called as
1277 Perl_custom_op_register with an aTHX_ parameter.
1278
1279 void Perl_custom_op_register(pTHX_
1280 Perl_ppaddr_t ppaddr,
1281 const XOP *xop)
1282
1283 Perl_custom_op_xop
1284 Return the XOP structure for a given custom op. This macro
1285 should be considered internal to "OP_NAME" and the other access
1286 macros: use them instead. This macro does call a function.
1287 Prior to 5.19.6, this was implemented as a function.
1288
1289 const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
1290
1291 XopDISABLE
1292 Temporarily disable a member of the XOP, by clearing the
1293 appropriate flag.
1294
1295 void XopDISABLE(XOP *xop, which)
1296
1297 XopENABLE
1298 Reenable a member of the XOP which has been disabled.
1299
1300 void XopENABLE(XOP *xop, which)
1301
1302 XopENTRY
1303 Return a member of the XOP structure. "which" is a cpp token
1304 indicating which entry to return. If the member is not set
1305 this will return a default value. The return type depends on
1306 "which". This macro evaluates its arguments more than once.
1307 If you are using "Perl_custom_op_xop" to retreive a "XOP *"
1308 from a "OP *", use the more efficient "XopENTRYCUSTOM" instead.
1309
1310 XopENTRY(XOP *xop, which)
1311
1312 XopENTRYCUSTOM
1313 Exactly like "XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o),
1314 which)" but more efficient. The "which" parameter is identical
1315 to "XopENTRY".
1316
1317 XopENTRYCUSTOM(const OP *o, which)
1318
1319 XopENTRY_set
1320 Set a member of the XOP structure. "which" is a cpp token
1321 indicating which entry to set. See "Custom Operators" in
1322 perlguts for details about the available members and how they
1323 are used. This macro evaluates its argument more than once.
1324
1325 void XopENTRY_set(XOP *xop, which, value)
1326
1327 XopFLAGS
1328 Return the XOP's flags.
1329
1330 U32 XopFLAGS(XOP *xop)
1331
1333 This section documents functions to manipulate CVs which are code-
1334 values, or subroutines. For more information, see perlguts.
1335
1336 caller_cx
1337 The XSUB-writer's equivalent of caller(). The returned
1338 "PERL_CONTEXT" structure can be interrogated to find all the
1339 information returned to Perl by "caller". Note that XSUBs
1340 don't get a stack frame, so "caller_cx(0, NULL)" will return
1341 information for the immediately-surrounding Perl code.
1342
1343 This function skips over the automatic calls to &DB::sub made
1344 on the behalf of the debugger. If the stack frame requested
1345 was a sub called by "DB::sub", the return value will be the
1346 frame for the call to "DB::sub", since that has the correct
1347 line number/etc. for the call site. If dbcxp is non-"NULL", it
1348 will be set to a pointer to the frame for the sub call itself.
1349
1350 const PERL_CONTEXT * caller_cx(
1351 I32 level,
1352 const PERL_CONTEXT **dbcxp
1353 )
1354
1355 CvSTASH Returns the stash of the CV. A stash is the symbol table hash,
1356 containing the package-scoped variables in the package where
1357 the subroutine was defined. For more information, see
1358 perlguts.
1359
1360 This also has a special use with XS AUTOLOAD subs. See
1361 "Autoloading with XSUBs" in perlguts.
1362
1363 HV* CvSTASH(CV* cv)
1364
1365 find_runcv
1366 Locate the CV corresponding to the currently executing sub or
1367 eval. If "db_seqp" is non_null, skip CVs that are in the DB
1368 package and populate *db_seqp with the cop sequence number at
1369 the point that the DB:: code was entered. (This allows
1370 debuggers to eval in the scope of the breakpoint rather than in
1371 the scope of the debugger itself.)
1372
1373 CV* find_runcv(U32 *db_seqp)
1374
1375 get_cv Uses "strlen" to get the length of "name", then calls
1376 "get_cvn_flags".
1377
1378 NOTE: the perl_ form of this function is deprecated.
1379
1380 CV* get_cv(const char* name, I32 flags)
1381
1382 get_cvn_flags
1383 Returns the CV of the specified Perl subroutine. "flags" are
1384 passed to "gv_fetchpvn_flags". If "GV_ADD" is set and the Perl
1385 subroutine does not exist then it will be declared (which has
1386 the same effect as saying "sub name;"). If "GV_ADD" is not set
1387 and the subroutine does not exist then NULL is returned.
1388
1389 CV* get_cvn_flags(const char* name, STRLEN len,
1390 I32 flags)
1391
1393 ax Variable which is setup by "xsubpp" to indicate the stack base
1394 offset, used by the "ST", "XSprePUSH" and "XSRETURN" macros.
1395 The "dMARK" macro must be called prior to setup the "MARK"
1396 variable.
1397
1398 I32 ax
1399
1400 CLASS Variable which is setup by "xsubpp" to indicate the class name
1401 for a C++ XS constructor. This is always a "char*". See
1402 "THIS".
1403
1404 char* CLASS
1405
1406 dAX Sets up the "ax" variable. This is usually handled
1407 automatically by "xsubpp" by calling "dXSARGS".
1408
1409 dAX;
1410
1411 dAXMARK Sets up the "ax" variable and stack marker variable "mark".
1412 This is usually handled automatically by "xsubpp" by calling
1413 "dXSARGS".
1414
1415 dAXMARK;
1416
1417 dITEMS Sets up the "items" variable. This is usually handled
1418 automatically by "xsubpp" by calling "dXSARGS".
1419
1420 dITEMS;
1421
1422 dUNDERBAR
1423 Sets up any variable needed by the "UNDERBAR" macro. It used
1424 to define "padoff_du", but it is currently a noop. However, it
1425 is strongly advised to still use it for ensuring past and
1426 future compatibility.
1427
1428 dUNDERBAR;
1429
1430 dXSARGS Sets up stack and mark pointers for an XSUB, calling "dSP" and
1431 "dMARK". Sets up the "ax" and "items" variables by calling
1432 "dAX" and "dITEMS". This is usually handled automatically by
1433 "xsubpp".
1434
1435 dXSARGS;
1436
1437 dXSI32 Sets up the "ix" variable for an XSUB which has aliases. This
1438 is usually handled automatically by "xsubpp".
1439
1440 dXSI32;
1441
1442 items Variable which is setup by "xsubpp" to indicate the number of
1443 items on the stack. See "Variable-length Parameter Lists" in
1444 perlxs.
1445
1446 I32 items
1447
1448 ix Variable which is setup by "xsubpp" to indicate which of an
1449 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword"
1450 in perlxs.
1451
1452 I32 ix
1453
1454 RETVAL Variable which is setup by "xsubpp" to hold the return value
1455 for an XSUB. This is always the proper type for the XSUB. See
1456 "The RETVAL Variable" in perlxs.
1457
1458 (whatever) RETVAL
1459
1460 ST Used to access elements on the XSUB's stack.
1461
1462 SV* ST(int ix)
1463
1464 THIS Variable which is setup by "xsubpp" to designate the object in
1465 a C++ XSUB. This is always the proper type for the C++ object.
1466 See "CLASS" and "Using XS With C++" in perlxs.
1467
1468 (whatever) THIS
1469
1470 UNDERBAR
1471 The SV* corresponding to the $_ variable. Works even if there
1472 is a lexical $_ in scope.
1473
1474 XS Macro to declare an XSUB and its C parameter list. This is
1475 handled by "xsubpp". It is the same as using the more explicit
1476 "XS_EXTERNAL" macro.
1477
1478 XS_EXTERNAL
1479 Macro to declare an XSUB and its C parameter list explicitly
1480 exporting the symbols.
1481
1482 XS_INTERNAL
1483 Macro to declare an XSUB and its C parameter list without
1484 exporting the symbols. This is handled by "xsubpp" and
1485 generally preferable over exporting the XSUB symbols
1486 unnecessarily.
1487
1489 dump_all
1490 Dumps the entire optree of the current program starting at
1491 "PL_main_root" to "STDERR". Also dumps the optrees for all
1492 visible subroutines in "PL_defstash".
1493
1494 void dump_all()
1495
1496 dump_packsubs
1497 Dumps the optrees for all visible subroutines in "stash".
1498
1499 void dump_packsubs(const HV* stash)
1500
1501 op_class
1502 Given an op, determine what type of struct it has been
1503 allocated as. Returns one of the OPclass enums, such as
1504 OPclass_LISTOP.
1505
1506 OPclass op_class(const OP *o)
1507
1508 op_dump Dumps the optree starting at OP "o" to "STDERR".
1509
1510 void op_dump(const OP *o)
1511
1512 sv_dump Dumps the contents of an SV to the "STDERR" filehandle.
1513
1514 For an example of its output, see Devel::Peek.
1515
1516 void sv_dump(SV* sv)
1517
1519 pv_display
1520 Similar to
1521
1522 pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
1523
1524 except that an additional "\0" will be appended to the string
1525 when len > cur and pv[cur] is "\0".
1526
1527 Note that the final string may be up to 7 chars longer than
1528 pvlim.
1529
1530 char* pv_display(SV *dsv, const char *pv, STRLEN cur,
1531 STRLEN len, STRLEN pvlim)
1532
1533 pv_escape
1534 Escapes at most the first "count" chars of "pv" and puts the
1535 results into "dsv" such that the size of the escaped string
1536 will not exceed "max" chars and will not contain any incomplete
1537 escape sequences. The number of bytes escaped will be returned
1538 in the "STRLEN *escaped" parameter if it is not null. When the
1539 "dsv" parameter is null no escaping actually occurs, but the
1540 number of bytes that would be escaped were it not null will be
1541 calculated.
1542
1543 If flags contains "PERL_PV_ESCAPE_QUOTE" then any double quotes
1544 in the string will also be escaped.
1545
1546 Normally the SV will be cleared before the escaped string is
1547 prepared, but when "PERL_PV_ESCAPE_NOCLEAR" is set this will
1548 not occur.
1549
1550 If "PERL_PV_ESCAPE_UNI" is set then the input string is treated
1551 as UTF-8 if "PERL_PV_ESCAPE_UNI_DETECT" is set then the input
1552 string is scanned using "is_utf8_string()" to determine if it
1553 is UTF-8.
1554
1555 If "PERL_PV_ESCAPE_ALL" is set then all input chars will be
1556 output using "\x01F1" style escapes, otherwise if
1557 "PERL_PV_ESCAPE_NONASCII" is set, only non-ASCII chars will be
1558 escaped using this style; otherwise, only chars above 255 will
1559 be so escaped; other non printable chars will use octal or
1560 common escaped patterns like "\n". Otherwise, if
1561 "PERL_PV_ESCAPE_NOBACKSLASH" then all chars below 255 will be
1562 treated as printable and will be output as literals.
1563
1564 If "PERL_PV_ESCAPE_FIRSTCHAR" is set then only the first char
1565 of the string will be escaped, regardless of max. If the
1566 output is to be in hex, then it will be returned as a plain hex
1567 sequence. Thus the output will either be a single char, an
1568 octal escape sequence, a special escape like "\n" or a hex
1569 value.
1570
1571 If "PERL_PV_ESCAPE_RE" is set then the escape char used will be
1572 a "%" and not a "\\". This is because regexes very often
1573 contain backslashed sequences, whereas "%" is not a
1574 particularly common character in patterns.
1575
1576 Returns a pointer to the escaped text as held by "dsv".
1577
1578 char* pv_escape(SV *dsv, char const * const str,
1579 const STRLEN count, const STRLEN max,
1580 STRLEN * const escaped,
1581 const U32 flags)
1582
1583 pv_pretty
1584 Converts a string into something presentable, handling escaping
1585 via "pv_escape()" and supporting quoting and ellipses.
1586
1587 If the "PERL_PV_PRETTY_QUOTE" flag is set then the result will
1588 be double quoted with any double quotes in the string escaped.
1589 Otherwise if the "PERL_PV_PRETTY_LTGT" flag is set then the
1590 result be wrapped in angle brackets.
1591
1592 If the "PERL_PV_PRETTY_ELLIPSES" flag is set and not all
1593 characters in string were output then an ellipsis "..." will be
1594 appended to the string. Note that this happens AFTER it has
1595 been quoted.
1596
1597 If "start_color" is non-null then it will be inserted after the
1598 opening quote (if there is one) but before the escaped text.
1599 If "end_color" is non-null then it will be inserted after the
1600 escaped text but before any quotes or ellipses.
1601
1602 Returns a pointer to the prettified text as held by "dsv".
1603
1604 char* pv_pretty(SV *dsv, char const * const str,
1605 const STRLEN count, const STRLEN max,
1606 char const * const start_color,
1607 char const * const end_color,
1608 const U32 flags)
1609
1611 cv_clone
1612 Clone a CV, making a lexical closure. "proto" supplies the
1613 prototype of the function: its code, pad structure, and other
1614 attributes. The prototype is combined with a capture of outer
1615 lexicals to which the code refers, which are taken from the
1616 currently-executing instance of the immediately surrounding
1617 code.
1618
1619 CV* cv_clone(CV* proto)
1620
1621 cv_name Returns an SV containing the name of the CV, mainly for use in
1622 error reporting. The CV may actually be a GV instead, in which
1623 case the returned SV holds the GV's name. Anything other than
1624 a GV or CV is treated as a string already holding the sub name,
1625 but this could change in the future.
1626
1627 An SV may be passed as a second argument. If so, the name will
1628 be assigned to it and it will be returned. Otherwise the
1629 returned SV will be a new mortal.
1630
1631 If "flags" has the "CV_NAME_NOTQUAL" bit set, then the package
1632 name will not be included. If the first argument is neither a
1633 CV nor a GV, this flag is ignored (subject to change).
1634
1635 SV * cv_name(CV *cv, SV *sv, U32 flags)
1636
1637 cv_undef
1638 Clear out all the active components of a CV. This can happen
1639 either by an explicit "undef &foo", or by the reference count
1640 going to zero. In the former case, we keep the "CvOUTSIDE"
1641 pointer, so that any anonymous children can still follow the
1642 full lexical scope chain.
1643
1644 void cv_undef(CV* cv)
1645
1646 find_rundefsv
1647 Returns the global variable $_.
1648
1649 SV* find_rundefsv()
1650
1651 find_rundefsvoffset
1652 DEPRECATED! It is planned to remove this function from a
1653 future release of Perl. Do not use it for new code; remove it
1654 from existing code.
1655
1656 Until the lexical $_ feature was removed, this function would
1657 find the position of the lexical $_ in the pad of the
1658 currently-executing function and return the offset in the
1659 current pad, or "NOT_IN_PAD".
1660
1661 Now it always returns "NOT_IN_PAD".
1662
1663 PADOFFSET find_rundefsvoffset()
1664
1665 intro_my
1666 "Introduce" "my" variables to visible status. This is called
1667 during parsing at the end of each statement to make lexical
1668 variables visible to subsequent statements.
1669
1670 U32 intro_my()
1671
1672 load_module
1673 Loads the module whose name is pointed to by the string part of
1674 "name". Note that the actual module name, not its filename,
1675 should be given. Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver,
1676 if specified and not NULL, provides version semantics similar
1677 to "use Foo::Bar VERSION". The optional trailing arguments can
1678 be used to specify arguments to the module's "import()" method,
1679 similar to "use Foo::Bar VERSION LIST"; their precise handling
1680 depends on the flags. The flags argument is a bitwise-ORed
1681 collection of any of "PERL_LOADMOD_DENY",
1682 "PERL_LOADMOD_NOIMPORT", or "PERL_LOADMOD_IMPORT_OPS" (or 0 for
1683 no flags).
1684
1685 If "PERL_LOADMOD_NOIMPORT" is set, the module is loaded as if
1686 with an empty import list, as in "use Foo::Bar ()"; this is the
1687 only circumstance in which the trailing optional arguments may
1688 be omitted entirely. Otherwise, if "PERL_LOADMOD_IMPORT_OPS" is
1689 set, the trailing arguments must consist of exactly one "OP*",
1690 containing the op tree that produces the relevant import
1691 arguments. Otherwise, the trailing arguments must all be "SV*"
1692 values that will be used as import arguments; and the list must
1693 be terminated with "(SV*) NULL". If neither
1694 "PERL_LOADMOD_NOIMPORT" nor "PERL_LOADMOD_IMPORT_OPS" is set,
1695 the trailing "NULL" pointer is needed even if no import
1696 arguments are desired. The reference count for each specified
1697 "SV*" argument is decremented. In addition, the "name" argument
1698 is modified.
1699
1700 If "PERL_LOADMOD_DENY" is set, the module is loaded as if with
1701 "no" rather than "use".
1702
1703 void load_module(U32 flags, SV* name, SV* ver, ...)
1704
1705 my_exit A wrapper for the C library exit(3), honoring what
1706 "PL_exit_flags" in perlapi say to do.
1707
1708 void my_exit(U32 status)
1709
1710 newPADNAMELIST
1711 NOTE: this function is experimental and may change or be
1712 removed without notice.
1713
1714 Creates a new pad name list. "max" is the highest index for
1715 which space is allocated.
1716
1717 PADNAMELIST * newPADNAMELIST(size_t max)
1718
1719 newPADNAMEouter
1720 NOTE: this function is experimental and may change or be
1721 removed without notice.
1722
1723 Constructs and returns a new pad name. Only use this function
1724 for names that refer to outer lexicals. (See also
1725 "newPADNAMEpvn".) "outer" is the outer pad name that this one
1726 mirrors. The returned pad name has the "PADNAMEt_OUTER" flag
1727 already set.
1728
1729 PADNAME * newPADNAMEouter(PADNAME *outer)
1730
1731 newPADNAMEpvn
1732 NOTE: this function is experimental and may change or be
1733 removed without notice.
1734
1735 Constructs and returns a new pad name. "s" must be a UTF-8
1736 string. Do not use this for pad names that point to outer
1737 lexicals. See "newPADNAMEouter".
1738
1739 PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
1740
1741 nothreadhook
1742 Stub that provides thread hook for perl_destruct when there are
1743 no threads.
1744
1745 int nothreadhook()
1746
1747 pad_add_anon
1748 Allocates a place in the currently-compiling pad (via
1749 "pad_alloc") for an anonymous function that is lexically scoped
1750 inside the currently-compiling function. The function "func"
1751 is linked into the pad, and its "CvOUTSIDE" link to the outer
1752 scope is weakened to avoid a reference loop.
1753
1754 One reference count is stolen, so you may need to do
1755 "SvREFCNT_inc(func)".
1756
1757 "optype" should be an opcode indicating the type of operation
1758 that the pad entry is to support. This doesn't affect
1759 operational semantics, but is used for debugging.
1760
1761 PADOFFSET pad_add_anon(CV* func, I32 optype)
1762
1763 pad_add_name_pv
1764 Exactly like "pad_add_name_pvn", but takes a nul-terminated
1765 string instead of a string/length pair.
1766
1767 PADOFFSET pad_add_name_pv(const char *name,
1768 const U32 flags,
1769 HV *typestash, HV *ourstash)
1770
1771 pad_add_name_pvn
1772 Allocates a place in the currently-compiling pad for a named
1773 lexical variable. Stores the name and other metadata in the
1774 name part of the pad, and makes preparations to manage the
1775 variable's lexical scoping. Returns the offset of the
1776 allocated pad slot.
1777
1778 "namepv"/"namelen" specify the variable's name, including
1779 leading sigil. If "typestash" is non-null, the name is for a
1780 typed lexical, and this identifies the type. If "ourstash" is
1781 non-null, it's a lexical reference to a package variable, and
1782 this identifies the package. The following flags can be OR'ed
1783 together:
1784
1785 padadd_OUR redundantly specifies if it's a package var
1786 padadd_STATE variable will retain value persistently
1787 padadd_NO_DUP_CHECK skip check for lexical shadowing
1788
1789 PADOFFSET pad_add_name_pvn(const char *namepv,
1790 STRLEN namelen, U32 flags,
1791 HV *typestash, HV *ourstash)
1792
1793 pad_add_name_sv
1794 Exactly like "pad_add_name_pvn", but takes the name string in
1795 the form of an SV instead of a string/length pair.
1796
1797 PADOFFSET pad_add_name_sv(SV *name, U32 flags,
1798 HV *typestash, HV *ourstash)
1799
1800 pad_alloc
1801 NOTE: this function is experimental and may change or be
1802 removed without notice.
1803
1804 Allocates a place in the currently-compiling pad, returning the
1805 offset of the allocated pad slot. No name is initially
1806 attached to the pad slot. "tmptype" is a set of flags
1807 indicating the kind of pad entry required, which will be set in
1808 the value SV for the allocated pad entry:
1809
1810 SVs_PADMY named lexical variable ("my", "our", "state")
1811 SVs_PADTMP unnamed temporary store
1812 SVf_READONLY constant shared between recursion levels
1813
1814 "SVf_READONLY" has been supported here only since perl 5.20.
1815 To work with earlier versions as well, use
1816 "SVf_READONLY|SVs_PADTMP". "SVf_READONLY" does not cause the
1817 SV in the pad slot to be marked read-only, but simply tells
1818 "pad_alloc" that it will be made read-only (by the caller), or
1819 at least should be treated as such.
1820
1821 "optype" should be an opcode indicating the type of operation
1822 that the pad entry is to support. This doesn't affect
1823 operational semantics, but is used for debugging.
1824
1825 PADOFFSET pad_alloc(I32 optype, U32 tmptype)
1826
1827 pad_findmy_pv
1828 Exactly like "pad_findmy_pvn", but takes a nul-terminated
1829 string instead of a string/length pair.
1830
1831 PADOFFSET pad_findmy_pv(const char* name, U32 flags)
1832
1833 pad_findmy_pvn
1834 Given the name of a lexical variable, find its position in the
1835 currently-compiling pad. "namepv"/"namelen" specify the
1836 variable's name, including leading sigil. "flags" is reserved
1837 and must be zero. If it is not in the current pad but appears
1838 in the pad of any lexically enclosing scope, then a pseudo-
1839 entry for it is added in the current pad. Returns the offset
1840 in the current pad, or "NOT_IN_PAD" if no such lexical is in
1841 scope.
1842
1843 PADOFFSET pad_findmy_pvn(const char* namepv,
1844 STRLEN namelen, U32 flags)
1845
1846 pad_findmy_sv
1847 Exactly like "pad_findmy_pvn", but takes the name string in the
1848 form of an SV instead of a string/length pair.
1849
1850 PADOFFSET pad_findmy_sv(SV* name, U32 flags)
1851
1852 padnamelist_fetch
1853 NOTE: this function is experimental and may change or be
1854 removed without notice.
1855
1856 Fetches the pad name from the given index.
1857
1858 PADNAME * padnamelist_fetch(PADNAMELIST *pnl,
1859 SSize_t key)
1860
1861 padnamelist_store
1862 NOTE: this function is experimental and may change or be
1863 removed without notice.
1864
1865 Stores the pad name (which may be null) at the given index,
1866 freeing any existing pad name in that slot.
1867
1868 PADNAME ** padnamelist_store(PADNAMELIST *pnl,
1869 SSize_t key, PADNAME *val)
1870
1871 pad_setsv
1872 Set the value at offset "po" in the current (compiling or
1873 executing) pad. Use the macro "PAD_SETSV()" rather than
1874 calling this function directly.
1875
1876 void pad_setsv(PADOFFSET po, SV* sv)
1877
1878 pad_sv Get the value at offset "po" in the current (compiling or
1879 executing) pad. Use macro "PAD_SV" instead of calling this
1880 function directly.
1881
1882 SV* pad_sv(PADOFFSET po)
1883
1884 pad_tidy
1885 NOTE: this function is experimental and may change or be
1886 removed without notice.
1887
1888 Tidy up a pad at the end of compilation of the code to which it
1889 belongs. Jobs performed here are: remove most stuff from the
1890 pads of anonsub prototypes; give it a @_; mark temporaries as
1891 such. "type" indicates the kind of subroutine:
1892
1893 padtidy_SUB ordinary subroutine
1894 padtidy_SUBCLONE prototype for lexical closure
1895 padtidy_FORMAT format
1896
1897 void pad_tidy(padtidy_type type)
1898
1899 perl_alloc
1900 Allocates a new Perl interpreter. See perlembed.
1901
1902 PerlInterpreter* perl_alloc()
1903
1904 perl_construct
1905 Initializes a new Perl interpreter. See perlembed.
1906
1907 void perl_construct(PerlInterpreter *my_perl)
1908
1909 perl_destruct
1910 Shuts down a Perl interpreter. See perlembed for a tutorial.
1911
1912 "my_perl" points to the Perl interpreter. It must have been
1913 previously created through the use of "perl_alloc" and
1914 "perl_construct". It may have been initialised through
1915 "perl_parse", and may have been used through "perl_run" and
1916 other means. This function should be called for any Perl
1917 interpreter that has been constructed with "perl_construct",
1918 even if subsequent operations on it failed, for example if
1919 "perl_parse" returned a non-zero value.
1920
1921 If the interpreter's "PL_exit_flags" word has the
1922 "PERL_EXIT_DESTRUCT_END" flag set, then this function will
1923 execute code in "END" blocks before performing the rest of
1924 destruction. If it is desired to make any use of the
1925 interpreter between "perl_parse" and "perl_destruct" other than
1926 just calling "perl_run", then this flag should be set early on.
1927 This matters if "perl_run" will not be called, or if anything
1928 else will be done in addition to calling "perl_run".
1929
1930 Returns a value be a suitable value to pass to the C library
1931 function "exit" (or to return from "main"), to serve as an exit
1932 code indicating the nature of the way the interpreter
1933 terminated. This takes into account any failure of
1934 "perl_parse" and any early exit from "perl_run". The exit code
1935 is of the type required by the host operating system, so
1936 because of differing exit code conventions it is not portable
1937 to interpret specific numeric values as having specific
1938 meanings.
1939
1940 int perl_destruct(PerlInterpreter *my_perl)
1941
1942 perl_free
1943 Releases a Perl interpreter. See perlembed.
1944
1945 void perl_free(PerlInterpreter *my_perl)
1946
1947 perl_parse
1948 Tells a Perl interpreter to parse a Perl script. This performs
1949 most of the initialisation of a Perl interpreter. See
1950 perlembed for a tutorial.
1951
1952 "my_perl" points to the Perl interpreter that is to parse the
1953 script. It must have been previously created through the use
1954 of "perl_alloc" and "perl_construct". "xsinit" points to a
1955 callback function that will be called to set up the ability for
1956 this Perl interpreter to load XS extensions, or may be null to
1957 perform no such setup.
1958
1959 "argc" and "argv" supply a set of command-line arguments to the
1960 Perl interpreter, as would normally be passed to the "main"
1961 function of a C program. "argv[argc]" must be null. These
1962 arguments are where the script to parse is specified, either by
1963 naming a script file or by providing a script in a "-e" option.
1964 If $0 will be written to in the Perl interpreter, then the
1965 argument strings must be in writable memory, and so mustn't
1966 just be string constants.
1967
1968 "env" specifies a set of environment variables that will be
1969 used by this Perl interpreter. If non-null, it must point to a
1970 null-terminated array of environment strings. If null, the
1971 Perl interpreter will use the environment supplied by the
1972 "environ" global variable.
1973
1974 This function initialises the interpreter, and parses and
1975 compiles the script specified by the command-line arguments.
1976 This includes executing code in "BEGIN", "UNITCHECK", and
1977 "CHECK" blocks. It does not execute "INIT" blocks or the main
1978 program.
1979
1980 Returns an integer of slightly tricky interpretation. The
1981 correct use of the return value is as a truth value indicating
1982 whether there was a failure in initialisation. If zero is
1983 returned, this indicates that initialisation was successful,
1984 and it is safe to proceed to call "perl_run" and make other use
1985 of it. If a non-zero value is returned, this indicates some
1986 problem that means the interpreter wants to terminate. The
1987 interpreter should not be just abandoned upon such failure; the
1988 caller should proceed to shut the interpreter down cleanly with
1989 "perl_destruct" and free it with "perl_free".
1990
1991 For historical reasons, the non-zero return value also attempts
1992 to be a suitable value to pass to the C library function "exit"
1993 (or to return from "main"), to serve as an exit code indicating
1994 the nature of the way initialisation terminated. However, this
1995 isn't portable, due to differing exit code conventions. A
1996 historical bug is preserved for the time being: if the Perl
1997 built-in "exit" is called during this function's execution,
1998 with a type of exit entailing a zero exit code under the host
1999 operating system's conventions, then this function returns zero
2000 rather than a non-zero value. This bug, [perl #2754], leads to
2001 "perl_run" being called (and therefore "INIT" blocks and the
2002 main program running) despite a call to "exit". It has been
2003 preserved because a popular module-installing module has come
2004 to rely on it and needs time to be fixed. This issue is [perl
2005 #132577], and the original bug is due to be fixed in Perl 5.30.
2006
2007 int perl_parse(PerlInterpreter *my_perl,
2008 XSINIT_t xsinit, int argc,
2009 char** argv, char** env)
2010
2011 perl_run
2012 Tells a Perl interpreter to run its main program. See
2013 perlembed for a tutorial.
2014
2015 "my_perl" points to the Perl interpreter. It must have been
2016 previously created through the use of "perl_alloc" and
2017 "perl_construct", and initialised through "perl_parse". This
2018 function should not be called if "perl_parse" returned a non-
2019 zero value, indicating a failure in initialisation or
2020 compilation.
2021
2022 This function executes code in "INIT" blocks, and then executes
2023 the main program. The code to be executed is that established
2024 by the prior call to "perl_parse". If the interpreter's
2025 "PL_exit_flags" word does not have the "PERL_EXIT_DESTRUCT_END"
2026 flag set, then this function will also execute code in "END"
2027 blocks. If it is desired to make any further use of the
2028 interpreter after calling this function, then "END" blocks
2029 should be postponed to "perl_destruct" time by setting that
2030 flag.
2031
2032 Returns an integer of slightly tricky interpretation. The
2033 correct use of the return value is as a truth value indicating
2034 whether the program terminated non-locally. If zero is
2035 returned, this indicates that the program ran to completion,
2036 and it is safe to make other use of the interpreter (provided
2037 that the "PERL_EXIT_DESTRUCT_END" flag was set as described
2038 above). If a non-zero value is returned, this indicates that
2039 the interpreter wants to terminate early. The interpreter
2040 should not be just abandoned because of this desire to
2041 terminate; the caller should proceed to shut the interpreter
2042 down cleanly with "perl_destruct" and free it with "perl_free".
2043
2044 For historical reasons, the non-zero return value also attempts
2045 to be a suitable value to pass to the C library function "exit"
2046 (or to return from "main"), to serve as an exit code indicating
2047 the nature of the way the program terminated. However, this
2048 isn't portable, due to differing exit code conventions. An
2049 attempt is made to return an exit code of the type required by
2050 the host operating system, but because it is constrained to be
2051 non-zero, it is not necessarily possible to indicate every type
2052 of exit. It is only reliable on Unix, where a zero exit code
2053 can be augmented with a set bit that will be ignored. In any
2054 case, this function is not the correct place to acquire an exit
2055 code: one should get that from "perl_destruct".
2056
2057 int perl_run(PerlInterpreter *my_perl)
2058
2059 require_pv
2060 Tells Perl to "require" the file named by the string argument.
2061 It is analogous to the Perl code "eval "require '$file'"".
2062 It's even implemented that way; consider using load_module
2063 instead.
2064
2065 NOTE: the perl_ form of this function is deprecated.
2066
2067 void require_pv(const char* pv)
2068
2070 dXCPT Set up necessary local variables for exception handling. See
2071 "Exception Handling" in perlguts.
2072
2073 dXCPT;
2074
2075 XCPT_CATCH
2076 Introduces a catch block. See "Exception Handling" in
2077 perlguts.
2078
2079 XCPT_RETHROW
2080 Rethrows a previously caught exception. See "Exception
2081 Handling" in perlguts.
2082
2083 XCPT_RETHROW;
2084
2085 XCPT_TRY_END
2086 Ends a try block. See "Exception Handling" in perlguts.
2087
2088 XCPT_TRY_START
2089 Starts a try block. See "Exception Handling" in perlguts.
2090
2092 av_count
2093 Returns the number of elements in the array "av". This is the
2094 true length of the array, including any undefined elements. It
2095 is always the same as "av_top_index(av) + 1".
2096
2097 Size_t av_count(AV *av)
2098
2100 new_version
2101 Returns a new version object based on the passed in SV:
2102
2103 SV *sv = new_version(SV *ver);
2104
2105 Does not alter the passed in ver SV. See "upg_version" if you
2106 want to upgrade the SV.
2107
2108 SV* new_version(SV *ver)
2109
2110 prescan_version
2111 Validate that a given string can be parsed as a version object,
2112 but doesn't actually perform the parsing. Can use either
2113 strict or lax validation rules. Can optionally set a number of
2114 hint variables to save the parsing code some time when
2115 tokenizing.
2116
2117 const char* prescan_version(const char *s, bool strict,
2118 const char** errstr,
2119 bool *sqv,
2120 int *ssaw_decimal,
2121 int *swidth, bool *salpha)
2122
2123 scan_version
2124 Returns a pointer to the next character after the parsed
2125 version string, as well as upgrading the passed in SV to an RV.
2126
2127 Function must be called with an already existing SV like
2128
2129 sv = newSV(0);
2130 s = scan_version(s, SV *sv, bool qv);
2131
2132 Performs some preprocessing to the string to ensure that it has
2133 the correct characteristics of a version. Flags the object if
2134 it contains an underscore (which denotes this is an alpha
2135 version). The boolean qv denotes that the version should be
2136 interpreted as if it had multiple decimals, even if it doesn't.
2137
2138 const char* scan_version(const char *s, SV *rv, bool qv)
2139
2140 upg_version
2141 In-place upgrade of the supplied SV to a version object.
2142
2143 SV *sv = upg_version(SV *sv, bool qv);
2144
2145 Returns a pointer to the upgraded SV. Set the boolean qv if
2146 you want to force this SV to be interpreted as an "extended"
2147 version.
2148
2149 SV* upg_version(SV *ver, bool qv)
2150
2151 vcmp Version object aware cmp. Both operands must already have been
2152 converted into version objects.
2153
2154 int vcmp(SV *lhv, SV *rhv)
2155
2156 vnormal Accepts a version object and returns the normalized string
2157 representation. Call like:
2158
2159 sv = vnormal(rv);
2160
2161 NOTE: you can pass either the object directly or the SV
2162 contained within the RV.
2163
2164 The SV returned has a refcount of 1.
2165
2166 SV* vnormal(SV *vs)
2167
2168 vnumify Accepts a version object and returns the normalized floating
2169 point representation. Call like:
2170
2171 sv = vnumify(rv);
2172
2173 NOTE: you can pass either the object directly or the SV
2174 contained within the RV.
2175
2176 The SV returned has a refcount of 1.
2177
2178 SV* vnumify(SV *vs)
2179
2180 vstringify
2181 In order to maintain maximum compatibility with earlier
2182 versions of Perl, this function will return either the floating
2183 point notation or the multiple dotted notation, depending on
2184 whether the original version contained 1 or more dots,
2185 respectively.
2186
2187 The SV returned has a refcount of 1.
2188
2189 SV* vstringify(SV *vs)
2190
2191 vverify Validates that the SV contains valid internal structure for a
2192 version object. It may be passed either the version object
2193 (RV) or the hash itself (HV). If the structure is valid, it
2194 returns the HV. If the structure is invalid, it returns NULL.
2195
2196 SV *hv = vverify(sv);
2197
2198 Note that it only confirms the bare minimum structure (so as
2199 not to get confused by derived classes which may contain
2200 additional hash entries):
2201
2202 · The SV is an HV or a reference to an HV
2203
2204 · The hash contains a "version" key
2205
2206 · The "version" key has a reference to an AV as its value
2207
2208 SV* vverify(SV *vs)
2209
2211 G_ARRAY Used to indicate list context. See "GIMME_V", "GIMME" and
2212 perlcall.
2213
2214 G_DISCARD
2215 Indicates that arguments returned from a callback should be
2216 discarded. See perlcall.
2217
2218 G_EVAL Used to force a Perl "eval" wrapper around a callback. See
2219 perlcall.
2220
2221 GIMME A backward-compatible version of "GIMME_V" which can only
2222 return "G_SCALAR" or "G_ARRAY"; in a void context, it returns
2223 "G_SCALAR". Deprecated. Use "GIMME_V" instead.
2224
2225 U32 GIMME
2226
2227 GIMME_V The XSUB-writer's equivalent to Perl's "wantarray". Returns
2228 "G_VOID", "G_SCALAR" or "G_ARRAY" for void, scalar or list
2229 context, respectively. See perlcall for a usage example.
2230
2231 U32 GIMME_V
2232
2233 G_NOARGS
2234 Indicates that no arguments are being sent to a callback. See
2235 perlcall.
2236
2237 G_SCALAR
2238 Used to indicate scalar context. See "GIMME_V", "GIMME", and
2239 perlcall.
2240
2241 G_VOID Used to indicate void context. See "GIMME_V" and perlcall.
2242
2244 These variables are global to an entire process. They are shared
2245 between all interpreters and all threads in a process. Any variables
2246 not documented here may be changed or removed without notice, so don't
2247 use them! If you feel you really do need to use an unlisted variable,
2248 first send email to perl5-porters@perl.org
2249 <mailto:perl5-porters@perl.org>. It may be that someone there will
2250 point out a way to accomplish what you need without using an internal
2251 variable. But if not, you should get a go-ahead to document and then
2252 use the variable.
2253
2254 PL_check
2255 Array, indexed by opcode, of functions that will be called for
2256 the "check" phase of optree building during compilation of Perl
2257 code. For most (but not all) types of op, once the op has been
2258 initially built and populated with child ops it will be
2259 filtered through the check function referenced by the
2260 appropriate element of this array. The new op is passed in as
2261 the sole argument to the check function, and the check function
2262 returns the completed op. The check function may (as the name
2263 suggests) check the op for validity and signal errors. It may
2264 also initialise or modify parts of the ops, or perform more
2265 radical surgery such as adding or removing child ops, or even
2266 throw the op away and return a different op in its place.
2267
2268 This array of function pointers is a convenient place to hook
2269 into the compilation process. An XS module can put its own
2270 custom check function in place of any of the standard ones, to
2271 influence the compilation of a particular type of op. However,
2272 a custom check function must never fully replace a standard
2273 check function (or even a custom check function from another
2274 module). A module modifying checking must instead wrap the
2275 preexisting check function. A custom check function must be
2276 selective about when to apply its custom behaviour. In the
2277 usual case where it decides not to do anything special with an
2278 op, it must chain the preexisting op function. Check functions
2279 are thus linked in a chain, with the core's base checker at the
2280 end.
2281
2282 For thread safety, modules should not write directly to this
2283 array. Instead, use the function "wrap_op_checker".
2284
2285 PL_keyword_plugin
2286 NOTE: this function is experimental and may change or be
2287 removed without notice.
2288
2289 Function pointer, pointing at a function used to handle
2290 extended keywords. The function should be declared as
2291
2292 int keyword_plugin_function(pTHX_
2293 char *keyword_ptr, STRLEN keyword_len,
2294 OP **op_ptr)
2295
2296 The function is called from the tokeniser, whenever a possible
2297 keyword is seen. "keyword_ptr" points at the word in the
2298 parser's input buffer, and "keyword_len" gives its length; it
2299 is not null-terminated. The function is expected to examine
2300 the word, and possibly other state such as %^H, to decide
2301 whether it wants to handle it as an extended keyword. If it
2302 does not, the function should return "KEYWORD_PLUGIN_DECLINE",
2303 and the normal parser process will continue.
2304
2305 If the function wants to handle the keyword, it first must
2306 parse anything following the keyword that is part of the syntax
2307 introduced by the keyword. See "Lexer interface" for details.
2308
2309 When a keyword is being handled, the plugin function must build
2310 a tree of "OP" structures, representing the code that was
2311 parsed. The root of the tree must be stored in *op_ptr. The
2312 function then returns a constant indicating the syntactic role
2313 of the construct that it has parsed: "KEYWORD_PLUGIN_STMT" if
2314 it is a complete statement, or "KEYWORD_PLUGIN_EXPR" if it is
2315 an expression. Note that a statement construct cannot be used
2316 inside an expression (except via "do BLOCK" and similar), and
2317 an expression is not a complete statement (it requires at least
2318 a terminating semicolon).
2319
2320 When a keyword is handled, the plugin function may also have
2321 (compile-time) side effects. It may modify "%^H", define
2322 functions, and so on. Typically, if side effects are the main
2323 purpose of a handler, it does not wish to generate any ops to
2324 be included in the normal compilation. In this case it is
2325 still required to supply an op tree, but it suffices to
2326 generate a single null op.
2327
2328 That's how the *PL_keyword_plugin function needs to behave
2329 overall. Conventionally, however, one does not completely
2330 replace the existing handler function. Instead, take a copy of
2331 "PL_keyword_plugin" before assigning your own function pointer
2332 to it. Your handler function should look for keywords that it
2333 is interested in and handle those. Where it is not interested,
2334 it should call the saved plugin function, passing on the
2335 arguments it received. Thus "PL_keyword_plugin" actually
2336 points at a chain of handler functions, all of which have an
2337 opportunity to handle keywords, and only the last function in
2338 the chain (built into the Perl core) will normally return
2339 "KEYWORD_PLUGIN_DECLINE".
2340
2341 For thread safety, modules should not set this variable
2342 directly. Instead, use the function "wrap_keyword_plugin".
2343
2344 PL_phase
2345 A value that indicates the current Perl interpreter's phase.
2346 Possible values include "PERL_PHASE_CONSTRUCT",
2347 "PERL_PHASE_START", "PERL_PHASE_CHECK", "PERL_PHASE_INIT",
2348 "PERL_PHASE_RUN", "PERL_PHASE_END", and "PERL_PHASE_DESTRUCT".
2349
2350 For example, the following determines whether the interpreter
2351 is in global destruction:
2352
2353 if (PL_phase == PERL_PHASE_DESTRUCT) {
2354 // we are in global destruction
2355 }
2356
2357 "PL_phase" was introduced in Perl 5.14; in prior perls you can
2358 use "PL_dirty" (boolean) to determine whether the interpreter
2359 is in global destruction. (Use of "PL_dirty" is discouraged
2360 since 5.14.)
2361
2362 enum perl_phase PL_phase
2363
2365 A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
2366 It is a structure that holds a pointer to a scalar, an array, a hash
2367 etc, corresponding to $foo, @foo, %foo.
2368
2369 GVs are usually found as values in stashes (symbol table hashes) where
2370 Perl stores its global variables.
2371
2372 GvAV Return the AV from the GV.
2373
2374 AV* GvAV(GV* gv)
2375
2376 gv_const_sv
2377 If "gv" is a typeglob whose subroutine entry is a constant sub
2378 eligible for inlining, or "gv" is a placeholder reference that
2379 would be promoted to such a typeglob, then returns the value
2380 returned by the sub. Otherwise, returns "NULL".
2381
2382 SV* gv_const_sv(GV* gv)
2383
2384 GvCV Return the CV from the GV.
2385
2386 CV* GvCV(GV* gv)
2387
2388 gv_fetchmeth
2389 Like "gv_fetchmeth_pvn", but lacks a flags parameter.
2390
2391 GV* gv_fetchmeth(HV* stash, const char* name,
2392 STRLEN len, I32 level)
2393
2394 gv_fetchmethod_autoload
2395 Returns the glob which contains the subroutine to call to
2396 invoke the method on the "stash". In fact in the presence of
2397 autoloading this may be the glob for "AUTOLOAD". In this case
2398 the corresponding variable $AUTOLOAD is already setup.
2399
2400 The third parameter of "gv_fetchmethod_autoload" determines
2401 whether AUTOLOAD lookup is performed if the given method is not
2402 present: non-zero means yes, look for AUTOLOAD; zero means no,
2403 don't look for AUTOLOAD. Calling "gv_fetchmethod" is
2404 equivalent to calling "gv_fetchmethod_autoload" with a non-zero
2405 "autoload" parameter.
2406
2407 These functions grant "SUPER" token as a prefix of the method
2408 name. Note that if you want to keep the returned glob for a
2409 long time, you need to check for it being "AUTOLOAD", since at
2410 the later time the call may load a different subroutine due to
2411 $AUTOLOAD changing its value. Use the glob created as a side
2412 effect to do this.
2413
2414 These functions have the same side-effects as "gv_fetchmeth"
2415 with "level==0". The warning against passing the GV returned
2416 by "gv_fetchmeth" to "call_sv" applies equally to these
2417 functions.
2418
2419 GV* gv_fetchmethod_autoload(HV* stash,
2420 const char* name,
2421 I32 autoload)
2422
2423 gv_fetchmeth_autoload
2424 This is the old form of "gv_fetchmeth_pvn_autoload", which has
2425 no flags parameter.
2426
2427 GV* gv_fetchmeth_autoload(HV* stash,
2428 const char* name,
2429 STRLEN len, I32 level)
2430
2431 gv_fetchmeth_pv
2432 Exactly like "gv_fetchmeth_pvn", but takes a nul-terminated
2433 string instead of a string/length pair.
2434
2435 GV* gv_fetchmeth_pv(HV* stash, const char* name,
2436 I32 level, U32 flags)
2437
2438 gv_fetchmeth_pvn
2439 Returns the glob with the given "name" and a defined subroutine
2440 or "NULL". The glob lives in the given "stash", or in the
2441 stashes accessible via @ISA and "UNIVERSAL::".
2442
2443 The argument "level" should be either 0 or -1. If "level==0",
2444 as a side-effect creates a glob with the given "name" in the
2445 given "stash" which in the case of success contains an alias
2446 for the subroutine, and sets up caching info for this glob.
2447
2448 The only significant values for "flags" are "GV_SUPER" and
2449 "SVf_UTF8".
2450
2451 "GV_SUPER" indicates that we want to look up the method in the
2452 superclasses of the "stash".
2453
2454 The GV returned from "gv_fetchmeth" may be a method cache
2455 entry, which is not visible to Perl code. So when calling
2456 "call_sv", you should not use the GV directly; instead, you
2457 should use the method's CV, which can be obtained from the GV
2458 with the "GvCV" macro.
2459
2460 GV* gv_fetchmeth_pvn(HV* stash, const char* name,
2461 STRLEN len, I32 level,
2462 U32 flags)
2463
2464 gv_fetchmeth_pvn_autoload
2465 Same as "gv_fetchmeth_pvn()", but looks for autoloaded
2466 subroutines too. Returns a glob for the subroutine.
2467
2468 For an autoloaded subroutine without a GV, will create a GV
2469 even if "level < 0". For an autoloaded subroutine without a
2470 stub, "GvCV()" of the result may be zero.
2471
2472 Currently, the only significant value for "flags" is
2473 "SVf_UTF8".
2474
2475 GV* gv_fetchmeth_pvn_autoload(HV* stash,
2476 const char* name,
2477 STRLEN len, I32 level,
2478 U32 flags)
2479
2480 gv_fetchmeth_pv_autoload
2481 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-
2482 terminated string instead of a string/length pair.
2483
2484 GV* gv_fetchmeth_pv_autoload(HV* stash,
2485 const char* name,
2486 I32 level, U32 flags)
2487
2488 gv_fetchmeth_sv
2489 Exactly like "gv_fetchmeth_pvn", but takes the name string in
2490 the form of an SV instead of a string/length pair.
2491
2492 GV* gv_fetchmeth_sv(HV* stash, SV* namesv,
2493 I32 level, U32 flags)
2494
2495 gv_fetchmeth_sv_autoload
2496 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name
2497 string in the form of an SV instead of a string/length pair.
2498
2499 GV* gv_fetchmeth_sv_autoload(HV* stash, SV* namesv,
2500 I32 level, U32 flags)
2501
2502 GvHV Return the HV from the GV.
2503
2504 HV* GvHV(GV* gv)
2505
2506 gv_init The old form of "gv_init_pvn()". It does not work with UTF-8
2507 strings, as it has no flags parameter. If the "multi"
2508 parameter is set, the "GV_ADDMULTI" flag will be passed to
2509 "gv_init_pvn()".
2510
2511 void gv_init(GV* gv, HV* stash, const char* name,
2512 STRLEN len, int multi)
2513
2514 gv_init_pv
2515 Same as "gv_init_pvn()", but takes a nul-terminated string for
2516 the name instead of separate char * and length parameters.
2517
2518 void gv_init_pv(GV* gv, HV* stash, const char* name,
2519 U32 flags)
2520
2521 gv_init_pvn
2522 Converts a scalar into a typeglob. This is an incoercible
2523 typeglob; assigning a reference to it will assign to one of its
2524 slots, instead of overwriting it as happens with typeglobs
2525 created by "SvSetSV". Converting any scalar that is "SvOK()"
2526 may produce unpredictable results and is reserved for perl's
2527 internal use.
2528
2529 "gv" is the scalar to be converted.
2530
2531 "stash" is the parent stash/package, if any.
2532
2533 "name" and "len" give the name. The name must be unqualified;
2534 that is, it must not include the package name. If "gv" is a
2535 stash element, it is the caller's responsibility to ensure that
2536 the name passed to this function matches the name of the
2537 element. If it does not match, perl's internal bookkeeping
2538 will get out of sync.
2539
2540 "flags" can be set to "SVf_UTF8" if "name" is a UTF-8 string,
2541 or the return value of SvUTF8(sv). It can also take the
2542 "GV_ADDMULTI" flag, which means to pretend that the GV has been
2543 seen before (i.e., suppress "Used once" warnings).
2544
2545 void gv_init_pvn(GV* gv, HV* stash, const char* name,
2546 STRLEN len, U32 flags)
2547
2548 gv_init_sv
2549 Same as "gv_init_pvn()", but takes an SV * for the name instead
2550 of separate char * and length parameters. "flags" is currently
2551 unused.
2552
2553 void gv_init_sv(GV* gv, HV* stash, SV* namesv,
2554 U32 flags)
2555
2556 gv_stashpv
2557 Returns a pointer to the stash for a specified package. Uses
2558 "strlen" to determine the length of "name", then calls
2559 "gv_stashpvn()".
2560
2561 HV* gv_stashpv(const char* name, I32 flags)
2562
2563 gv_stashpvn
2564 Returns a pointer to the stash for a specified package. The
2565 "namelen" parameter indicates the length of the "name", in
2566 bytes. "flags" is passed to "gv_fetchpvn_flags()", so if set
2567 to "GV_ADD" then the package will be created if it does not
2568 already exist. If the package does not exist and "flags" is 0
2569 (or any other setting that does not create packages) then
2570 "NULL" is returned.
2571
2572 Flags may be one of:
2573
2574 GV_ADD
2575 SVf_UTF8
2576 GV_NOADD_NOINIT
2577 GV_NOINIT
2578 GV_NOEXPAND
2579 GV_ADDMG
2580
2581 The most important of which are probably "GV_ADD" and
2582 "SVf_UTF8".
2583
2584 Note, use of "gv_stashsv" instead of "gv_stashpvn" where
2585 possible is strongly recommended for performance reasons.
2586
2587 HV* gv_stashpvn(const char* name, U32 namelen,
2588 I32 flags)
2589
2590 gv_stashpvs
2591 Like "gv_stashpvn", but takes a literal string instead of a
2592 string/length pair.
2593
2594 HV* gv_stashpvs("name", I32 create)
2595
2596 gv_stashsv
2597 Returns a pointer to the stash for a specified package. See
2598 "gv_stashpvn".
2599
2600 Note this interface is strongly preferred over "gv_stashpvn"
2601 for performance reasons.
2602
2603 HV* gv_stashsv(SV* sv, I32 flags)
2604
2605 GvSV Return the SV from the GV.
2606
2607 SV* GvSV(GV* gv)
2608
2609 save_gp Saves the current GP of gv on the save stack to be restored on
2610 scope exit.
2611
2612 If empty is true, replace the GP with a new GP.
2613
2614 If empty is false, mark gv with GVf_INTRO so the next reference
2615 assigned is localized, which is how " local *foo = $someref; "
2616 works.
2617
2618 void save_gp(GV* gv, I32 empty)
2619
2620 setdefout
2621 Sets "PL_defoutgv", the default file handle for output, to the
2622 passed in typeglob. As "PL_defoutgv" "owns" a reference on its
2623 typeglob, the reference count of the passed in typeglob is
2624 increased by one, and the reference count of the typeglob that
2625 "PL_defoutgv" points to is decreased by one.
2626
2627 void setdefout(GV* gv)
2628
2630 C_ARRAY_END
2631 Returns a pointer to one element past the final element of the
2632 input C array.
2633
2634 void * C_ARRAY_END(void *a)
2635
2636 C_ARRAY_LENGTH
2637 Returns the number of elements in the input C array (so you
2638 want your zero-based indices to be less than but not equal to).
2639
2640 STRLEN C_ARRAY_LENGTH(void *a)
2641
2642 cBOOL Cast-to-bool. A simple "(bool) expr" cast may not do the right
2643 thing: if "bool" is defined as "char", for example, then the
2644 cast from "int" is implementation-defined.
2645
2646 "(bool)!!(cbool)" in a ternary triggers a bug in xlc on AIX
2647
2648 bool cBOOL(bool expr)
2649
2650 Nullav DEPRECATED! It is planned to remove this function from a
2651 future release of Perl. Do not use it for new code; remove it
2652 from existing code.
2653
2654 Null AV pointer.
2655
2656 (deprecated - use "(AV *)NULL" instead)
2657
2658 Nullch Null character pointer. (No longer available when "PERL_CORE"
2659 is defined.)
2660
2661 Nullcv DEPRECATED! It is planned to remove this function from a
2662 future release of Perl. Do not use it for new code; remove it
2663 from existing code.
2664
2665 Null CV pointer.
2666
2667 (deprecated - use "(CV *)NULL" instead)
2668
2669 Nullhv DEPRECATED! It is planned to remove this function from a
2670 future release of Perl. Do not use it for new code; remove it
2671 from existing code.
2672
2673 Null HV pointer.
2674
2675 (deprecated - use "(HV *)NULL" instead)
2676
2677 Nullsv Null SV pointer. (No longer available when "PERL_CORE" is
2678 defined.)
2679
2680 STR_WITH_LEN
2681 Returns two comma separated tokens of the input literal string,
2682 and its length. This is convenience macro which helps out in
2683 some API calls. Note that it can't be used as an argument to
2684 macros or functions that under some configurations might be
2685 macros, which means that it requires the full Perl_xxx(aTHX_
2686 ...) form for any API calls where it's used.
2687
2688 pair STR_WITH_LEN("literal string")
2689
2690 __ASSERT_
2691 This is a helper macro to avoid preprocessor issues, replaced
2692 by nothing unless under DEBUGGING, where it expands to an
2693 assert of its argument, followed by a comma (hence the comma
2694 operator). If we just used a straight assert(), we would get a
2695 comma with nothing before it when not DEBUGGING.
2696
2697 void __ASSERT_(bool expr)
2698
2700 A HV structure represents a Perl hash. It consists mainly of an array
2701 of pointers, each of which points to a linked list of HE structures.
2702 The array is indexed by the hash function of the key, so each linked
2703 list represents all the hash entries with the same hash value. Each HE
2704 contains a pointer to the actual value, plus a pointer to a HEK
2705 structure which holds the key and hash value.
2706
2707 cop_fetch_label
2708 NOTE: this function is experimental and may change or be
2709 removed without notice.
2710
2711 Returns the label attached to a cop, and stores its length in
2712 bytes into *len. Upon return, *flags will be set to either
2713 "SVf_UTF8" or 0.
2714
2715 Alternatively, use the macro ""CopLABEL_len_flags""; or if you
2716 don't need to know if the label is UTF-8 or not, the macro
2717 ""CopLABEL_len""; or if you additionally dont need to know the
2718 length, ""CopLABEL"".
2719
2720 const char * cop_fetch_label(COP *const cop,
2721 STRLEN *len, U32 *flags)
2722
2723 cop_store_label
2724 NOTE: this function is experimental and may change or be
2725 removed without notice.
2726
2727 Save a label into a "cop_hints_hash". You need to set flags to
2728 "SVf_UTF8" for a UTF-8 label. Any other flag is ignored.
2729
2730 void cop_store_label(COP *const cop,
2731 const char *label, STRLEN len,
2732 U32 flags)
2733
2734 get_hv Returns the HV of the specified Perl hash. "flags" are passed
2735 to "gv_fetchpv". If "GV_ADD" is set and the Perl variable does
2736 not exist then it will be created. If "flags" is zero and the
2737 variable does not exist then "NULL" is returned.
2738
2739 NOTE: the perl_ form of this function is deprecated.
2740
2741 HV* get_hv(const char *name, I32 flags)
2742
2743 HEf_SVKEY
2744 This flag, used in the length slot of hash entries and magic
2745 structures, specifies the structure contains an "SV*" pointer
2746 where a "char*" pointer is to be expected. (For information
2747 only--not to be used).
2748
2749 HeHASH Returns the computed hash stored in the hash entry.
2750
2751 U32 HeHASH(HE* he)
2752
2753 HeKEY Returns the actual pointer stored in the key slot of the hash
2754 entry. The pointer may be either "char*" or "SV*", depending
2755 on the value of "HeKLEN()". Can be assigned to. The "HePV()"
2756 or "HeSVKEY()" macros are usually preferable for finding the
2757 value of a key.
2758
2759 void* HeKEY(HE* he)
2760
2761 HeKLEN If this is negative, and amounts to "HEf_SVKEY", it indicates
2762 the entry holds an "SV*" key. Otherwise, holds the actual
2763 length of the key. Can be assigned to. The "HePV()" macro is
2764 usually preferable for finding key lengths.
2765
2766 STRLEN HeKLEN(HE* he)
2767
2768 HePV Returns the key slot of the hash entry as a "char*" value,
2769 doing any necessary dereferencing of possibly "SV*" keys. The
2770 length of the string is placed in "len" (this is a macro, so do
2771 not use &len). If you do not care about what the length of the
2772 key is, you may use the global variable "PL_na", though this is
2773 rather less efficient than using a local variable. Remember
2774 though, that hash keys in perl are free to contain embedded
2775 nulls, so using "strlen()" or similar is not a good way to find
2776 the length of hash keys. This is very similar to the "SvPV()"
2777 macro described elsewhere in this document. See also "HeUTF8".
2778
2779 If you are using "HePV" to get values to pass to "newSVpvn()"
2780 to create a new SV, you should consider using
2781 "newSVhek(HeKEY_hek(he))" as it is more efficient.
2782
2783 char* HePV(HE* he, STRLEN len)
2784
2785 HeSVKEY Returns the key as an "SV*", or "NULL" if the hash entry does
2786 not contain an "SV*" key.
2787
2788 SV* HeSVKEY(HE* he)
2789
2790 HeSVKEY_force
2791 Returns the key as an "SV*". Will create and return a
2792 temporary mortal "SV*" if the hash entry contains only a
2793 "char*" key.
2794
2795 SV* HeSVKEY_force(HE* he)
2796
2797 HeSVKEY_set
2798 Sets the key to a given "SV*", taking care to set the
2799 appropriate flags to indicate the presence of an "SV*" key, and
2800 returns the same "SV*".
2801
2802 SV* HeSVKEY_set(HE* he, SV* sv)
2803
2804 HeUTF8 Returns whether the "char *" value returned by "HePV" is
2805 encoded in UTF-8, doing any necessary dereferencing of possibly
2806 "SV*" keys. The value returned will be 0 or non-0, not
2807 necessarily 1 (or even a value with any low bits set), so do
2808 not blindly assign this to a "bool" variable, as "bool" may be
2809 a typedef for "char".
2810
2811 U32 HeUTF8(HE* he)
2812
2813 HeVAL Returns the value slot (type "SV*") stored in the hash entry.
2814 Can be assigned to.
2815
2816 SV *foo= HeVAL(hv);
2817 HeVAL(hv)= sv;
2818
2819
2820 SV* HeVAL(HE* he)
2821
2822 hv_assert
2823 Check that a hash is in an internally consistent state.
2824
2825 NOTE: this function must be explicitly called as Perl_hv_assert
2826 with an aTHX_ parameter.
2827
2828 void Perl_hv_assert(pTHX_ HV *hv)
2829
2830 hv_bucket_ratio
2831 NOTE: this function is experimental and may change or be
2832 removed without notice.
2833
2834 If the hash is tied dispatches through to the SCALAR tied
2835 method, otherwise if the hash contains no keys returns 0,
2836 otherwise returns a mortal sv containing a string specifying
2837 the number of used buckets, followed by a slash, followed by
2838 the number of available buckets.
2839
2840 This function is expensive, it must scan all of the buckets to
2841 determine which are used, and the count is NOT cached. In a
2842 large hash this could be a lot of buckets.
2843
2844 SV* hv_bucket_ratio(HV *hv)
2845
2846 hv_clear
2847 Frees the all the elements of a hash, leaving it empty. The XS
2848 equivalent of "%hash = ()". See also "hv_undef".
2849
2850 See "av_clear" for a note about the hash possibly being invalid
2851 on return.
2852
2853 void hv_clear(HV *hv)
2854
2855 hv_clear_placeholders
2856 Clears any placeholders from a hash. If a restricted hash has
2857 any of its keys marked as readonly and the key is subsequently
2858 deleted, the key is not actually deleted but is marked by
2859 assigning it a value of &PL_sv_placeholder. This tags it so it
2860 will be ignored by future operations such as iterating over the
2861 hash, but will still allow the hash to have a value reassigned
2862 to the key at some future point. This function clears any such
2863 placeholder keys from the hash. See "Hash::Util::lock_keys()"
2864 for an example of its use.
2865
2866 void hv_clear_placeholders(HV *hv)
2867
2868 hv_copy_hints_hv
2869 A specialised version of "newHVhv" for copying "%^H". "ohv"
2870 must be a pointer to a hash (which may have "%^H" magic, but
2871 should be generally non-magical), or "NULL" (interpreted as an
2872 empty hash). The content of "ohv" is copied to a new hash,
2873 which has the "%^H"-specific magic added to it. A pointer to
2874 the new hash is returned.
2875
2876 HV * hv_copy_hints_hv(HV *const ohv)
2877
2878 hv_delete
2879 Deletes a key/value pair in the hash. The value's SV is
2880 removed from the hash, made mortal, and returned to the caller.
2881 The absolute value of "klen" is the length of the key. If
2882 "klen" is negative the key is assumed to be in UTF-8-encoded
2883 Unicode. The "flags" value will normally be zero; if set to
2884 "G_DISCARD" then "NULL" will be returned. "NULL" will also be
2885 returned if the key is not found.
2886
2887 SV* hv_delete(HV *hv, const char *key, I32 klen,
2888 I32 flags)
2889
2890 hv_delete_ent
2891 Deletes a key/value pair in the hash. The value SV is removed
2892 from the hash, made mortal, and returned to the caller. The
2893 "flags" value will normally be zero; if set to "G_DISCARD" then
2894 "NULL" will be returned. "NULL" will also be returned if the
2895 key is not found. "hash" can be a valid precomputed hash
2896 value, or 0 to ask for it to be computed.
2897
2898 SV* hv_delete_ent(HV *hv, SV *keysv, I32 flags,
2899 U32 hash)
2900
2901 HvENAME Returns the effective name of a stash, or NULL if there is
2902 none. The effective name represents a location in the symbol
2903 table where this stash resides. It is updated automatically
2904 when packages are aliased or deleted. A stash that is no
2905 longer in the symbol table has no effective name. This name is
2906 preferable to "HvNAME" for use in MRO linearisations and isa
2907 caches.
2908
2909 char* HvENAME(HV* stash)
2910
2911 HvENAMELEN
2912 Returns the length of the stash's effective name.
2913
2914 STRLEN HvENAMELEN(HV *stash)
2915
2916 HvENAMEUTF8
2917 Returns true if the effective name is in UTF-8 encoding.
2918
2919 unsigned char HvENAMEUTF8(HV *stash)
2920
2921 hv_exists
2922 Returns a boolean indicating whether the specified hash key
2923 exists. The absolute value of "klen" is the length of the key.
2924 If "klen" is negative the key is assumed to be in UTF-8-encoded
2925 Unicode.
2926
2927 bool hv_exists(HV *hv, const char *key, I32 klen)
2928
2929 hv_exists_ent
2930 Returns a boolean indicating whether the specified hash key
2931 exists. "hash" can be a valid precomputed hash value, or 0 to
2932 ask for it to be computed.
2933
2934 bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
2935
2936 hv_fetch
2937 Returns the SV which corresponds to the specified key in the
2938 hash. The absolute value of "klen" is the length of the key.
2939 If "klen" is negative the key is assumed to be in UTF-8-encoded
2940 Unicode. If "lval" is set then the fetch will be part of a
2941 store. This means that if there is no value in the hash
2942 associated with the given key, then one is created and a
2943 pointer to it is returned. The "SV*" it points to can be
2944 assigned to. But always check that the return value is non-
2945 null before dereferencing it to an "SV*".
2946
2947 See "Understanding the Magic of Tied Hashes and Arrays" in
2948 perlguts for more information on how to use this function on
2949 tied hashes.
2950
2951 SV** hv_fetch(HV *hv, const char *key, I32 klen,
2952 I32 lval)
2953
2954 hv_fetchs
2955 Like "hv_fetch", but takes a literal string instead of a
2956 string/length pair.
2957
2958 SV** hv_fetchs(HV* tb, "key", I32 lval)
2959
2960 hv_fetch_ent
2961 Returns the hash entry which corresponds to the specified key
2962 in the hash. "hash" must be a valid precomputed hash number
2963 for the given "key", or 0 if you want the function to compute
2964 it. IF "lval" is set then the fetch will be part of a store.
2965 Make sure the return value is non-null before accessing it.
2966 The return value when "hv" is a tied hash is a pointer to a
2967 static location, so be sure to make a copy of the structure if
2968 you need to store it somewhere.
2969
2970 See "Understanding the Magic of Tied Hashes and Arrays" in
2971 perlguts for more information on how to use this function on
2972 tied hashes.
2973
2974 HE* hv_fetch_ent(HV *hv, SV *keysv, I32 lval,
2975 U32 hash)
2976
2977 HvFILL See "hv_fill".
2978
2979 STRLEN HvFILL(HV *const hv)
2980
2981 hv_fill Returns the number of hash buckets that happen to be in use.
2982
2983 This function is wrapped by the macro "HvFILL".
2984
2985 As of perl 5.25 this function is used only for debugging
2986 purposes, and the number of used hash buckets is not in any way
2987 cached, thus this function can be costly to execute as it must
2988 iterate over all the buckets in the hash.
2989
2990 NOTE: this function must be explicitly called as Perl_hv_fill
2991 with an aTHX_ parameter.
2992
2993 STRLEN Perl_hv_fill(pTHX_ HV *const hv)
2994
2995 hv_iterinit
2996 Prepares a starting point to traverse a hash table. Returns
2997 the number of keys in the hash, including placeholders (i.e.
2998 the same as "HvTOTALKEYS(hv)"). The return value is currently
2999 only meaningful for hashes without tie magic.
3000
3001 NOTE: Before version 5.004_65, "hv_iterinit" used to return the
3002 number of hash buckets that happen to be in use. If you still
3003 need that esoteric value, you can get it through the macro
3004 "HvFILL(hv)".
3005
3006 I32 hv_iterinit(HV *hv)
3007
3008 hv_iterkey
3009 Returns the key from the current position of the hash iterator.
3010 See "hv_iterinit".
3011
3012 char* hv_iterkey(HE* entry, I32* retlen)
3013
3014 hv_iterkeysv
3015 Returns the key as an "SV*" from the current position of the
3016 hash iterator. The return value will always be a mortal copy
3017 of the key. Also see "hv_iterinit".
3018
3019 SV* hv_iterkeysv(HE* entry)
3020
3021 hv_iternext
3022 Returns entries from a hash iterator. See "hv_iterinit".
3023
3024 You may call "hv_delete" or "hv_delete_ent" on the hash entry
3025 that the iterator currently points to, without losing your
3026 place or invalidating your iterator. Note that in this case
3027 the current entry is deleted from the hash with your iterator
3028 holding the last reference to it. Your iterator is flagged to
3029 free the entry on the next call to "hv_iternext", so you must
3030 not discard your iterator immediately else the entry will leak
3031 - call "hv_iternext" to trigger the resource deallocation.
3032
3033 HE* hv_iternext(HV *hv)
3034
3035 hv_iternextsv
3036 Performs an "hv_iternext", "hv_iterkey", and "hv_iterval" in
3037 one operation.
3038
3039 SV* hv_iternextsv(HV *hv, char **key, I32 *retlen)
3040
3041 hv_iternext_flags
3042 NOTE: this function is experimental and may change or be
3043 removed without notice.
3044
3045 Returns entries from a hash iterator. See "hv_iterinit" and
3046 "hv_iternext". The "flags" value will normally be zero; if
3047 "HV_ITERNEXT_WANTPLACEHOLDERS" is set the placeholders keys
3048 (for restricted hashes) will be returned in addition to normal
3049 keys. By default placeholders are automatically skipped over.
3050 Currently a placeholder is implemented with a value that is
3051 &PL_sv_placeholder. Note that the implementation of
3052 placeholders and restricted hashes may change, and the
3053 implementation currently is insufficiently abstracted for any
3054 change to be tidy.
3055
3056 HE* hv_iternext_flags(HV *hv, I32 flags)
3057
3058 hv_iterval
3059 Returns the value from the current position of the hash
3060 iterator. See "hv_iterkey".
3061
3062 SV* hv_iterval(HV *hv, HE *entry)
3063
3064 hv_magic
3065 Adds magic to a hash. See "sv_magic".
3066
3067 void hv_magic(HV *hv, GV *gv, int how)
3068
3069 HvNAME Returns the package name of a stash, or "NULL" if "stash" isn't
3070 a stash. See "SvSTASH", "CvSTASH".
3071
3072 char* HvNAME(HV* stash)
3073
3074 HvNAMELEN
3075 Returns the length of the stash's name.
3076
3077 STRLEN HvNAMELEN(HV *stash)
3078
3079 HvNAMEUTF8
3080 Returns true if the name is in UTF-8 encoding.
3081
3082 unsigned char HvNAMEUTF8(HV *stash)
3083
3084 hv_scalar
3085 Evaluates the hash in scalar context and returns the result.
3086
3087 When the hash is tied dispatches through to the SCALAR method,
3088 otherwise returns a mortal SV containing the number of keys in
3089 the hash.
3090
3091 Note, prior to 5.25 this function returned what is now returned
3092 by the hv_bucket_ratio() function.
3093
3094 SV* hv_scalar(HV *hv)
3095
3096 hv_store
3097 Stores an SV in a hash. The hash key is specified as "key" and
3098 the absolute value of "klen" is the length of the key. If
3099 "klen" is negative the key is assumed to be in UTF-8-encoded
3100 Unicode. The "hash" parameter is the precomputed hash value;
3101 if it is zero then Perl will compute it.
3102
3103 The return value will be "NULL" if the operation failed or if
3104 the value did not need to be actually stored within the hash
3105 (as in the case of tied hashes). Otherwise it can be
3106 dereferenced to get the original "SV*". Note that the caller
3107 is responsible for suitably incrementing the reference count of
3108 "val" before the call, and decrementing it if the function
3109 returned "NULL". Effectively a successful "hv_store" takes
3110 ownership of one reference to "val". This is usually what you
3111 want; a newly created SV has a reference count of one, so if
3112 all your code does is create SVs then store them in a hash,
3113 "hv_store" will own the only reference to the new SV, and your
3114 code doesn't need to do anything further to tidy up.
3115 "hv_store" is not implemented as a call to "hv_store_ent", and
3116 does not create a temporary SV for the key, so if your key data
3117 is not already in SV form then use "hv_store" in preference to
3118 "hv_store_ent".
3119
3120 See "Understanding the Magic of Tied Hashes and Arrays" in
3121 perlguts for more information on how to use this function on
3122 tied hashes.
3123
3124 SV** hv_store(HV *hv, const char *key, I32 klen,
3125 SV *val, U32 hash)
3126
3127 hv_stores
3128 Like "hv_store", but takes a literal string instead of a
3129 string/length pair and omits the hash parameter.
3130
3131 SV** hv_stores(HV* tb, "key", SV* val)
3132
3133 hv_store_ent
3134 Stores "val" in a hash. The hash key is specified as "key".
3135 The "hash" parameter is the precomputed hash value; if it is
3136 zero then Perl will compute it. The return value is the new
3137 hash entry so created. It will be "NULL" if the operation
3138 failed or if the value did not need to be actually stored
3139 within the hash (as in the case of tied hashes). Otherwise the
3140 contents of the return value can be accessed using the "He?"
3141 macros described here. Note that the caller is responsible for
3142 suitably incrementing the reference count of "val" before the
3143 call, and decrementing it if the function returned NULL.
3144 Effectively a successful "hv_store_ent" takes ownership of one
3145 reference to "val". This is usually what you want; a newly
3146 created SV has a reference count of one, so if all your code
3147 does is create SVs then store them in a hash, "hv_store" will
3148 own the only reference to the new SV, and your code doesn't
3149 need to do anything further to tidy up. Note that
3150 "hv_store_ent" only reads the "key"; unlike "val" it does not
3151 take ownership of it, so maintaining the correct reference
3152 count on "key" is entirely the caller's responsibility. The
3153 reason it does not take ownership, is that "key" is not used
3154 after this function returns, and so can be freed immediately.
3155 "hv_store" is not implemented as a call to "hv_store_ent", and
3156 does not create a temporary SV for the key, so if your key data
3157 is not already in SV form then use "hv_store" in preference to
3158 "hv_store_ent".
3159
3160 See "Understanding the Magic of Tied Hashes and Arrays" in
3161 perlguts for more information on how to use this function on
3162 tied hashes.
3163
3164 HE* hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
3165
3166 hv_undef
3167 Undefines the hash. The XS equivalent of "undef(%hash)".
3168
3169 As well as freeing all the elements of the hash (like
3170 "hv_clear()"), this also frees any auxiliary data and storage
3171 associated with the hash.
3172
3173 See "av_clear" for a note about the hash possibly being invalid
3174 on return.
3175
3176 void hv_undef(HV *hv)
3177
3178 newHV Creates a new HV. The reference count is set to 1.
3179
3180 HV* newHV()
3181
3183 These functions provide convenient and thread-safe means of
3184 manipulating hook variables.
3185
3186 wrap_op_checker
3187 Puts a C function into the chain of check functions for a
3188 specified op type. This is the preferred way to manipulate the
3189 "PL_check" array. "opcode" specifies which type of op is to be
3190 affected. "new_checker" is a pointer to the C function that is
3191 to be added to that opcode's check chain, and "old_checker_p"
3192 points to the storage location where a pointer to the next
3193 function in the chain will be stored. The value of
3194 "new_checker" is written into the "PL_check" array, while the
3195 value previously stored there is written to *old_checker_p.
3196
3197 "PL_check" is global to an entire process, and a module wishing
3198 to hook op checking may find itself invoked more than once per
3199 process, typically in different threads. To handle that
3200 situation, this function is idempotent. The location
3201 *old_checker_p must initially (once per process) contain a null
3202 pointer. A C variable of static duration (declared at file
3203 scope, typically also marked "static" to give it internal
3204 linkage) will be implicitly initialised appropriately, if it
3205 does not have an explicit initialiser. This function will only
3206 actually modify the check chain if it finds *old_checker_p to
3207 be null. This function is also thread safe on the small scale.
3208 It uses appropriate locking to avoid race conditions in
3209 accessing "PL_check".
3210
3211 When this function is called, the function referenced by
3212 "new_checker" must be ready to be called, except for
3213 *old_checker_p being unfilled. In a threading situation,
3214 "new_checker" may be called immediately, even before this
3215 function has returned. *old_checker_p will always be
3216 appropriately set before "new_checker" is called. If
3217 "new_checker" decides not to do anything special with an op
3218 that it is given (which is the usual case for most uses of op
3219 check hooking), it must chain the check function referenced by
3220 *old_checker_p.
3221
3222 Taken all together, XS code to hook an op checker should
3223 typically look something like this:
3224
3225 static Perl_check_t nxck_frob;
3226 static OP *myck_frob(pTHX_ OP *op) {
3227 ...
3228 op = nxck_frob(aTHX_ op);
3229 ...
3230 return op;
3231 }
3232 BOOT:
3233 wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
3234
3235 If you want to influence compilation of calls to a specific
3236 subroutine, then use "cv_set_call_checker_flags" rather than
3237 hooking checking of all "entersub" ops.
3238
3239 void wrap_op_checker(Optype opcode,
3240 Perl_check_t new_checker,
3241 Perl_check_t *old_checker_p)
3242
3244 This is the lower layer of the Perl parser, managing characters and
3245 tokens.
3246
3247 lex_bufutf8
3248 NOTE: this function is experimental and may change or be
3249 removed without notice.
3250
3251 Indicates whether the octets in the lexer buffer
3252 ("PL_parser->linestr") should be interpreted as the UTF-8
3253 encoding of Unicode characters. If not, they should be
3254 interpreted as Latin-1 characters. This is analogous to the
3255 "SvUTF8" flag for scalars.
3256
3257 In UTF-8 mode, it is not guaranteed that the lexer buffer
3258 actually contains valid UTF-8. Lexing code must be robust in
3259 the face of invalid encoding.
3260
3261 The actual "SvUTF8" flag of the "PL_parser->linestr" scalar is
3262 significant, but not the whole story regarding the input
3263 character encoding. Normally, when a file is being read, the
3264 scalar contains octets and its "SvUTF8" flag is off, but the
3265 octets should be interpreted as UTF-8 if the "use utf8" pragma
3266 is in effect. During a string eval, however, the scalar may
3267 have the "SvUTF8" flag on, and in this case its octets should
3268 be interpreted as UTF-8 unless the "use bytes" pragma is in
3269 effect. This logic may change in the future; use this function
3270 instead of implementing the logic yourself.
3271
3272 bool lex_bufutf8()
3273
3274 lex_discard_to
3275 NOTE: this function is experimental and may change or be
3276 removed without notice.
3277
3278 Discards the first part of the "PL_parser->linestr" buffer, up
3279 to "ptr". The remaining content of the buffer will be moved,
3280 and all pointers into the buffer updated appropriately. "ptr"
3281 must not be later in the buffer than the position of
3282 "PL_parser->bufptr": it is not permitted to discard text that
3283 has yet to be lexed.
3284
3285 Normally it is not necessarily to do this directly, because it
3286 suffices to use the implicit discarding behaviour of
3287 "lex_next_chunk" and things based on it. However, if a token
3288 stretches across multiple lines, and the lexing code has kept
3289 multiple lines of text in the buffer for that purpose, then
3290 after completion of the token it would be wise to explicitly
3291 discard the now-unneeded earlier lines, to avoid future multi-
3292 line tokens growing the buffer without bound.
3293
3294 void lex_discard_to(char* ptr)
3295
3296 lex_grow_linestr
3297 NOTE: this function is experimental and may change or be
3298 removed without notice.
3299
3300 Reallocates the lexer buffer ("PL_parser->linestr") to
3301 accommodate at least "len" octets (including terminating
3302 "NUL"). Returns a pointer to the reallocated buffer. This is
3303 necessary before making any direct modification of the buffer
3304 that would increase its length. "lex_stuff_pvn" provides a
3305 more convenient way to insert text into the buffer.
3306
3307 Do not use "SvGROW" or "sv_grow" directly on
3308 "PL_parser->linestr"; this function updates all of the lexer's
3309 variables that point directly into the buffer.
3310
3311 char* lex_grow_linestr(STRLEN len)
3312
3313 lex_next_chunk
3314 NOTE: this function is experimental and may change or be
3315 removed without notice.
3316
3317 Reads in the next chunk of text to be lexed, appending it to
3318 "PL_parser->linestr". This should be called when lexing code
3319 has looked to the end of the current chunk and wants to know
3320 more. It is usual, but not necessary, for lexing to have
3321 consumed the entirety of the current chunk at this time.
3322
3323 If "PL_parser->bufptr" is pointing to the very end of the
3324 current chunk (i.e., the current chunk has been entirely
3325 consumed), normally the current chunk will be discarded at the
3326 same time that the new chunk is read in. If "flags" has the
3327 "LEX_KEEP_PREVIOUS" bit set, the current chunk will not be
3328 discarded. If the current chunk has not been entirely
3329 consumed, then it will not be discarded regardless of the flag.
3330
3331 Returns true if some new text was added to the buffer, or false
3332 if the buffer has reached the end of the input text.
3333
3334 bool lex_next_chunk(U32 flags)
3335
3336 lex_peek_unichar
3337 NOTE: this function is experimental and may change or be
3338 removed without notice.
3339
3340 Looks ahead one (Unicode) character in the text currently being
3341 lexed. Returns the codepoint (unsigned integer value) of the
3342 next character, or -1 if lexing has reached the end of the
3343 input text. To consume the peeked character, use
3344 "lex_read_unichar".
3345
3346 If the next character is in (or extends into) the next chunk of
3347 input text, the next chunk will be read in. Normally the
3348 current chunk will be discarded at the same time, but if
3349 "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3350 chunk will not be discarded.
3351
3352 If the input is being interpreted as UTF-8 and a UTF-8 encoding
3353 error is encountered, an exception is generated.
3354
3355 I32 lex_peek_unichar(U32 flags)
3356
3357 lex_read_space
3358 NOTE: this function is experimental and may change or be
3359 removed without notice.
3360
3361 Reads optional spaces, in Perl style, in the text currently
3362 being lexed. The spaces may include ordinary whitespace
3363 characters and Perl-style comments. "#line" directives are
3364 processed if encountered. "PL_parser->bufptr" is moved past
3365 the spaces, so that it points at a non-space character (or the
3366 end of the input text).
3367
3368 If spaces extend into the next chunk of input text, the next
3369 chunk will be read in. Normally the current chunk will be
3370 discarded at the same time, but if "flags" has the
3371 "LEX_KEEP_PREVIOUS" bit set, then the current chunk will not be
3372 discarded.
3373
3374 void lex_read_space(U32 flags)
3375
3376 lex_read_to
3377 NOTE: this function is experimental and may change or be
3378 removed without notice.
3379
3380 Consume text in the lexer buffer, from "PL_parser->bufptr" up
3381 to "ptr". This advances "PL_parser->bufptr" to match "ptr",
3382 performing the correct bookkeeping whenever a newline character
3383 is passed. This is the normal way to consume lexed text.
3384
3385 Interpretation of the buffer's octets can be abstracted out by
3386 using the slightly higher-level functions "lex_peek_unichar"
3387 and "lex_read_unichar".
3388
3389 void lex_read_to(char* ptr)
3390
3391 lex_read_unichar
3392 NOTE: this function is experimental and may change or be
3393 removed without notice.
3394
3395 Reads the next (Unicode) character in the text currently being
3396 lexed. Returns the codepoint (unsigned integer value) of the
3397 character read, and moves "PL_parser->bufptr" past the
3398 character, or returns -1 if lexing has reached the end of the
3399 input text. To non-destructively examine the next character,
3400 use "lex_peek_unichar" instead.
3401
3402 If the next character is in (or extends into) the next chunk of
3403 input text, the next chunk will be read in. Normally the
3404 current chunk will be discarded at the same time, but if
3405 "flags" has the "LEX_KEEP_PREVIOUS" bit set, then the current
3406 chunk will not be discarded.
3407
3408 If the input is being interpreted as UTF-8 and a UTF-8 encoding
3409 error is encountered, an exception is generated.
3410
3411 I32 lex_read_unichar(U32 flags)
3412
3413 lex_start
3414 NOTE: this function is experimental and may change or be
3415 removed without notice.
3416
3417 Creates and initialises a new lexer/parser state object,
3418 supplying a context in which to lex and parse from a new source
3419 of Perl code. A pointer to the new state object is placed in
3420 "PL_parser". An entry is made on the save stack so that upon
3421 unwinding, the new state object will be destroyed and the
3422 former value of "PL_parser" will be restored. Nothing else
3423 need be done to clean up the parsing context.
3424
3425 The code to be parsed comes from "line" and "rsfp". "line", if
3426 non-null, provides a string (in SV form) containing code to be
3427 parsed. A copy of the string is made, so subsequent
3428 modification of "line" does not affect parsing. "rsfp", if
3429 non-null, provides an input stream from which code will be read
3430 to be parsed. If both are non-null, the code in "line" comes
3431 first and must consist of complete lines of input, and "rsfp"
3432 supplies the remainder of the source.
3433
3434 The "flags" parameter is reserved for future use. Currently it
3435 is only used by perl internally, so extensions should always
3436 pass zero.
3437
3438 void lex_start(SV* line, PerlIO *rsfp, U32 flags)
3439
3440 lex_stuff_pv
3441 NOTE: this function is experimental and may change or be
3442 removed without notice.
3443
3444 Insert characters into the lexer buffer ("PL_parser->linestr"),
3445 immediately after the current lexing point
3446 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3447 This means that lexing code that runs later will see the
3448 characters as if they had appeared in the input. It is not
3449 recommended to do this as part of normal parsing, and most uses
3450 of this facility run the risk of the inserted characters being
3451 interpreted in an unintended manner.
3452
3453 The string to be inserted is represented by octets starting at
3454 "pv" and continuing to the first nul. These octets are
3455 interpreted as either UTF-8 or Latin-1, according to whether
3456 the "LEX_STUFF_UTF8" flag is set in "flags". The characters
3457 are recoded for the lexer buffer, according to how the buffer
3458 is currently being interpreted ("lex_bufutf8"). If it is not
3459 convenient to nul-terminate a string to be inserted, the
3460 "lex_stuff_pvn" function is more appropriate.
3461
3462 void lex_stuff_pv(const char* pv, U32 flags)
3463
3464 lex_stuff_pvn
3465 NOTE: this function is experimental and may change or be
3466 removed without notice.
3467
3468 Insert characters into the lexer buffer ("PL_parser->linestr"),
3469 immediately after the current lexing point
3470 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3471 This means that lexing code that runs later will see the
3472 characters as if they had appeared in the input. It is not
3473 recommended to do this as part of normal parsing, and most uses
3474 of this facility run the risk of the inserted characters being
3475 interpreted in an unintended manner.
3476
3477 The string to be inserted is represented by "len" octets
3478 starting at "pv". These octets are interpreted as either UTF-8
3479 or Latin-1, according to whether the "LEX_STUFF_UTF8" flag is
3480 set in "flags". The characters are recoded for the lexer
3481 buffer, according to how the buffer is currently being
3482 interpreted ("lex_bufutf8"). If a string to be inserted is
3483 available as a Perl scalar, the "lex_stuff_sv" function is more
3484 convenient.
3485
3486 void lex_stuff_pvn(const char* pv, STRLEN len,
3487 U32 flags)
3488
3489 lex_stuff_pvs
3490 NOTE: this function is experimental and may change or be
3491 removed without notice.
3492
3493 Like "lex_stuff_pvn", but takes a literal string instead of a
3494 string/length pair.
3495
3496 void lex_stuff_pvs("pv", U32 flags)
3497
3498 lex_stuff_sv
3499 NOTE: this function is experimental and may change or be
3500 removed without notice.
3501
3502 Insert characters into the lexer buffer ("PL_parser->linestr"),
3503 immediately after the current lexing point
3504 ("PL_parser->bufptr"), reallocating the buffer if necessary.
3505 This means that lexing code that runs later will see the
3506 characters as if they had appeared in the input. It is not
3507 recommended to do this as part of normal parsing, and most uses
3508 of this facility run the risk of the inserted characters being
3509 interpreted in an unintended manner.
3510
3511 The string to be inserted is the string value of "sv". The
3512 characters are recoded for the lexer buffer, according to how
3513 the buffer is currently being interpreted ("lex_bufutf8"). If
3514 a string to be inserted is not already a Perl scalar, the
3515 "lex_stuff_pvn" function avoids the need to construct a scalar.
3516
3517 void lex_stuff_sv(SV* sv, U32 flags)
3518
3519 lex_unstuff
3520 NOTE: this function is experimental and may change or be
3521 removed without notice.
3522
3523 Discards text about to be lexed, from "PL_parser->bufptr" up to
3524 "ptr". Text following "ptr" will be moved, and the buffer
3525 shortened. This hides the discarded text from any lexing code
3526 that runs later, as if the text had never appeared.
3527
3528 This is not the normal way to consume lexed text. For that,
3529 use "lex_read_to".
3530
3531 void lex_unstuff(char* ptr)
3532
3533 parse_arithexpr
3534 NOTE: this function is experimental and may change or be
3535 removed without notice.
3536
3537 Parse a Perl arithmetic expression. This may contain operators
3538 of precedence down to the bit shift operators. The expression
3539 must be followed (and thus terminated) either by a comparison
3540 or lower-precedence operator or by something that would
3541 normally terminate an expression such as semicolon. If "flags"
3542 has the "PARSE_OPTIONAL" bit set, then the expression is
3543 optional, otherwise it is mandatory. It is up to the caller to
3544 ensure that the dynamic parser state ("PL_parser" et al) is
3545 correctly set to reflect the source of the code to be parsed
3546 and the lexical context for the expression.
3547
3548 The op tree representing the expression is returned. If an
3549 optional expression is absent, a null pointer is returned,
3550 otherwise the pointer will be non-null.
3551
3552 If an error occurs in parsing or compilation, in most cases a
3553 valid op tree is returned anyway. The error is reflected in
3554 the parser state, normally resulting in a single exception at
3555 the top level of parsing which covers all the compilation
3556 errors that occurred. Some compilation errors, however, will
3557 throw an exception immediately.
3558
3559 OP* parse_arithexpr(U32 flags)
3560
3561 parse_barestmt
3562 NOTE: this function is experimental and may change or be
3563 removed without notice.
3564
3565 Parse a single unadorned Perl statement. This may be a normal
3566 imperative statement or a declaration that has compile-time
3567 effect. It does not include any label or other affixture. It
3568 is up to the caller to ensure that the dynamic parser state
3569 ("PL_parser" et al) is correctly set to reflect the source of
3570 the code to be parsed and the lexical context for the
3571 statement.
3572
3573 The op tree representing the statement is returned. This may
3574 be a null pointer if the statement is null, for example if it
3575 was actually a subroutine definition (which has compile-time
3576 side effects). If not null, it will be ops directly
3577 implementing the statement, suitable to pass to "newSTATEOP".
3578 It will not normally include a "nextstate" or equivalent op
3579 (except for those embedded in a scope contained entirely within
3580 the statement).
3581
3582 If an error occurs in parsing or compilation, in most cases a
3583 valid op tree (most likely null) is returned anyway. The error
3584 is reflected in the parser state, normally resulting in a
3585 single exception at the top level of parsing which covers all
3586 the compilation errors that occurred. Some compilation errors,
3587 however, will throw an exception immediately.
3588
3589 The "flags" parameter is reserved for future use, and must
3590 always be zero.
3591
3592 OP* parse_barestmt(U32 flags)
3593
3594 parse_block
3595 NOTE: this function is experimental and may change or be
3596 removed without notice.
3597
3598 Parse a single complete Perl code block. This consists of an
3599 opening brace, a sequence of statements, and a closing brace.
3600 The block constitutes a lexical scope, so "my" variables and
3601 various compile-time effects can be contained within it. It is
3602 up to the caller to ensure that the dynamic parser state
3603 ("PL_parser" et al) is correctly set to reflect the source of
3604 the code to be parsed and the lexical context for the
3605 statement.
3606
3607 The op tree representing the code block is returned. This is
3608 always a real op, never a null pointer. It will normally be a
3609 "lineseq" list, including "nextstate" or equivalent ops. No
3610 ops to construct any kind of runtime scope are included by
3611 virtue of it being a block.
3612
3613 If an error occurs in parsing or compilation, in most cases a
3614 valid op tree (most likely null) is returned anyway. The error
3615 is reflected in the parser state, normally resulting in a
3616 single exception at the top level of parsing which covers all
3617 the compilation errors that occurred. Some compilation errors,
3618 however, will throw an exception immediately.
3619
3620 The "flags" parameter is reserved for future use, and must
3621 always be zero.
3622
3623 OP* parse_block(U32 flags)
3624
3625 parse_fullexpr
3626 NOTE: this function is experimental and may change or be
3627 removed without notice.
3628
3629 Parse a single complete Perl expression. This allows the full
3630 expression grammar, including the lowest-precedence operators
3631 such as "or". The expression must be followed (and thus
3632 terminated) by a token that an expression would normally be
3633 terminated by: end-of-file, closing bracketing punctuation,
3634 semicolon, or one of the keywords that signals a postfix
3635 expression-statement modifier. If "flags" has the
3636 "PARSE_OPTIONAL" bit set, then the expression is optional,
3637 otherwise it is mandatory. It is up to the caller to ensure
3638 that the dynamic parser state ("PL_parser" et al) is correctly
3639 set to reflect the source of the code to be parsed and the
3640 lexical context for the expression.
3641
3642 The op tree representing the expression is returned. If an
3643 optional expression is absent, a null pointer is returned,
3644 otherwise the pointer will be non-null.
3645
3646 If an error occurs in parsing or compilation, in most cases a
3647 valid op tree is returned anyway. The error is reflected in
3648 the parser state, normally resulting in a single exception at
3649 the top level of parsing which covers all the compilation
3650 errors that occurred. Some compilation errors, however, will
3651 throw an exception immediately.
3652
3653 OP* parse_fullexpr(U32 flags)
3654
3655 parse_fullstmt
3656 NOTE: this function is experimental and may change or be
3657 removed without notice.
3658
3659 Parse a single complete Perl statement. This may be a normal
3660 imperative statement or a declaration that has compile-time
3661 effect, and may include optional labels. It is up to the
3662 caller to ensure that the dynamic parser state ("PL_parser" et
3663 al) is correctly set to reflect the source of the code to be
3664 parsed and the lexical context for the statement.
3665
3666 The op tree representing the statement is returned. This may
3667 be a null pointer if the statement is null, for example if it
3668 was actually a subroutine definition (which has compile-time
3669 side effects). If not null, it will be the result of a
3670 "newSTATEOP" call, normally including a "nextstate" or
3671 equivalent op.
3672
3673 If an error occurs in parsing or compilation, in most cases a
3674 valid op tree (most likely null) is returned anyway. The error
3675 is reflected in the parser state, normally resulting in a
3676 single exception at the top level of parsing which covers all
3677 the compilation errors that occurred. Some compilation errors,
3678 however, will throw an exception immediately.
3679
3680 The "flags" parameter is reserved for future use, and must
3681 always be zero.
3682
3683 OP* parse_fullstmt(U32 flags)
3684
3685 parse_label
3686 NOTE: this function is experimental and may change or be
3687 removed without notice.
3688
3689 Parse a single label, possibly optional, of the type that may
3690 prefix a Perl statement. It is up to the caller to ensure that
3691 the dynamic parser state ("PL_parser" et al) is correctly set
3692 to reflect the source of the code to be parsed. If "flags" has
3693 the "PARSE_OPTIONAL" bit set, then the label is optional,
3694 otherwise it is mandatory.
3695
3696 The name of the label is returned in the form of a fresh
3697 scalar. If an optional label is absent, a null pointer is
3698 returned.
3699
3700 If an error occurs in parsing, which can only occur if the
3701 label is mandatory, a valid label is returned anyway. The
3702 error is reflected in the parser state, normally resulting in a
3703 single exception at the top level of parsing which covers all
3704 the compilation errors that occurred.
3705
3706 SV* parse_label(U32 flags)
3707
3708 parse_listexpr
3709 NOTE: this function is experimental and may change or be
3710 removed without notice.
3711
3712 Parse a Perl list expression. This may contain operators of
3713 precedence down to the comma operator. The expression must be
3714 followed (and thus terminated) either by a low-precedence logic
3715 operator such as "or" or by something that would normally
3716 terminate an expression such as semicolon. If "flags" has the
3717 "PARSE_OPTIONAL" bit set, then the expression is optional,
3718 otherwise it is mandatory. It is up to the caller to ensure
3719 that the dynamic parser state ("PL_parser" et al) is correctly
3720 set to reflect the source of the code to be parsed and the
3721 lexical context for the expression.
3722
3723 The op tree representing the expression is returned. If an
3724 optional expression is absent, a null pointer is returned,
3725 otherwise the pointer will be non-null.
3726
3727 If an error occurs in parsing or compilation, in most cases a
3728 valid op tree is returned anyway. The error is reflected in
3729 the parser state, normally resulting in a single exception at
3730 the top level of parsing which covers all the compilation
3731 errors that occurred. Some compilation errors, however, will
3732 throw an exception immediately.
3733
3734 OP* parse_listexpr(U32 flags)
3735
3736 parse_stmtseq
3737 NOTE: this function is experimental and may change or be
3738 removed without notice.
3739
3740 Parse a sequence of zero or more Perl statements. These may be
3741 normal imperative statements, including optional labels, or
3742 declarations that have compile-time effect, or any mixture
3743 thereof. The statement sequence ends when a closing brace or
3744 end-of-file is encountered in a place where a new statement
3745 could have validly started. It is up to the caller to ensure
3746 that the dynamic parser state ("PL_parser" et al) is correctly
3747 set to reflect the source of the code to be parsed and the
3748 lexical context for the statements.
3749
3750 The op tree representing the statement sequence is returned.
3751 This may be a null pointer if the statements were all null, for
3752 example if there were no statements or if there were only
3753 subroutine definitions (which have compile-time side effects).
3754 If not null, it will be a "lineseq" list, normally including
3755 "nextstate" or equivalent ops.
3756
3757 If an error occurs in parsing or compilation, in most cases a
3758 valid op tree is returned anyway. The error is reflected in
3759 the parser state, normally resulting in a single exception at
3760 the top level of parsing which covers all the compilation
3761 errors that occurred. Some compilation errors, however, will
3762 throw an exception immediately.
3763
3764 The "flags" parameter is reserved for future use, and must
3765 always be zero.
3766
3767 OP* parse_stmtseq(U32 flags)
3768
3769 parse_subsignature
3770 NOTE: this function is experimental and may change or be
3771 removed without notice.
3772
3773 Parse a subroutine signature declaration. This is the contents
3774 of the parentheses following a named or anonymous subroutine
3775 declaration when the "signatures" feature is enabled. Note that
3776 this function neither expects nor consumes the opening and
3777 closing parentheses around the signature; it is the caller's
3778 job to handle these.
3779
3780 This function must only be called during parsing of a
3781 subroutine; after "start_subparse" has been called. It might
3782 allocate lexical variables on the pad for the current
3783 subroutine.
3784
3785 The op tree to unpack the arguments from the stack at runtime
3786 is returned. This op tree should appear at the beginning of
3787 the compiled function. The caller may wish to use
3788 "op_append_list" to build their function body after it, or
3789 splice it together with the body before calling "newATTRSUB".
3790
3791 The "flags" parameter is reserved for future use, and must
3792 always be zero.
3793
3794 OP* parse_subsignature(U32 flags)
3795
3796 parse_termexpr
3797 NOTE: this function is experimental and may change or be
3798 removed without notice.
3799
3800 Parse a Perl term expression. This may contain operators of
3801 precedence down to the assignment operators. The expression
3802 must be followed (and thus terminated) either by a comma or
3803 lower-precedence operator or by something that would normally
3804 terminate an expression such as semicolon. If "flags" has the
3805 "PARSE_OPTIONAL" bit set, then the expression is optional,
3806 otherwise it is mandatory. It is up to the caller to ensure
3807 that the dynamic parser state ("PL_parser" et al) is correctly
3808 set to reflect the source of the code to be parsed and the
3809 lexical context for the expression.
3810
3811 The op tree representing the expression is returned. If an
3812 optional expression is absent, a null pointer is returned,
3813 otherwise the pointer will be non-null.
3814
3815 If an error occurs in parsing or compilation, in most cases a
3816 valid op tree is returned anyway. The error is reflected in
3817 the parser state, normally resulting in a single exception at
3818 the top level of parsing which covers all the compilation
3819 errors that occurred. Some compilation errors, however, will
3820 throw an exception immediately.
3821
3822 OP* parse_termexpr(U32 flags)
3823
3824 PL_parser
3825 Pointer to a structure encapsulating the state of the parsing
3826 operation currently in progress. The pointer can be locally
3827 changed to perform a nested parse without interfering with the
3828 state of an outer parse. Individual members of "PL_parser"
3829 have their own documentation.
3830
3831 PL_parser->bufend
3832 NOTE: this function is experimental and may change or be
3833 removed without notice.
3834
3835 Direct pointer to the end of the chunk of text currently being
3836 lexed, the end of the lexer buffer. This is equal to
3837 "SvPVX(PL_parser->linestr) + SvCUR(PL_parser->linestr)". A
3838 "NUL" character (zero octet) is always located at the end of
3839 the buffer, and does not count as part of the buffer's
3840 contents.
3841
3842 PL_parser->bufptr
3843 NOTE: this function is experimental and may change or be
3844 removed without notice.
3845
3846 Points to the current position of lexing inside the lexer
3847 buffer. Characters around this point may be freely examined,
3848 within the range delimited by "SvPVX("PL_parser->linestr")" and
3849 "PL_parser->bufend". The octets of the buffer may be intended
3850 to be interpreted as either UTF-8 or Latin-1, as indicated by
3851 "lex_bufutf8".
3852
3853 Lexing code (whether in the Perl core or not) moves this
3854 pointer past the characters that it consumes. It is also
3855 expected to perform some bookkeeping whenever a newline
3856 character is consumed. This movement can be more conveniently
3857 performed by the function "lex_read_to", which handles newlines
3858 appropriately.
3859
3860 Interpretation of the buffer's octets can be abstracted out by
3861 using the slightly higher-level functions "lex_peek_unichar"
3862 and "lex_read_unichar".
3863
3864 PL_parser->linestart
3865 NOTE: this function is experimental and may change or be
3866 removed without notice.
3867
3868 Points to the start of the current line inside the lexer
3869 buffer. This is useful for indicating at which column an error
3870 occurred, and not much else. This must be updated by any
3871 lexing code that consumes a newline; the function "lex_read_to"
3872 handles this detail.
3873
3874 PL_parser->linestr
3875 NOTE: this function is experimental and may change or be
3876 removed without notice.
3877
3878 Buffer scalar containing the chunk currently under
3879 consideration of the text currently being lexed. This is
3880 always a plain string scalar (for which "SvPOK" is true). It
3881 is not intended to be used as a scalar by normal scalar means;
3882 instead refer to the buffer directly by the pointer variables
3883 described below.
3884
3885 The lexer maintains various "char*" pointers to things in the
3886 "PL_parser->linestr" buffer. If "PL_parser->linestr" is ever
3887 reallocated, all of these pointers must be updated. Don't
3888 attempt to do this manually, but rather use "lex_grow_linestr"
3889 if you need to reallocate the buffer.
3890
3891 The content of the text chunk in the buffer is commonly exactly
3892 one complete line of input, up to and including a newline
3893 terminator, but there are situations where it is otherwise.
3894 The octets of the buffer may be intended to be interpreted as
3895 either UTF-8 or Latin-1. The function "lex_bufutf8" tells you
3896 which. Do not use the "SvUTF8" flag on this scalar, which may
3897 disagree with it.
3898
3899 For direct examination of the buffer, the variable
3900 "PL_parser->bufend" points to the end of the buffer. The
3901 current lexing position is pointed to by "PL_parser->bufptr".
3902 Direct use of these pointers is usually preferable to
3903 examination of the scalar through normal scalar means.
3904
3905 wrap_keyword_plugin
3906 NOTE: this function is experimental and may change or be
3907 removed without notice.
3908
3909 Puts a C function into the chain of keyword plugins. This is
3910 the preferred way to manipulate the "PL_keyword_plugin"
3911 variable. "new_plugin" is a pointer to the C function that is
3912 to be added to the keyword plugin chain, and "old_plugin_p"
3913 points to the storage location where a pointer to the next
3914 function in the chain will be stored. The value of
3915 "new_plugin" is written into the "PL_keyword_plugin" variable,
3916 while the value previously stored there is written to
3917 *old_plugin_p.
3918
3919 "PL_keyword_plugin" is global to an entire process, and a
3920 module wishing to hook keyword parsing may find itself invoked
3921 more than once per process, typically in different threads. To
3922 handle that situation, this function is idempotent. The
3923 location *old_plugin_p must initially (once per process)
3924 contain a null pointer. A C variable of static duration
3925 (declared at file scope, typically also marked "static" to give
3926 it internal linkage) will be implicitly initialised
3927 appropriately, if it does not have an explicit initialiser.
3928 This function will only actually modify the plugin chain if it
3929 finds *old_plugin_p to be null. This function is also thread
3930 safe on the small scale. It uses appropriate locking to avoid
3931 race conditions in accessing "PL_keyword_plugin".
3932
3933 When this function is called, the function referenced by
3934 "new_plugin" must be ready to be called, except for
3935 *old_plugin_p being unfilled. In a threading situation,
3936 "new_plugin" may be called immediately, even before this
3937 function has returned. *old_plugin_p will always be
3938 appropriately set before "new_plugin" is called. If
3939 "new_plugin" decides not to do anything special with the
3940 identifier that it is given (which is the usual case for most
3941 calls to a keyword plugin), it must chain the plugin function
3942 referenced by *old_plugin_p.
3943
3944 Taken all together, XS code to install a keyword plugin should
3945 typically look something like this:
3946
3947 static Perl_keyword_plugin_t next_keyword_plugin;
3948 static OP *my_keyword_plugin(pTHX_
3949 char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
3950 {
3951 if (memEQs(keyword_ptr, keyword_len,
3952 "my_new_keyword")) {
3953 ...
3954 } else {
3955 return next_keyword_plugin(aTHX_
3956 keyword_ptr, keyword_len, op_ptr);
3957 }
3958 }
3959 BOOT:
3960 wrap_keyword_plugin(my_keyword_plugin,
3961 &next_keyword_plugin);
3962
3963 Direct access to "PL_keyword_plugin" should be avoided.
3964
3965 void wrap_keyword_plugin(
3966 Perl_keyword_plugin_t new_plugin,
3967 Perl_keyword_plugin_t *old_plugin_p
3968 )
3969
3971 DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3972 This macro should be used as a statement. It declares a
3973 private variable (whose name begins with an underscore) that is
3974 needed by the other macros in this section. Failing to include
3975 this correctly should lead to a syntax error. For
3976 compatibility with C89 C compilers it should be placed in a
3977 block before any executable statements.
3978
3979 void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
3980
3981 IN_LOCALE
3982 Evaluates to TRUE if the plain locale pragma without a
3983 parameter ("use locale") is in effect.
3984
3985 bool IN_LOCALE
3986
3987 IN_LOCALE_COMPILETIME
3988 Evaluates to TRUE if, when compiling a perl program (including
3989 an "eval") if the plain locale pragma without a parameter
3990 ("use locale") is in effect.
3991
3992 bool IN_LOCALE_COMPILETIME
3993
3994 IN_LOCALE_RUNTIME
3995 Evaluates to TRUE if, when executing a perl program (including
3996 an "eval") if the plain locale pragma without a parameter
3997 ("use locale") is in effect.
3998
3999 bool IN_LOCALE_RUNTIME
4000
4001 Perl_langinfo
4002 This is an (almost) drop-in replacement for the system
4003 nl_langinfo(3), taking the same "item" parameter values, and
4004 returning the same information. But it is more thread-safe
4005 than regular "nl_langinfo()", and hides the quirks of Perl's
4006 locale handling from your code, and can be used on systems that
4007 lack a native "nl_langinfo".
4008
4009 Expanding on these:
4010
4011 · The reason it isn't quite a drop-in replacement is actually
4012 an advantage. The only difference is that it returns
4013 "const char *", whereas plain "nl_langinfo()" returns
4014 "char *", but you are (only by documentation) forbidden to
4015 write into the buffer. By declaring this "const", the
4016 compiler enforces this restriction, so if it is violated,
4017 you know at compilation time, rather than getting segfaults
4018 at runtime.
4019
4020 · It delivers the correct results for the "RADIXCHAR" and
4021 "THOUSEP" items, without you having to write extra code.
4022 The reason for the extra code would be because these are
4023 from the "LC_NUMERIC" locale category, which is normally
4024 kept set by Perl so that the radix is a dot, and the
4025 separator is the empty string, no matter what the
4026 underlying locale is supposed to be, and so to get the
4027 expected results, you have to temporarily toggle into the
4028 underlying locale, and later toggle back. (You could use
4029 plain "nl_langinfo" and
4030 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" for this but then
4031 you wouldn't get the other advantages of "Perl_langinfo()";
4032 not keeping "LC_NUMERIC" in the C (or equivalent) locale
4033 would break a lot of CPAN, which is expecting the radix
4034 (decimal point) character to be a dot.)
4035
4036 · The system function it replaces can have its static return
4037 buffer trashed, not only by a subesequent call to that
4038 function, but by a "freelocale", "setlocale", or other
4039 locale change. The returned buffer of this function is not
4040 changed until the next call to it, so the buffer is never
4041 in a trashed state.
4042
4043 · Its return buffer is per-thread, so it also is never
4044 overwritten by a call to this function from another thread;
4045 unlike the function it replaces.
4046
4047 · But most importantly, it works on systems that don't have
4048 "nl_langinfo", such as Windows, hence makes your code more
4049 portable. Of the fifty-some possible items specified by
4050 the POSIX 2008 standard,
4051 <http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
4052 only one is completely unimplemented, though on non-Windows
4053 platforms, another significant one is also not
4054 implemented). It uses various techniques to recover the
4055 other items, including calling localeconv(3), and
4056 strftime(3), both of which are specified in C89, so should
4057 be always be available. Later "strftime()" versions have
4058 additional capabilities; "" is returned for those not
4059 available on your system.
4060
4061 It is important to note that when called with an item that
4062 is recovered by using "localeconv", the buffer from any
4063 previous explicit call to "localeconv" will be overwritten.
4064 This means you must save that buffer's contents if you need
4065 to access them after a call to this function. (But note
4066 that you might not want to be using "localeconv()" directly
4067 anyway, because of issues like the ones listed in the
4068 second item of this list (above) for "RADIXCHAR" and
4069 "THOUSEP". You can use the methods given in perlcall to
4070 call "localeconv" in POSIX and avoid all the issues, but
4071 then you have a hash to unpack).
4072
4073 The details for those items which may deviate from what
4074 this emulation returns and what a native "nl_langinfo()"
4075 would return are specified in I18N::Langinfo.
4076
4077 When using "Perl_langinfo" on systems that don't have a native
4078 "nl_langinfo()", you must
4079
4080 #include "perl_langinfo.h"
4081
4082 before the "perl.h" "#include". You can replace your
4083 "langinfo.h" "#include" with this one. (Doing it this way
4084 keeps out the symbols that plain "langinfo.h" would try to
4085 import into the namespace for code that doesn't need it.)
4086
4087 The original impetus for "Perl_langinfo()" was so that code
4088 that needs to find out the current currency symbol, floating
4089 point radix character, or digit grouping separator can use, on
4090 all systems, the simpler and more thread-friendly "nl_langinfo"
4091 API instead of localeconv(3) which is a pain to make thread-
4092 friendly. For other fields returned by "localeconv", it is
4093 better to use the methods given in perlcall to call
4094 "POSIX::localeconv()", which is thread-friendly.
4095
4096 const char* Perl_langinfo(const nl_item item)
4097
4098 Perl_setlocale
4099 This is an (almost) drop-in replacement for the system
4100 setlocale(3), taking the same parameters, and returning the
4101 same information, except that it returns the correct underlying
4102 "LC_NUMERIC" locale. Regular "setlocale" will instead return
4103 "C" if the underlying locale has a non-dot decimal point
4104 character, or a non-empty thousands separator for displaying
4105 floating point numbers. This is because perl keeps that locale
4106 category such that it has a dot and empty separator, changing
4107 the locale briefly during the operations where the underlying
4108 one is required. "Perl_setlocale" knows about this, and
4109 compensates; regular "setlocale" doesn't.
4110
4111 Another reason it isn't completely a drop-in replacement is
4112 that it is declared to return "const char *", whereas the
4113 system setlocale omits the "const" (presumably because its API
4114 was specified long ago, and can't be updated; it is illegal to
4115 change the information "setlocale" returns; doing so leads to
4116 segfaults.)
4117
4118 Finally, "Perl_setlocale" works under all circumstances,
4119 whereas plain "setlocale" can be completely ineffective on some
4120 platforms under some configurations.
4121
4122 "Perl_setlocale" should not be used to change the locale except
4123 on systems where the predefined variable "${^SAFE_LOCALES}" is
4124 1. On some such systems, the system "setlocale()" is
4125 ineffective, returning the wrong information, and failing to
4126 actually change the locale. "Perl_setlocale", however works
4127 properly in all circumstances.
4128
4129 The return points to a per-thread static buffer, which is
4130 overwritten the next time "Perl_setlocale" is called from the
4131 same thread.
4132
4133 const char* Perl_setlocale(const int category,
4134 const char* locale)
4135
4136 RESTORE_LC_NUMERIC
4137 This is used in conjunction with one of the macros
4138 "STORE_LC_NUMERIC_SET_TO_NEEDED" and
4139 "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
4140 "LC_NUMERIC" state.
4141
4142 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4143 been made to declare at compile time a private variable used by
4144 this macro and the two "STORE" ones. This macro should be
4145 called as a single statement, not an expression, but with an
4146 empty argument list, like this:
4147
4148 {
4149 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4150 ...
4151 RESTORE_LC_NUMERIC();
4152 ...
4153 }
4154
4155 void RESTORE_LC_NUMERIC()
4156
4157 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING
4158 This is used by XS code that is "LC_NUMERIC" locale-aware to
4159 force the locale for category "LC_NUMERIC" to be what perl
4160 thinks is the current underlying locale. (The perl interpreter
4161 could be wrong about what the underlying locale actually is if
4162 some C or XS code has called the C library function
4163 setlocale(3) behind its back; calling "sync_locale" before
4164 calling this macro will update perl's records.)
4165
4166 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4167 been made to declare at compile time a private variable used by
4168 this macro. This macro should be called as a single statement,
4169 not an expression, but with an empty argument list, like this:
4170
4171 {
4172 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4173 ...
4174 STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
4175 ...
4176 RESTORE_LC_NUMERIC();
4177 ...
4178 }
4179
4180 The private variable is used to save the current locale state,
4181 so that the requisite matching call to "RESTORE_LC_NUMERIC" can
4182 restore it.
4183
4184 On threaded perls not operating with thread-safe functionality,
4185 this macro uses a mutex to force a critical section. Therefore
4186 the matching RESTORE should be close by, and guaranteed to be
4187 called.
4188
4189 void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
4190
4191 STORE_LC_NUMERIC_SET_TO_NEEDED
4192 This is used to help wrap XS or C code that is "LC_NUMERIC"
4193 locale-aware. This locale category is generally kept set to a
4194 locale where the decimal radix character is a dot, and the
4195 separator between groups of digits is empty. This is because
4196 most XS code that reads floating point numbers is expecting
4197 them to have this syntax.
4198
4199 This macro makes sure the current "LC_NUMERIC" state is set
4200 properly, to be aware of locale if the call to the XS or C code
4201 from the Perl program is from within the scope of a
4202 "use locale"; or to ignore locale if the call is instead from
4203 outside such scope.
4204
4205 This macro is the start of wrapping the C or XS code; the wrap
4206 ending is done by calling the "RESTORE_LC_NUMERIC" macro after
4207 the operation. Otherwise the state can be changed that will
4208 adversely affect other XS code.
4209
4210 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have
4211 been made to declare at compile time a private variable used by
4212 this macro. This macro should be called as a single statement,
4213 not an expression, but with an empty argument list, like this:
4214
4215 {
4216 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4217 ...
4218 STORE_LC_NUMERIC_SET_TO_NEEDED();
4219 ...
4220 RESTORE_LC_NUMERIC();
4221 ...
4222 }
4223
4224 On threaded perls not operating with thread-safe functionality,
4225 this macro uses a mutex to force a critical section. Therefore
4226 the matching RESTORE should be close by, and guaranteed to be
4227 called; see "WITH_LC_NUMERIC_SET_TO_NEEDED" for a more
4228 contained way to ensure that.
4229
4230 void STORE_LC_NUMERIC_SET_TO_NEEDED()
4231
4232 STORE_LC_NUMERIC_SET_TO_NEEDED_IN
4233 Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
4234 provided as the precalculated value of "IN_LC(LC_NUMERIC)". It
4235 is the caller's responsibility to ensure that the status of
4236 "PL_compiling" and "PL_hints" cannot have changed since the
4237 precalculation.
4238
4239 void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(
4240 bool in_lc_numeric
4241 )
4242
4243 switch_to_global_locale
4244 On systems without locale support, or on typical single-
4245 threaded builds, or on platforms that do not support per-thread
4246 locale operations, this function does nothing. On such systems
4247 that do have locale support, only a locale global to the whole
4248 program is available.
4249
4250 On multi-threaded builds on systems that do have per-thread
4251 locale operations, this function converts the thread it is
4252 running in to use the global locale. This is for code that has
4253 not yet or cannot be updated to handle multi-threaded locale
4254 operation. As long as only a single thread is so-converted,
4255 everything works fine, as all the other threads continue to
4256 ignore the global one, so only this thread looks at it.
4257
4258 However, on Windows systems this isn't quite true prior to
4259 Visual Studio 15, at which point Microsoft fixed a bug. A race
4260 can occur if you use the following operations on earlier
4261 Windows platforms:
4262
4263 POSIX::localeconv
4264 I18N::Langinfo, items "CRNCYSTR" and "THOUSEP"
4265 "Perl_langinfo" in perlapi, items "CRNCYSTR" and "THOUSEP"
4266
4267 The first item is not fixable (except by upgrading to a later
4268 Visual Studio release), but it would be possible to work around
4269 the latter two items by using the Windows API functions
4270 "GetNumberFormat" and "GetCurrencyFormat"; patches welcome.
4271
4272 Without this function call, threads that use the setlocale(3)
4273 system function will not work properly, as all the locale-
4274 sensitive functions will look at the per-thread locale, and
4275 "setlocale" will have no effect on this thread.
4276
4277 Perl code should convert to either call "Perl_setlocale" (which
4278 is a drop-in for the system "setlocale") or use the methods
4279 given in perlcall to call "POSIX::setlocale". Either one will
4280 transparently properly handle all cases of single- vs multi-
4281 thread, POSIX 2008-supported or not.
4282
4283 Non-Perl libraries, such as "gtk", that call the system
4284 "setlocale" can continue to work if this function is called
4285 before transferring control to the library.
4286
4287 Upon return from the code that needs to use the global locale,
4288 "sync_locale()" should be called to restore the safe multi-
4289 thread operation.
4290
4291 void switch_to_global_locale()
4292
4293 sync_locale
4294 "Perl_setlocale" can be used at any time to query or change the
4295 locale (though changing the locale is antisocial and dangerous
4296 on multi-threaded systems that don't have multi-thread safe
4297 locale operations. (See "Multi-threaded operation" in
4298 perllocale). Using the system setlocale(3) should be avoided.
4299 Nevertheless, certain non-Perl libraries called from XS, such
4300 as "Gtk" do so, and this can't be changed. When the locale is
4301 changed by XS code that didn't use "Perl_setlocale", Perl needs
4302 to be told that the locale has changed. Use this function to
4303 do so, before returning to Perl.
4304
4305 The return value is a boolean: TRUE if the global locale at the
4306 time of call was in effect; and FALSE if a per-thread locale
4307 was in effect. This can be used by the caller that needs to
4308 restore things as-they-were to decide whether or not to call
4309 "Perl_switch_to_global_locale".
4310
4311 bool sync_locale()
4312
4313 WITH_LC_NUMERIC_SET_TO_NEEDED
4314 This macro invokes the supplied statement or block within the
4315 context of a "STORE_LC_NUMERIC_SET_TO_NEEDED" ..
4316 "RESTORE_LC_NUMERIC" pair if required, so eg:
4317
4318 WITH_LC_NUMERIC_SET_TO_NEEDED(
4319 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
4320 );
4321
4322 is equivalent to:
4323
4324 {
4325 #ifdef USE_LOCALE_NUMERIC
4326 DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
4327 STORE_LC_NUMERIC_SET_TO_NEEDED();
4328 #endif
4329 SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
4330 #ifdef USE_LOCALE_NUMERIC
4331 RESTORE_LC_NUMERIC();
4332 #endif
4333 }
4334
4335 void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
4336
4337 WITH_LC_NUMERIC_SET_TO_NEEDED_IN
4338 Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric
4339 provided as the precalculated value of "IN_LC(LC_NUMERIC)". It
4340 is the caller's responsibility to ensure that the status of
4341 "PL_compiling" and "PL_hints" cannot have changed since the
4342 precalculation.
4343
4344 void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(
4345 bool in_lc_numeric, block
4346 )
4347
4349 mg_clear
4350 Clear something magical that the SV represents. See
4351 "sv_magic".
4352
4353 int mg_clear(SV* sv)
4354
4355 mg_copy Copies the magic from one SV to another. See "sv_magic".
4356
4357 int mg_copy(SV *sv, SV *nsv, const char *key,
4358 I32 klen)
4359
4360 mg_find Finds the magic pointer for "type" matching the SV. See
4361 "sv_magic".
4362
4363 MAGIC* mg_find(const SV* sv, int type)
4364
4365 mg_findext
4366 Finds the magic pointer of "type" with the given "vtbl" for the
4367 "SV". See "sv_magicext".
4368
4369 MAGIC* mg_findext(const SV* sv, int type,
4370 const MGVTBL *vtbl)
4371
4372 mg_free Free any magic storage used by the SV. See "sv_magic".
4373
4374 int mg_free(SV* sv)
4375
4376 mg_freeext
4377 Remove any magic of type "how" using virtual table "vtbl" from
4378 the SV "sv". See "sv_magic".
4379
4380 "mg_freeext(sv, how, NULL)" is equivalent to "mg_free_type(sv,
4381 how)".
4382
4383 void mg_freeext(SV* sv, int how, const MGVTBL *vtbl)
4384
4385 mg_free_type
4386 Remove any magic of type "how" from the SV "sv". See
4387 "sv_magic".
4388
4389 void mg_free_type(SV* sv, int how)
4390
4391 mg_get Do magic before a value is retrieved from the SV. The type of
4392 SV must be >= "SVt_PVMG". See "sv_magic".
4393
4394 int mg_get(SV* sv)
4395
4396 mg_length
4397 DEPRECATED! It is planned to remove this function from a
4398 future release of Perl. Do not use it for new code; remove it
4399 from existing code.
4400
4401 Reports on the SV's length in bytes, calling length magic if
4402 available, but does not set the UTF8 flag on "sv". It will
4403 fall back to 'get' magic if there is no 'length' magic, but
4404 with no indication as to whether it called 'get' magic. It
4405 assumes "sv" is a "PVMG" or higher. Use "sv_len()" instead.
4406
4407 U32 mg_length(SV* sv)
4408
4409 mg_magical
4410 Turns on the magical status of an SV. See "sv_magic".
4411
4412 void mg_magical(SV* sv)
4413
4414 mg_set Do magic after a value is assigned to the SV. See "sv_magic".
4415
4416 int mg_set(SV* sv)
4417
4418 SvGETMAGIC
4419 Invokes "mg_get" on an SV if it has 'get' magic. For example,
4420 this will call "FETCH" on a tied variable. This macro
4421 evaluates its argument more than once.
4422
4423 void SvGETMAGIC(SV* sv)
4424
4425 SvLOCK Arranges for a mutual exclusion lock to be obtained on "sv" if
4426 a suitable module has been loaded.
4427
4428 void SvLOCK(SV* sv)
4429
4430 SvSETMAGIC
4431 Invokes "mg_set" on an SV if it has 'set' magic. This is
4432 necessary after modifying a scalar, in case it is a magical
4433 variable like $| or a tied variable (it calls "STORE"). This
4434 macro evaluates its argument more than once.
4435
4436 void SvSETMAGIC(SV* sv)
4437
4438 SvSetMagicSV
4439 Like "SvSetSV", but does any set magic required afterwards.
4440
4441 void SvSetMagicSV(SV* dsv, SV* ssv)
4442
4443 SvSetMagicSV_nosteal
4444 Like "SvSetSV_nosteal", but does any set magic required
4445 afterwards.
4446
4447 void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
4448
4449 SvSetSV Calls "sv_setsv" if "dsv" is not the same as "ssv". May
4450 evaluate arguments more than once. Does not handle 'set' magic
4451 on the destination SV.
4452
4453 void SvSetSV(SV* dsv, SV* ssv)
4454
4455 SvSetSV_nosteal
4456 Calls a non-destructive version of "sv_setsv" if "dsv" is not
4457 the same as "ssv". May evaluate arguments more than once.
4458
4459 void SvSetSV_nosteal(SV* dsv, SV* ssv)
4460
4461 SvSHARE Arranges for "sv" to be shared between threads if a suitable
4462 module has been loaded.
4463
4464 void SvSHARE(SV* sv)
4465
4466 sv_string_from_errnum
4467 Generates the message string describing an OS error and returns
4468 it as an SV. "errnum" must be a value that "errno" could take,
4469 identifying the type of error.
4470
4471 If "tgtsv" is non-null then the string will be written into
4472 that SV (overwriting existing content) and it will be returned.
4473 If "tgtsv" is a null pointer then the string will be written
4474 into a new mortal SV which will be returned.
4475
4476 The message will be taken from whatever locale would be used by
4477 $!, and will be encoded in the SV in whatever manner would be
4478 used by $!. The details of this process are subject to future
4479 change. Currently, the message is taken from the C locale by
4480 default (usually producing an English message), and from the
4481 currently selected locale when in the scope of the "use locale"
4482 pragma. A heuristic attempt is made to decode the message from
4483 the locale's character encoding, but it will only be decoded as
4484 either UTF-8 or ISO-8859-1. It is always correctly decoded in
4485 a UTF-8 locale, usually in an ISO-8859-1 locale, and never in
4486 any other locale.
4487
4488 The SV is always returned containing an actual string, and with
4489 no other OK bits set. Unlike $!, a message is even yielded for
4490 "errnum" zero (meaning success), and if no useful message is
4491 available then a useless string (currently empty) is returned.
4492
4493 SV* sv_string_from_errnum(int errnum, SV* tgtsv)
4494
4495 SvUNLOCK
4496 Releases a mutual exclusion lock on "sv" if a suitable module
4497 has been loaded.
4498
4499 void SvUNLOCK(SV* sv)
4500
4502 Copy The XSUB-writer's interface to the C "memcpy" function. The
4503 "src" is the source, "dest" is the destination, "nitems" is the
4504 number of items, and "type" is the type. May fail on
4505 overlapping copies. See also "Move".
4506
4507 void Copy(void* src, void* dest, int nitems, type)
4508
4509 CopyD Like "Copy" but returns "dest". Useful for encouraging
4510 compilers to tail-call optimise.
4511
4512 void * CopyD(void* src, void* dest, int nitems, type)
4513
4514 Move The XSUB-writer's interface to the C "memmove" function. The
4515 "src" is the source, "dest" is the destination, "nitems" is the
4516 number of items, and "type" is the type. Can do overlapping
4517 moves. See also "Copy".
4518
4519 void Move(void* src, void* dest, int nitems, type)
4520
4521 MoveD Like "Move" but returns "dest". Useful for encouraging
4522 compilers to tail-call optimise.
4523
4524 void * MoveD(void* src, void* dest, int nitems, type)
4525
4526 Newx The XSUB-writer's interface to the C "malloc" function.
4527
4528 Memory obtained by this should ONLY be freed with "Safefree".
4529
4530 In 5.9.3, Newx() and friends replace the older New() API, and
4531 drops the first parameter, x, a debug aid which allowed callers
4532 to identify themselves. This aid has been superseded by a new
4533 build option, PERL_MEM_LOG (see "PERL_MEM_LOG" in
4534 perlhacktips). The older API is still there for use in XS
4535 modules supporting older perls.
4536
4537 void Newx(void* ptr, int nitems, type)
4538
4539 Newxc The XSUB-writer's interface to the C "malloc" function, with
4540 cast. See also "Newx".
4541
4542 Memory obtained by this should ONLY be freed with "Safefree".
4543
4544 void Newxc(void* ptr, int nitems, type, cast)
4545
4546 Newxz The XSUB-writer's interface to the C "malloc" function. The
4547 allocated memory is zeroed with "memzero". See also "Newx".
4548
4549 Memory obtained by this should ONLY be freed with "Safefree".
4550
4551 void Newxz(void* ptr, int nitems, type)
4552
4553 Poison PoisonWith(0xEF) for catching access to freed memory.
4554
4555 void Poison(void* dest, int nitems, type)
4556
4557 PoisonFree
4558 PoisonWith(0xEF) for catching access to freed memory.
4559
4560 void PoisonFree(void* dest, int nitems, type)
4561
4562 PoisonNew
4563 PoisonWith(0xAB) for catching access to allocated but
4564 uninitialized memory.
4565
4566 void PoisonNew(void* dest, int nitems, type)
4567
4568 PoisonWith
4569 Fill up memory with a byte pattern (a byte repeated over and
4570 over again) that hopefully catches attempts to access
4571 uninitialized memory.
4572
4573 void PoisonWith(void* dest, int nitems, type,
4574 U8 byte)
4575
4576 Renew The XSUB-writer's interface to the C "realloc" function.
4577
4578 Memory obtained by this should ONLY be freed with "Safefree".
4579
4580 void Renew(void* ptr, int nitems, type)
4581
4582 Renewc The XSUB-writer's interface to the C "realloc" function, with
4583 cast.
4584
4585 Memory obtained by this should ONLY be freed with "Safefree".
4586
4587 void Renewc(void* ptr, int nitems, type, cast)
4588
4589 Safefree
4590 The XSUB-writer's interface to the C "free" function.
4591
4592 This should ONLY be used on memory obtained using "Newx" and
4593 friends.
4594
4595 void Safefree(void* ptr)
4596
4597 savepv Perl's version of "strdup()". Returns a pointer to a newly
4598 allocated string which is a duplicate of "pv". The size of the
4599 string is determined by "strlen()", which means it may not
4600 contain embedded "NUL" characters and must have a trailing
4601 "NUL". To prevent memory leaks, the memory allocated for the
4602 new string needs to be freed when no longer needed. This can
4603 be done with the ""Safefree"" function, or "SAVEFREEPV".
4604
4605 On some platforms, Windows for example, all allocated memory
4606 owned by a thread is deallocated when that thread ends. So if
4607 you need that not to happen, you need to use the shared memory
4608 functions, such as "savesharedpv".
4609
4610 char* savepv(const char* pv)
4611
4612 savepvn Perl's version of what "strndup()" would be if it existed.
4613 Returns a pointer to a newly allocated string which is a
4614 duplicate of the first "len" bytes from "pv", plus a trailing
4615 "NUL" byte. The memory allocated for the new string can be
4616 freed with the "Safefree()" function.
4617
4618 On some platforms, Windows for example, all allocated memory
4619 owned by a thread is deallocated when that thread ends. So if
4620 you need that not to happen, you need to use the shared memory
4621 functions, such as "savesharedpvn".
4622
4623 char* savepvn(const char* pv, Size_t len)
4624
4625 savepvs Like "savepvn", but takes a literal string instead of a
4626 string/length pair.
4627
4628 char* savepvs("literal string")
4629
4630 savesharedpv
4631 A version of "savepv()" which allocates the duplicate string in
4632 memory which is shared between threads.
4633
4634 char* savesharedpv(const char* pv)
4635
4636 savesharedpvn
4637 A version of "savepvn()" which allocates the duplicate string
4638 in memory which is shared between threads. (With the specific
4639 difference that a "NULL" pointer is not acceptable)
4640
4641 char* savesharedpvn(const char *const pv,
4642 const STRLEN len)
4643
4644 savesharedpvs
4645 A version of "savepvs()" which allocates the duplicate string
4646 in memory which is shared between threads.
4647
4648 char* savesharedpvs("literal string")
4649
4650 savesharedsvpv
4651 A version of "savesharedpv()" which allocates the duplicate
4652 string in memory which is shared between threads.
4653
4654 char* savesharedsvpv(SV *sv)
4655
4656 savesvpv
4657 A version of "savepv()"/"savepvn()" which gets the string to
4658 duplicate from the passed in SV using "SvPV()"
4659
4660 On some platforms, Windows for example, all allocated memory
4661 owned by a thread is deallocated when that thread ends. So if
4662 you need that not to happen, you need to use the shared memory
4663 functions, such as "savesharedsvpv".
4664
4665 char* savesvpv(SV* sv)
4666
4667 StructCopy
4668 This is an architecture-independent macro to copy one structure
4669 to another.
4670
4671 void StructCopy(type *src, type *dest, type)
4672
4673 Zero The XSUB-writer's interface to the C "memzero" function. The
4674 "dest" is the destination, "nitems" is the number of items, and
4675 "type" is the type.
4676
4677 void Zero(void* dest, int nitems, type)
4678
4679 ZeroD Like "Zero" but returns dest. Useful for encouraging compilers
4680 to tail-call optimise.
4681
4682 void * ZeroD(void* dest, int nitems, type)
4683
4685 dump_c_backtrace
4686 Dumps the C backtrace to the given "fp".
4687
4688 Returns true if a backtrace could be retrieved, false if not.
4689
4690 bool dump_c_backtrace(PerlIO* fp, int max_depth,
4691 int skip)
4692
4693 fbm_compile
4694 Analyzes the string in order to make fast searches on it using
4695 "fbm_instr()" -- the Boyer-Moore algorithm.
4696
4697 void fbm_compile(SV* sv, U32 flags)
4698
4699 fbm_instr
4700 Returns the location of the SV in the string delimited by "big"
4701 and "bigend" ("bigend") is the char following the last char).
4702 It returns "NULL" if the string can't be found. The "sv" does
4703 not have to be "fbm_compiled", but the search will not be as
4704 fast then.
4705
4706 char* fbm_instr(unsigned char* big,
4707 unsigned char* bigend, SV* littlestr,
4708 U32 flags)
4709
4710 foldEQ Returns true if the leading "len" bytes of the strings "s1" and
4711 "s2" are the same case-insensitively; false otherwise.
4712 Uppercase and lowercase ASCII range bytes match themselves and
4713 their opposite case counterparts. Non-cased and non-ASCII
4714 range bytes match only themselves.
4715
4716 I32 foldEQ(const char* a, const char* b, I32 len)
4717
4718 foldEQ_locale
4719 Returns true if the leading "len" bytes of the strings "s1" and
4720 "s2" are the same case-insensitively in the current locale;
4721 false otherwise.
4722
4723 I32 foldEQ_locale(const char* a, const char* b,
4724 I32 len)
4725
4726 form Takes a sprintf-style format pattern and conventional (non-SV)
4727 arguments and returns the formatted string.
4728
4729 (char *) Perl_form(pTHX_ const char* pat, ...)
4730
4731 can be used any place a string (char *) is required:
4732
4733 char * s = Perl_form("%d.%d",major,minor);
4734
4735 Uses a single private buffer so if you want to format several
4736 strings you must explicitly copy the earlier strings away (and
4737 free the copies when you are done).
4738
4739 char* form(const char* pat, ...)
4740
4741 getcwd_sv
4742 Fill "sv" with current working directory
4743
4744 int getcwd_sv(SV* sv)
4745
4746 get_c_backtrace_dump
4747 Returns a SV containing a dump of "depth" frames of the call
4748 stack, skipping the "skip" innermost ones. "depth" of 20 is
4749 usually enough.
4750
4751 The appended output looks like:
4752
4753 ... 1 10e004812:0082 Perl_croak util.c:1716
4754 /usr/bin/perl 2 10df8d6d2:1d72 perl_parse perl.c:3975
4755 /usr/bin/perl ...
4756
4757 The fields are tab-separated. The first column is the depth
4758 (zero being the innermost non-skipped frame). In the
4759 hex:offset, the hex is where the program counter was in
4760 "S_parse_body", and the :offset (might be missing) tells how
4761 much inside the "S_parse_body" the program counter was.
4762
4763 The "util.c:1716" is the source code file and line number.
4764
4765 The /usr/bin/perl is obvious (hopefully).
4766
4767 Unknowns are "-". Unknowns can happen unfortunately quite
4768 easily: if the platform doesn't support retrieving the
4769 information; if the binary is missing the debug information; if
4770 the optimizer has transformed the code by for example inlining.
4771
4772 SV* get_c_backtrace_dump(int max_depth, int skip)
4773
4774 ibcmp This is a synonym for "(! foldEQ())"
4775
4776 I32 ibcmp(const char* a, const char* b, I32 len)
4777
4778 ibcmp_locale
4779 This is a synonym for "(! foldEQ_locale())"
4780
4781 I32 ibcmp_locale(const char* a, const char* b,
4782 I32 len)
4783
4784 instr Same as strstr(3), which finds and returns a pointer to the
4785 first occurrence of the NUL-terminated substring "little" in
4786 the NUL-terminated string "big", returning NULL if not found.
4787 The terminating NUL bytes are not compared.
4788
4789 char* instr(const char* big, const char* little)
4790
4791 IS_SAFE_SYSCALL
4792 Same as "is_safe_syscall".
4793
4794 bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
4795 NN const char *what,
4796 NN const char *op_name)
4797
4798 is_safe_syscall
4799 Test that the given "pv" (with length "len") doesn't contain
4800 any internal "NUL" characters. If it does, set "errno" to
4801 "ENOENT", optionally warn using the "syscalls" category, and
4802 return FALSE.
4803
4804 Return TRUE if the name is safe.
4805
4806 "what" and "op_name" are used in any warning.
4807
4808 Used by the "IS_SAFE_SYSCALL()" macro.
4809
4810 bool is_safe_syscall(const char *pv, STRLEN len,
4811 const char *what,
4812 const char *op_name)
4813
4814 LIKELY Returns the input unchanged, but at the same time it gives a
4815 branch prediction hint to the compiler that this condition is
4816 likely to be true.
4817
4818 memCHRs Returns the position of the first occurence of the byte "c" in
4819 the literal string "list", or NULL if "c" doesn't appear in
4820 "list". All bytes are treated as unsigned char. Thus this
4821 macro can be used to determine if "c" is in a set of particular
4822 characters. Unlike strchr(3), it works even if "c" is "NUL"
4823 (and the set doesn't include "NUL").
4824
4825 bool memCHRs("list", char c)
4826
4827 memEQ Test two buffers (which may contain embedded "NUL" characters,
4828 to see if they are equal. The "len" parameter indicates the
4829 number of bytes to compare. Returns zero if equal, or non-zero
4830 if non-equal.
4831
4832 bool memEQ(char* s1, char* s2, STRLEN len)
4833
4834 memEQs Like "memEQ", but the second string is a literal enclosed in
4835 double quotes, "l1" gives the number of bytes in "s1". Returns
4836 zero if equal, or non-zero if non-equal.
4837
4838 bool memEQs(char* s1, STRLEN l1, "s2")
4839
4840 memNE Test two buffers (which may contain embedded "NUL" characters,
4841 to see if they are not equal. The "len" parameter indicates
4842 the number of bytes to compare. Returns zero if non-equal, or
4843 non-zero if equal.
4844
4845 bool memNE(char* s1, char* s2, STRLEN len)
4846
4847 memNEs Like "memNE", but the second string is a literal enclosed in
4848 double quotes, "l1" gives the number of bytes in "s1". Returns
4849 zero if non-equal, or zero if non-equal.
4850
4851 bool memNEs(char* s1, STRLEN l1, "s2")
4852
4853 mess Take a sprintf-style format pattern and argument list. These
4854 are used to generate a string message. If the message does not
4855 end with a newline, then it will be extended with some
4856 indication of the current location in the code, as described
4857 for "mess_sv".
4858
4859 Normally, the resulting message is returned in a new mortal SV.
4860 During global destruction a single SV may be shared between
4861 uses of this function.
4862
4863 SV* mess(const char* pat, ...)
4864
4865 mess_sv Expands a message, intended for the user, to include an
4866 indication of the current location in the code, if the message
4867 does not already appear to be complete.
4868
4869 "basemsg" is the initial message or object. If it is a
4870 reference, it will be used as-is and will be the result of this
4871 function. Otherwise it is used as a string, and if it already
4872 ends with a newline, it is taken to be complete, and the result
4873 of this function will be the same string. If the message does
4874 not end with a newline, then a segment such as "at foo.pl line
4875 37" will be appended, and possibly other clauses indicating the
4876 current state of execution. The resulting message will end
4877 with a dot and a newline.
4878
4879 Normally, the resulting message is returned in a new mortal SV.
4880 During global destruction a single SV may be shared between
4881 uses of this function. If "consume" is true, then the function
4882 is permitted (but not required) to modify and return "basemsg"
4883 instead of allocating a new SV.
4884
4885 SV* mess_sv(SV* basemsg, bool consume)
4886
4887 my_snprintf
4888 The C library "snprintf" functionality, if available and
4889 standards-compliant (uses "vsnprintf", actually). However, if
4890 the "vsnprintf" is not available, will unfortunately use the
4891 unsafe "vsprintf" which can overrun the buffer (there is an
4892 overrun check, but that may be too late). Consider using
4893 "sv_vcatpvf" instead, or getting "vsnprintf".
4894
4895 int my_snprintf(char *buffer, const Size_t len,
4896 const char *format, ...)
4897
4898 my_sprintf
4899 DEPRECATED! It is planned to remove this function from a
4900 future release of Perl. Do not use it for new code; remove it
4901 from existing code.
4902
4903 Do NOT use this due to the possibility of overflowing "buffer".
4904 Instead use my_snprintf()
4905
4906 int my_sprintf(NN char *buffer, NN const char *pat,
4907 ...)
4908
4909 my_strlcat
4910 The C library "strlcat" if available, or a Perl implementation
4911 of it. This operates on C "NUL"-terminated strings.
4912
4913 "my_strlcat()" appends string "src" to the end of "dst". It
4914 will append at most "size - strlen(dst) - 1" characters. It
4915 will then "NUL"-terminate, unless "size" is 0 or the original
4916 "dst" string was longer than "size" (in practice this should
4917 not happen as it means that either "size" is incorrect or that
4918 "dst" is not a proper "NUL"-terminated string).
4919
4920 Note that "size" is the full size of the destination buffer and
4921 the result is guaranteed to be "NUL"-terminated if there is
4922 room. Note that room for the "NUL" should be included in
4923 "size".
4924
4925 The return value is the total length that "dst" would have if
4926 "size" is sufficiently large. Thus it is the initial length of
4927 "dst" plus the length of "src". If "size" is smaller than the
4928 return, the excess was not appended.
4929
4930 Size_t my_strlcat(char *dst, const char *src,
4931 Size_t size)
4932
4933 my_strlcpy
4934 The C library "strlcpy" if available, or a Perl implementation
4935 of it. This operates on C "NUL"-terminated strings.
4936
4937 "my_strlcpy()" copies up to "size - 1" characters from the
4938 string "src" to "dst", "NUL"-terminating the result if "size"
4939 is not 0.
4940
4941 The return value is the total length "src" would be if the copy
4942 completely succeeded. If it is larger than "size", the excess
4943 was not copied.
4944
4945 Size_t my_strlcpy(char *dst, const char *src,
4946 Size_t size)
4947
4948 my_strnlen
4949 The C library "strnlen" if available, or a Perl implementation
4950 of it.
4951
4952 "my_strnlen()" computes the length of the string, up to
4953 "maxlen" characters. It will never attempt to address more
4954 than "maxlen" characters, making it suitable for use with
4955 strings that are not guaranteed to be NUL-terminated.
4956
4957 Size_t my_strnlen(const char *str, Size_t maxlen)
4958
4959 my_vsnprintf
4960 The C library "vsnprintf" if available and standards-compliant.
4961 However, if the "vsnprintf" is not available, will
4962 unfortunately use the unsafe "vsprintf" which can overrun the
4963 buffer (there is an overrun check, but that may be too late).
4964 Consider using "sv_vcatpvf" instead, or getting "vsnprintf".
4965
4966 int my_vsnprintf(char *buffer, const Size_t len,
4967 const char *format, va_list ap)
4968
4969 ninstr Find the first (leftmost) occurrence of a sequence of bytes
4970 within another sequence. This is the Perl version of
4971 "strstr()", extended to handle arbitrary sequences, potentially
4972 containing embedded "NUL" characters ("NUL" is what the initial
4973 "n" in the function name stands for; some systems have an
4974 equivalent, "memmem()", but with a somewhat different API).
4975
4976 Another way of thinking about this function is finding a needle
4977 in a haystack. "big" points to the first byte in the haystack.
4978 "big_end" points to one byte beyond the final byte in the
4979 haystack. "little" points to the first byte in the needle.
4980 "little_end" points to one byte beyond the final byte in the
4981 needle. All the parameters must be non-"NULL".
4982
4983 The function returns "NULL" if there is no occurrence of
4984 "little" within "big". If "little" is the empty string, "big"
4985 is returned.
4986
4987 Because this function operates at the byte level, and because
4988 of the inherent characteristics of UTF-8 (or UTF-EBCDIC), it
4989 will work properly if both the needle and the haystack are
4990 strings with the same UTF-8ness, but not if the UTF-8ness
4991 differs.
4992
4993 char* ninstr(const char* big, const char* bigend,
4994 const char* little, const char* lend)
4995
4996 PERL_SYS_INIT
4997 Provides system-specific tune up of the C runtime environment
4998 necessary to run Perl interpreters. This should be called only
4999 once, before creating any Perl interpreters.
5000
5001 void PERL_SYS_INIT(int *argc, char*** argv)
5002
5003 PERL_SYS_INIT3
5004 Provides system-specific tune up of the C runtime environment
5005 necessary to run Perl interpreters. This should be called only
5006 once, before creating any Perl interpreters.
5007
5008 void PERL_SYS_INIT3(int *argc, char*** argv,
5009 char*** env)
5010
5011 PERL_SYS_TERM
5012 Provides system-specific clean up of the C runtime environment
5013 after running Perl interpreters. This should be called only
5014 once, after freeing any remaining Perl interpreters.
5015
5016 void PERL_SYS_TERM()
5017
5018 READ_XDIGIT
5019 Returns the value of an ASCII-range hex digit and advances the
5020 string pointer. Behaviour is only well defined when
5021 isXDIGIT(*str) is true.
5022
5023 U8 READ_XDIGIT(char str*)
5024
5025 rninstr Like "ninstr", but instead finds the final (rightmost)
5026 occurrence of a sequence of bytes within another sequence,
5027 returning "NULL" if there is no such occurrence.
5028
5029 char* rninstr(const char* big, const char* bigend,
5030 const char* little, const char* lend)
5031
5032 STMT_START
5033 STMT_START { statements; } STMT_END;
5034
5035 can be used as a single statement, as in
5036
5037 if (x) STMT_START { ... } STMT_END; else ...
5038
5039 These are often used in macro definitions. Note that you can't
5040 return a value out of them.
5041
5042 strEQ Test two "NUL"-terminated strings to see if they are equal.
5043 Returns true or false.
5044
5045 bool strEQ(char* s1, char* s2)
5046
5047 strGE Test two "NUL"-terminated strings to see if the first, "s1", is
5048 greater than or equal to the second, "s2". Returns true or
5049 false.
5050
5051 bool strGE(char* s1, char* s2)
5052
5053 strGT Test two "NUL"-terminated strings to see if the first, "s1", is
5054 greater than the second, "s2". Returns true or false.
5055
5056 bool strGT(char* s1, char* s2)
5057
5058 strLE Test two "NUL"-terminated strings to see if the first, "s1", is
5059 less than or equal to the second, "s2". Returns true or false.
5060
5061 bool strLE(char* s1, char* s2)
5062
5063 strLT Test two "NUL"-terminated strings to see if the first, "s1", is
5064 less than the second, "s2". Returns true or false.
5065
5066 bool strLT(char* s1, char* s2)
5067
5068 strNE Test two "NUL"-terminated strings to see if they are different.
5069 Returns true or false.
5070
5071 bool strNE(char* s1, char* s2)
5072
5073 strnEQ Test two "NUL"-terminated strings to see if they are equal.
5074 The "len" parameter indicates the number of bytes to compare.
5075 Returns true or false. (A wrapper for "strncmp").
5076
5077 bool strnEQ(char* s1, char* s2, STRLEN len)
5078
5079 strnNE Test two "NUL"-terminated strings to see if they are different.
5080 The "len" parameter indicates the number of bytes to compare.
5081 Returns true or false. (A wrapper for "strncmp").
5082
5083 bool strnNE(char* s1, char* s2, STRLEN len)
5084
5085 sv_destroyable
5086 Dummy routine which reports that object can be destroyed when
5087 there is no sharing module present. It ignores its single SV
5088 argument, and returns 'true'. Exists to avoid test for a
5089 "NULL" function pointer and because it could potentially warn
5090 under some level of strict-ness.
5091
5092 bool sv_destroyable(SV *sv)
5093
5094 sv_nosharing
5095 Dummy routine which "shares" an SV when there is no sharing
5096 module present. Or "locks" it. Or "unlocks" it. In other
5097 words, ignores its single SV argument. Exists to avoid test
5098 for a "NULL" function pointer and because it could potentially
5099 warn under some level of strict-ness.
5100
5101 void sv_nosharing(SV *sv)
5102
5103 UNLIKELY
5104 Returns the input unchanged, but at the same time it gives a
5105 branch prediction hint to the compiler that this condition is
5106 likely to be false.
5107
5108 vmess "pat" and "args" are a sprintf-style format pattern and
5109 encapsulated argument list, respectively. These are used to
5110 generate a string message. If the message does not end with a
5111 newline, then it will be extended with some indication of the
5112 current location in the code, as described for "mess_sv".
5113
5114 Normally, the resulting message is returned in a new mortal SV.
5115 During global destruction a single SV may be shared between
5116 uses of this function.
5117
5118 SV* vmess(const char* pat, va_list* args)
5119
5121 These functions are related to the method resolution order of perl
5122 classes Also see perlmroapi.
5123
5124 mro_get_linear_isa
5125 Returns the mro linearisation for the given stash. By default,
5126 this will be whatever "mro_get_linear_isa_dfs" returns unless
5127 some other MRO is in effect for the stash. The return value is
5128 a read-only AV*.
5129
5130 You are responsible for "SvREFCNT_inc()" on the return value if
5131 you plan to store it anywhere semi-permanently (otherwise it
5132 might be deleted out from under you the next time the cache is
5133 invalidated).
5134
5135 AV* mro_get_linear_isa(HV* stash)
5136
5137 mro_method_changed_in
5138 Invalidates method caching on any child classes of the given
5139 stash, so that they might notice the changes in this one.
5140
5141 Ideally, all instances of "PL_sub_generation++" in perl source
5142 outside of mro.c should be replaced by calls to this.
5143
5144 Perl automatically handles most of the common ways a method
5145 might be redefined. However, there are a few ways you could
5146 change a method in a stash without the cache code noticing, in
5147 which case you need to call this method afterwards:
5148
5149 1) Directly manipulating the stash HV entries from XS code.
5150
5151 2) Assigning a reference to a readonly scalar constant into a
5152 stash entry in order to create a constant subroutine (like
5153 constant.pm does).
5154
5155 This same method is available from pure perl via,
5156 "mro::method_changed_in(classname)".
5157
5158 void mro_method_changed_in(HV* stash)
5159
5160 mro_register
5161 Registers a custom mro plugin. See perlmroapi for details on
5162 this and other mro functions.
5163
5164 NOTE: this function must be explicitly called as
5165 Perl_mro_register with an aTHX_ parameter.
5166
5167 void Perl_mro_register(pTHX_
5168 const struct mro_alg *mro)
5169
5171 dMULTICALL
5172 Declare local variables for a multicall. See "LIGHTWEIGHT
5173 CALLBACKS" in perlcall.
5174
5175 dMULTICALL;
5176
5177 MULTICALL
5178 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in
5179 perlcall.
5180
5181 MULTICALL;
5182
5183 POP_MULTICALL
5184 Closing bracket for a lightweight callback. See "LIGHTWEIGHT
5185 CALLBACKS" in perlcall.
5186
5187 POP_MULTICALL;
5188
5189 PUSH_MULTICALL
5190 Opening bracket for a lightweight callback. See "LIGHTWEIGHT
5191 CALLBACKS" in perlcall.
5192
5193 PUSH_MULTICALL(CV* the_cv);
5194
5196 grok_bin
5197 converts a string representing a binary number to numeric form.
5198
5199 On entry "start" and *len_p give the string to scan, *flags
5200 gives conversion flags, and "result" should be "NULL" or a
5201 pointer to an NV. The scan stops at the end of the string, or
5202 at just before the first invalid character. Unless
5203 "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5204 invalid character (except NUL) will also trigger a warning. On
5205 return *len_p is set to the length of the scanned string, and
5206 *flags gives output flags.
5207
5208 If the value is <= "UV_MAX" it is returned as a UV, the output
5209 flags are clear, and nothing is written to *result. If the
5210 value is > "UV_MAX", "grok_bin" returns "UV_MAX", sets
5211 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5212 an approximation of the correct value into *result (which is an
5213 NV; or the approximation is discarded if "result" is NULL).
5214
5215 The binary number may optionally be prefixed with "0b" or "b"
5216 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
5217
5218 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5219 all pairs of digits may be separated from each other by a
5220 single underscore; also a single leading underscore is
5221 accepted.
5222
5223 UV grok_bin(const char* start, STRLEN* len_p,
5224 I32* flags, NV *result)
5225
5226 grok_hex
5227 converts a string representing a hex number to numeric form.
5228
5229 On entry "start" and *len_p give the string to scan, *flags
5230 gives conversion flags, and "result" should be "NULL" or a
5231 pointer to an NV. The scan stops at the end of the string, or
5232 at just before the first invalid character. Unless
5233 "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5234 invalid character (except NUL) will also trigger a warning. On
5235 return *len_p is set to the length of the scanned string, and
5236 *flags gives output flags.
5237
5238 If the value is <= "UV_MAX" it is returned as a UV, the output
5239 flags are clear, and nothing is written to *result. If the
5240 value is > "UV_MAX", "grok_hex" returns "UV_MAX", sets
5241 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5242 an approximation of the correct value into *result (which is an
5243 NV; or the approximation is discarded if "result" is NULL).
5244
5245 The hex number may optionally be prefixed with "0x" or "x"
5246 unless "PERL_SCAN_DISALLOW_PREFIX" is set in *flags on entry.
5247
5248 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5249 all pairs of digits may be separated from each other by a
5250 single underscore; also a single leading underscore is
5251 accepted.
5252
5253 UV grok_hex(const char* start, STRLEN* len_p,
5254 I32* flags, NV *result)
5255
5256 grok_infnan
5257 Helper for "grok_number()", accepts various ways of spelling
5258 "infinity" or "not a number", and returns one of the following
5259 flag combinations:
5260
5261 IS_NUMBER_INFINITY
5262 IS_NUMBER_NAN
5263 IS_NUMBER_INFINITY | IS_NUMBER_NEG
5264 IS_NUMBER_NAN | IS_NUMBER_NEG
5265 0
5266
5267 possibly |-ed with "IS_NUMBER_TRAILING".
5268
5269 If an infinity or a not-a-number is recognized, *sp will point
5270 to one byte past the end of the recognized string. If the
5271 recognition fails, zero is returned, and *sp will not move.
5272
5273 int grok_infnan(const char** sp, const char *send)
5274
5275 grok_number
5276 Identical to "grok_number_flags()" with "flags" set to zero.
5277
5278 int grok_number(const char *pv, STRLEN len,
5279 UV *valuep)
5280
5281 grok_number_flags
5282 Recognise (or not) a number. The type of the number is
5283 returned (0 if unrecognised), otherwise it is a bit-ORed
5284 combination of "IS_NUMBER_IN_UV",
5285 "IS_NUMBER_GREATER_THAN_UV_MAX", "IS_NUMBER_NOT_INT",
5286 "IS_NUMBER_NEG", "IS_NUMBER_INFINITY", "IS_NUMBER_NAN" (defined
5287 in perl.h).
5288
5289 If the value of the number can fit in a UV, it is returned in
5290 *valuep. "IS_NUMBER_IN_UV" will be set to indicate that
5291 *valuep is valid, "IS_NUMBER_IN_UV" will never be set unless
5292 *valuep is valid, but *valuep may have been assigned to during
5293 processing even though "IS_NUMBER_IN_UV" is not set on return.
5294 If "valuep" is "NULL", "IS_NUMBER_IN_UV" will be set for the
5295 same cases as when "valuep" is non-"NULL", but no actual
5296 assignment (or SEGV) will occur.
5297
5298 "IS_NUMBER_NOT_INT" will be set with "IS_NUMBER_IN_UV" if
5299 trailing decimals were seen (in which case *valuep gives the
5300 true value truncated to an integer), and "IS_NUMBER_NEG" if the
5301 number is negative (in which case *valuep holds the absolute
5302 value). "IS_NUMBER_IN_UV" is not set if e notation was used or
5303 the number is larger than a UV.
5304
5305 "flags" allows only "PERL_SCAN_TRAILING", which allows for
5306 trailing non-numeric text on an otherwise successful grok,
5307 setting "IS_NUMBER_TRAILING" on the result.
5308
5309 int grok_number_flags(const char *pv, STRLEN len,
5310 UV *valuep, U32 flags)
5311
5312 GROK_NUMERIC_RADIX
5313 A synonym for "grok_numeric_radix"
5314
5315 bool GROK_NUMERIC_RADIX(NN const char **sp,
5316 NN const char *send)
5317
5318 grok_numeric_radix
5319 Scan and skip for a numeric decimal separator (radix).
5320
5321 bool grok_numeric_radix(const char **sp,
5322 const char *send)
5323
5324 grok_oct
5325 converts a string representing an octal number to numeric form.
5326
5327 On entry "start" and *len_p give the string to scan, *flags
5328 gives conversion flags, and "result" should be "NULL" or a
5329 pointer to an NV. The scan stops at the end of the string, or
5330 at just before the first invalid character. Unless
5331 "PERL_SCAN_SILENT_ILLDIGIT" is set in *flags, encountering an
5332 invalid character (except NUL) will also trigger a warning. On
5333 return *len_p is set to the length of the scanned string, and
5334 *flags gives output flags.
5335
5336 If the value is <= "UV_MAX" it is returned as a UV, the output
5337 flags are clear, and nothing is written to *result. If the
5338 value is > "UV_MAX", "grok_oct" returns "UV_MAX", sets
5339 "PERL_SCAN_GREATER_THAN_UV_MAX" in the output flags, and writes
5340 an approximation of the correct value into *result (which is an
5341 NV; or the approximation is discarded if "result" is NULL).
5342
5343 If "PERL_SCAN_ALLOW_UNDERSCORES" is set in *flags then any or
5344 all pairs of digits may be separated from each other by a
5345 single underscore; also a single leading underscore is
5346 accepted.
5347
5348 The "PERL_SCAN_DISALLOW_PREFIX" flag is always treated as being
5349 set for this function.
5350
5351 UV grok_oct(const char* start, STRLEN* len_p,
5352 I32* flags, NV *result)
5353
5354 isinfnan
5355 "Perl_isinfnan()" is a utility function that returns true if
5356 the NV argument is either an infinity or a "NaN", false
5357 otherwise. To test in more detail, use "Perl_isinf()" and
5358 "Perl_isnan()".
5359
5360 This is also the logical inverse of Perl_isfinite().
5361
5362 bool isinfnan(NV nv)
5363
5364 IS_NUMBER_GREATER_THAN_UV_MAX bool IS_NUMBER_GREATER_THAN_UV_MAX
5365 IS_NUMBER_INFINITY bool IS_NUMBER_INFINITY
5366 IS_NUMBER_IN_UV bool IS_NUMBER_IN_UV
5367 IS_NUMBER_NAN bool IS_NUMBER_NAN
5368 IS_NUMBER_NEG bool IS_NUMBER_NEG
5369 IS_NUMBER_NOT_INT
5370 bool IS_NUMBER_NOT_INT
5371
5372 my_strtod
5373 This function is equivalent to the libc strtod() function, and
5374 is available even on platforms that lack plain strtod(). Its
5375 return value is the best available precision depending on
5376 platform capabilities and Configure options.
5377
5378 It properly handles the locale radix character, meaning it
5379 expects a dot except when called from within the scope of
5380 "use locale", in which case the radix character should be that
5381 specified by the current locale.
5382
5383 The synonym Strtod() may be used instead.
5384
5385 NV my_strtod(const char * const s, char ** e)
5386
5387 PERL_ABS
5388 Typeless "abs" or "fabs", etc. (The usage below indicates it
5389 is for integers, but it works for any type.) Use instead of
5390 these, since the C library ones force their argument to be what
5391 it is expecting, potentially leading to disaster. But also
5392 beware that this evaluates its argument twice, so no "x++".
5393
5394 int PERL_ABS(int)
5395
5396 PERL_INT_MAX
5397 This and "PERL_INT_MIN", "PERL_LONG_MAX", "PERL_LONG_MIN",
5398 "PERL_QUAD_MAX", "PERL_SHORT_MAX", "PERL_SHORT_MIN",
5399 "PERL_UCHAR_MAX", "PERL_UCHAR_MIN", "PERL_UINT_MAX",
5400 "PERL_ULONG_MAX", "PERL_ULONG_MIN", "PERL_UQUAD_MAX",
5401 "PERL_UQUAD_MIN", "PERL_USHORT_MAX", "PERL_USHORT_MIN",
5402 "PERL_QUAD_MIN" give the largest and smallest number
5403 representable in the current platform in variables of the
5404 corresponding types.
5405
5406 For signed types, the smallest representable number is the most
5407 negative number, the one furthest away from zero.
5408
5409 For C99 and later compilers, these correspond to things like
5410 "INT_MAX", which are available to the C code. But these
5411 constants, furnished by Perl, allow code compiled on earlier
5412 compilers to portably have access to the same constants.
5413
5414 Perl_signbit
5415 NOTE: this function is experimental and may change or be
5416 removed without notice.
5417
5418 Return a non-zero integer if the sign bit on an NV is set, and
5419 0 if it is not.
5420
5421 If Configure detects this system has a "signbit()" that will
5422 work with our NVs, then we just use it via the "#define" in
5423 perl.h. Otherwise, fall back on this implementation. The main
5424 use of this function is catching "-0.0".
5425
5426 "Configure" notes: This function is called 'Perl_signbit'
5427 instead of a plain 'signbit' because it is easy to imagine a
5428 system having a "signbit()" function or macro that doesn't
5429 happen to work with our particular choice of NVs. We shouldn't
5430 just re-"#define" "signbit" as "Perl_signbit" and expect the
5431 standard system headers to be happy. Also, this is a no-
5432 context function (no "pTHX_") because "Perl_signbit()" is
5433 usually re-"#defined" in perl.h as a simple macro call to the
5434 system's "signbit()". Users should just always call
5435 "Perl_signbit()".
5436
5437 int Perl_signbit(NV f)
5438
5439 scan_bin
5440 For backwards compatibility. Use "grok_bin" instead.
5441
5442 NV scan_bin(const char* start, STRLEN len,
5443 STRLEN* retlen)
5444
5445 scan_hex
5446 For backwards compatibility. Use "grok_hex" instead.
5447
5448 NV scan_hex(const char* start, STRLEN len,
5449 STRLEN* retlen)
5450
5451 scan_oct
5452 For backwards compatibility. Use "grok_oct" instead.
5453
5454 NV scan_oct(const char* start, STRLEN len,
5455 STRLEN* retlen)
5456
5457 Strtod This is a synonym for "my_strtod".
5458
5459 NV Strtod(NN const char * const s,
5460 NULLOK char ** e)
5461
5462 Strtol Platform and configuration independent "strtol". This expands
5463 to the appropriate "strotol"-like function based on the
5464 platform and Configure options>. For example it could expand
5465 to "strtoll" or "strtoq" instead of "strtol".
5466
5467 NV Strtol(NN const char * const s,
5468 NULLOK char ** e, int base)
5469
5470 Strtoul Platform and configuration independent "strtoul". This expands
5471 to the appropriate "strotoul"-like function based on the
5472 platform and Configure options>. For example it could expand
5473 to "strtoull" or "strtouq" instead of "strtoul".
5474
5475 NV Strtoul(NN const char * const s,
5476 NULLOK char ** e, int base)
5477
5479 Some of these are also deprecated. You can exclude these from your
5480 compiled Perl by adding this option to Configure:
5481 "-Accflags='-DNO_MATHOMS'"
5482
5483 custom_op_desc
5484 DEPRECATED! It is planned to remove this function from a
5485 future release of Perl. Do not use it for new code; remove it
5486 from existing code.
5487
5488 Return the description of a given custom op. This was once
5489 used by the "OP_DESC" macro, but is no longer: it has only been
5490 kept for compatibility, and should not be used.
5491
5492 const char * custom_op_desc(const OP *o)
5493
5494 custom_op_name
5495 DEPRECATED! It is planned to remove this function from a
5496 future release of Perl. Do not use it for new code; remove it
5497 from existing code.
5498
5499 Return the name for a given custom op. This was once used by
5500 the "OP_NAME" macro, but is no longer: it has only been kept
5501 for compatibility, and should not be used.
5502
5503 const char * custom_op_name(const OP *o)
5504
5505 gv_fetchmethod
5506 See "gv_fetchmethod_autoload".
5507
5508 GV* gv_fetchmethod(HV* stash, const char* name)
5509
5510 is_utf8_char
5511 DEPRECATED! It is planned to remove this function from a
5512 future release of Perl. Do not use it for new code; remove it
5513 from existing code.
5514
5515 Tests if some arbitrary number of bytes begins in a valid UTF-8
5516 character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC
5517 machines) character is a valid UTF-8 character. The actual
5518 number of bytes in the UTF-8 character will be returned if it
5519 is valid, otherwise 0.
5520
5521 This function is deprecated due to the possibility that
5522 malformed input could cause reading beyond the end of the input
5523 buffer. Use "isUTF8_CHAR" instead.
5524
5525 STRLEN is_utf8_char(const U8 *s)
5526
5527 is_utf8_char_buf
5528 This is identical to the macro "isUTF8_CHAR" in perlapi.
5529
5530 STRLEN is_utf8_char_buf(const U8 *buf,
5531 const U8 *buf_end)
5532
5533 pack_cat
5534 The engine implementing "pack()" Perl function. Note:
5535 parameters "next_in_list" and "flags" are not used. This call
5536 should not be used; use "packlist" instead.
5537
5538 void pack_cat(SV *cat, const char *pat,
5539 const char *patend, SV **beglist,
5540 SV **endlist, SV ***next_in_list,
5541 U32 flags)
5542
5543 pad_compname_type
5544 Looks up the type of the lexical variable at position "po" in
5545 the currently-compiling pad. If the variable is typed, the
5546 stash of the class to which it is typed is returned. If not,
5547 "NULL" is returned.
5548
5549 HV* pad_compname_type(const PADOFFSET po)
5550
5551 sv_2pvbyte_nolen
5552 Return a pointer to the byte-encoded representation of the SV.
5553 May cause the SV to be downgraded from UTF-8 as a side-effect.
5554
5555 Usually accessed via the "SvPVbyte_nolen" macro.
5556
5557 char* sv_2pvbyte_nolen(SV* sv)
5558
5559 sv_2pvutf8_nolen
5560 Return a pointer to the UTF-8-encoded representation of the SV.
5561 May cause the SV to be upgraded to UTF-8 as a side-effect.
5562
5563 Usually accessed via the "SvPVutf8_nolen" macro.
5564
5565 char* sv_2pvutf8_nolen(SV* sv)
5566
5567 sv_2pv_nolen
5568 Like "sv_2pv()", but doesn't return the length too. You should
5569 usually use the macro wrapper "SvPV_nolen(sv)" instead.
5570
5571 char* sv_2pv_nolen(SV* sv)
5572
5573 sv_catpvn_mg
5574 Like "sv_catpvn", but also handles 'set' magic.
5575
5576 void sv_catpvn_mg(SV *sv, const char *ptr,
5577 STRLEN len)
5578
5579 sv_catsv_mg
5580 Like "sv_catsv", but also handles 'set' magic.
5581
5582 void sv_catsv_mg(SV *dsv, SV *ssv)
5583
5584 sv_force_normal
5585 Undo various types of fakery on an SV: if the PV is a shared
5586 string, make a private copy; if we're a ref, stop refing; if
5587 we're a glob, downgrade to an "xpvmg". See also
5588 "sv_force_normal_flags".
5589
5590 void sv_force_normal(SV *sv)
5591
5592 sv_iv DEPRECATED! It is planned to remove this function from a
5593 future release of Perl. Do not use it for new code; remove it
5594 from existing code.
5595
5596 A private implementation of the "SvIVx" macro for compilers
5597 which can't cope with complex macro expressions. Always use
5598 the macro instead.
5599
5600 IV sv_iv(SV* sv)
5601
5602 sv_nolocking
5603 DEPRECATED! It is planned to remove this function from a
5604 future release of Perl. Do not use it for new code; remove it
5605 from existing code.
5606
5607 Dummy routine which "locks" an SV when there is no locking
5608 module present. Exists to avoid test for a "NULL" function
5609 pointer and because it could potentially warn under some level
5610 of strict-ness.
5611
5612 "Superseded" by "sv_nosharing()".
5613
5614 void sv_nolocking(SV *sv)
5615
5616 sv_nounlocking
5617 DEPRECATED! It is planned to remove this function from a
5618 future release of Perl. Do not use it for new code; remove it
5619 from existing code.
5620
5621 Dummy routine which "unlocks" an SV when there is no locking
5622 module present. Exists to avoid test for a "NULL" function
5623 pointer and because it could potentially warn under some level
5624 of strict-ness.
5625
5626 "Superseded" by "sv_nosharing()".
5627
5628 void sv_nounlocking(SV *sv)
5629
5630 sv_nv DEPRECATED! It is planned to remove this function from a
5631 future release of Perl. Do not use it for new code; remove it
5632 from existing code.
5633
5634 A private implementation of the "SvNVx" macro for compilers
5635 which can't cope with complex macro expressions. Always use
5636 the macro instead.
5637
5638 NV sv_nv(SV* sv)
5639
5640 sv_pv Use the "SvPV_nolen" macro instead
5641
5642 char* sv_pv(SV *sv)
5643
5644 sv_pvbyte
5645 Use "SvPVbyte_nolen" instead.
5646
5647 char* sv_pvbyte(SV *sv)
5648
5649 sv_pvbyten
5650 DEPRECATED! It is planned to remove this function from a
5651 future release of Perl. Do not use it for new code; remove it
5652 from existing code.
5653
5654 A private implementation of the "SvPVbyte" macro for compilers
5655 which can't cope with complex macro expressions. Always use
5656 the macro instead.
5657
5658 char* sv_pvbyten(SV *sv, STRLEN *lp)
5659
5660 sv_pvn DEPRECATED! It is planned to remove this function from a
5661 future release of Perl. Do not use it for new code; remove it
5662 from existing code.
5663
5664 A private implementation of the "SvPV" macro for compilers
5665 which can't cope with complex macro expressions. Always use
5666 the macro instead.
5667
5668 char* sv_pvn(SV *sv, STRLEN *lp)
5669
5670 sv_pvutf8
5671 Use the "SvPVutf8_nolen" macro instead
5672
5673 char* sv_pvutf8(SV *sv)
5674
5675 sv_pvutf8n
5676 DEPRECATED! It is planned to remove this function from a
5677 future release of Perl. Do not use it for new code; remove it
5678 from existing code.
5679
5680 A private implementation of the "SvPVutf8" macro for compilers
5681 which can't cope with complex macro expressions. Always use
5682 the macro instead.
5683
5684 char* sv_pvutf8n(SV *sv, STRLEN *lp)
5685
5686 sv_taint
5687 Taint an SV. Use "SvTAINTED_on" instead.
5688
5689 void sv_taint(SV* sv)
5690
5691 sv_unref
5692 Unsets the RV status of the SV, and decrements the reference
5693 count of whatever was being referenced by the RV. This can
5694 almost be thought of as a reversal of "newSVrv". This is
5695 "sv_unref_flags" with the "flag" being zero. See "SvROK_off".
5696
5697 void sv_unref(SV* sv)
5698
5699 sv_usepvn
5700 Tells an SV to use "ptr" to find its string value. Implemented
5701 by calling "sv_usepvn_flags" with "flags" of 0, hence does not
5702 handle 'set' magic. See "sv_usepvn_flags".
5703
5704 void sv_usepvn(SV* sv, char* ptr, STRLEN len)
5705
5706 sv_usepvn_mg
5707 Like "sv_usepvn", but also handles 'set' magic.
5708
5709 void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
5710
5711 sv_uv DEPRECATED! It is planned to remove this function from a
5712 future release of Perl. Do not use it for new code; remove it
5713 from existing code.
5714
5715 A private implementation of the "SvUVx" macro for compilers
5716 which can't cope with complex macro expressions. Always use
5717 the macro instead.
5718
5719 UV sv_uv(SV* sv)
5720
5721 unpack_str
5722 DEPRECATED! It is planned to remove this function from a
5723 future release of Perl. Do not use it for new code; remove it
5724 from existing code.
5725
5726 The engine implementing "unpack()" Perl function. Note:
5727 parameters "strbeg", "new_s" and "ocnt" are not used. This
5728 call should not be used, use "unpackstring" instead.
5729
5730 SSize_t unpack_str(const char *pat, const char *patend,
5731 const char *s, const char *strbeg,
5732 const char *strend, char **new_s,
5733 I32 ocnt, U32 flags)
5734
5735 utf8_to_uvchr
5736 DEPRECATED! It is planned to remove this function from a
5737 future release of Perl. Do not use it for new code; remove it
5738 from existing code.
5739
5740 Returns the native code point of the first character in the
5741 string "s" which is assumed to be in UTF-8 encoding; "retlen"
5742 will be set to the length, in bytes, of that character.
5743
5744 Some, but not all, UTF-8 malformations are detected, and in
5745 fact, some malformed input could cause reading beyond the end
5746 of the input buffer, which is why this function is deprecated.
5747 Use "utf8_to_uvchr_buf" instead.
5748
5749 If "s" points to one of the detected malformations, and UTF8
5750 warnings are enabled, zero is returned and *retlen is set (if
5751 "retlen" isn't "NULL") to -1. If those warnings are off, the
5752 computed value if well-defined (or the Unicode REPLACEMENT
5753 CHARACTER, if not) is silently returned, and *retlen is set (if
5754 "retlen" isn't NULL) so that ("s" + *retlen) is the next
5755 possible position in "s" that could begin a non-malformed
5756 character. See "utf8n_to_uvchr" for details on when the
5757 REPLACEMENT CHARACTER is returned.
5758
5759 UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
5760
5762 newASSIGNOP
5763 Constructs, checks, and returns an assignment op. "left" and
5764 "right" supply the parameters of the assignment; they are
5765 consumed by this function and become part of the constructed op
5766 tree.
5767
5768 If "optype" is "OP_ANDASSIGN", "OP_ORASSIGN", or
5769 "OP_DORASSIGN", then a suitable conditional optree is
5770 constructed. If "optype" is the opcode of a binary operator,
5771 such as "OP_BIT_OR", then an op is constructed that performs
5772 the binary operation and assigns the result to the left
5773 argument. Either way, if "optype" is non-zero then "flags" has
5774 no effect.
5775
5776 If "optype" is zero, then a plain scalar or list assignment is
5777 constructed. Which type of assignment it is is automatically
5778 determined. "flags" gives the eight bits of "op_flags", except
5779 that "OPf_KIDS" will be set automatically, and, shifted up
5780 eight bits, the eight bits of "op_private", except that the bit
5781 with value 1 or 2 is automatically set as required.
5782
5783 OP* newASSIGNOP(I32 flags, OP* left, I32 optype,
5784 OP* right)
5785
5786 newBINOP
5787 Constructs, checks, and returns an op of any binary type.
5788 "type" is the opcode. "flags" gives the eight bits of
5789 "op_flags", except that "OPf_KIDS" will be set automatically,
5790 and, shifted up eight bits, the eight bits of "op_private",
5791 except that the bit with value 1 or 2 is automatically set as
5792 required. "first" and "last" supply up to two ops to be the
5793 direct children of the binary op; they are consumed by this
5794 function and become part of the constructed op tree.
5795
5796 OP* newBINOP(I32 type, I32 flags, OP* first,
5797 OP* last)
5798
5799 newCONDOP
5800 Constructs, checks, and returns a conditional-expression
5801 ("cond_expr") op. "flags" gives the eight bits of "op_flags",
5802 except that "OPf_KIDS" will be set automatically, and, shifted
5803 up eight bits, the eight bits of "op_private", except that the
5804 bit with value 1 is automatically set. "first" supplies the
5805 expression selecting between the two branches, and "trueop" and
5806 "falseop" supply the branches; they are consumed by this
5807 function and become part of the constructed op tree.
5808
5809 OP* newCONDOP(I32 flags, OP* first, OP* trueop,
5810 OP* falseop)
5811
5812 newDEFSVOP
5813 Constructs and returns an op to access $_.
5814
5815 OP* newDEFSVOP()
5816
5817 newFOROP
5818 Constructs, checks, and returns an op tree expressing a
5819 "foreach" loop (iteration through a list of values). This is a
5820 heavyweight loop, with structure that allows exiting the loop
5821 by "last" and suchlike.
5822
5823 "sv" optionally supplies the variable that will be aliased to
5824 each item in turn; if null, it defaults to $_. "expr" supplies
5825 the list of values to iterate over. "block" supplies the main
5826 body of the loop, and "cont" optionally supplies a "continue"
5827 block that operates as a second half of the body. All of these
5828 optree inputs are consumed by this function and become part of
5829 the constructed op tree.
5830
5831 "flags" gives the eight bits of "op_flags" for the "leaveloop"
5832 op and, shifted up eight bits, the eight bits of "op_private"
5833 for the "leaveloop" op, except that (in both cases) some bits
5834 will be set automatically.
5835
5836 OP* newFOROP(I32 flags, OP* sv, OP* expr, OP* block,
5837 OP* cont)
5838
5839 newGIVENOP
5840 Constructs, checks, and returns an op tree expressing a "given"
5841 block. "cond" supplies the expression to whose value $_ will
5842 be locally aliased, and "block" supplies the body of the
5843 "given" construct; they are consumed by this function and
5844 become part of the constructed op tree. "defsv_off" must be
5845 zero (it used to identity the pad slot of lexical $_).
5846
5847 OP* newGIVENOP(OP* cond, OP* block,
5848 PADOFFSET defsv_off)
5849
5850 newGVOP Constructs, checks, and returns an op of any type that involves
5851 an embedded reference to a GV. "type" is the opcode. "flags"
5852 gives the eight bits of "op_flags". "gv" identifies the GV
5853 that the op should reference; calling this function does not
5854 transfer ownership of any reference to it.
5855
5856 OP* newGVOP(I32 type, I32 flags, GV* gv)
5857
5858 newLISTOP
5859 Constructs, checks, and returns an op of any list type. "type"
5860 is the opcode. "flags" gives the eight bits of "op_flags",
5861 except that "OPf_KIDS" will be set automatically if required.
5862 "first" and "last" supply up to two ops to be direct children
5863 of the list op; they are consumed by this function and become
5864 part of the constructed op tree.
5865
5866 For most list operators, the check function expects all the kid
5867 ops to be present already, so calling "newLISTOP(OP_JOIN, ...)"
5868 (e.g.) is not appropriate. What you want to do in that case is
5869 create an op of type "OP_LIST", append more children to it, and
5870 then call "op_convert_list". See "op_convert_list" for more
5871 information.
5872
5873 OP* newLISTOP(I32 type, I32 flags, OP* first,
5874 OP* last)
5875
5876 newLOGOP
5877 Constructs, checks, and returns a logical (flow control) op.
5878 "type" is the opcode. "flags" gives the eight bits of
5879 "op_flags", except that "OPf_KIDS" will be set automatically,
5880 and, shifted up eight bits, the eight bits of "op_private",
5881 except that the bit with value 1 is automatically set. "first"
5882 supplies the expression controlling the flow, and "other"
5883 supplies the side (alternate) chain of ops; they are consumed
5884 by this function and become part of the constructed op tree.
5885
5886 OP* newLOGOP(I32 optype, I32 flags, OP *first,
5887 OP *other)
5888
5889 newLOOPEX
5890 Constructs, checks, and returns a loop-exiting op (such as
5891 "goto" or "last"). "type" is the opcode. "label" supplies the
5892 parameter determining the target of the op; it is consumed by
5893 this function and becomes part of the constructed op tree.
5894
5895 OP* newLOOPEX(I32 type, OP* label)
5896
5897 newLOOPOP
5898 Constructs, checks, and returns an op tree expressing a loop.
5899 This is only a loop in the control flow through the op tree; it
5900 does not have the heavyweight loop structure that allows
5901 exiting the loop by "last" and suchlike. "flags" gives the
5902 eight bits of "op_flags" for the top-level op, except that some
5903 bits will be set automatically as required. "expr" supplies
5904 the expression controlling loop iteration, and "block" supplies
5905 the body of the loop; they are consumed by this function and
5906 become part of the constructed op tree. "debuggable" is
5907 currently unused and should always be 1.
5908
5909 OP* newLOOPOP(I32 flags, I32 debuggable, OP* expr,
5910 OP* block)
5911
5912 newMETHOP
5913 Constructs, checks, and returns an op of method type with a
5914 method name evaluated at runtime. "type" is the opcode.
5915 "flags" gives the eight bits of "op_flags", except that
5916 "OPf_KIDS" will be set automatically, and, shifted up eight
5917 bits, the eight bits of "op_private", except that the bit with
5918 value 1 is automatically set. "dynamic_meth" supplies an op
5919 which evaluates method name; it is consumed by this function
5920 and become part of the constructed op tree. Supported optypes:
5921 "OP_METHOD".
5922
5923 OP* newMETHOP(I32 type, I32 flags, OP* dynamic_meth)
5924
5925 newMETHOP_named
5926 Constructs, checks, and returns an op of method type with a
5927 constant method name. "type" is the opcode. "flags" gives the
5928 eight bits of "op_flags", and, shifted up eight bits, the eight
5929 bits of "op_private". "const_meth" supplies a constant method
5930 name; it must be a shared COW string. Supported optypes:
5931 "OP_METHOD_NAMED".
5932
5933 OP* newMETHOP_named(I32 type, I32 flags,
5934 SV* const_meth)
5935
5936 newNULLLIST
5937 Constructs, checks, and returns a new "stub" op, which
5938 represents an empty list expression.
5939
5940 OP* newNULLLIST()
5941
5942 newOP Constructs, checks, and returns an op of any base type (any
5943 type that has no extra fields). "type" is the opcode. "flags"
5944 gives the eight bits of "op_flags", and, shifted up eight bits,
5945 the eight bits of "op_private".
5946
5947 OP* newOP(I32 optype, I32 flags)
5948
5949 newPADOP
5950 Constructs, checks, and returns an op of any type that involves
5951 a reference to a pad element. "type" is the opcode. "flags"
5952 gives the eight bits of "op_flags". A pad slot is
5953 automatically allocated, and is populated with "sv"; this
5954 function takes ownership of one reference to it.
5955
5956 This function only exists if Perl has been compiled to use
5957 ithreads.
5958
5959 OP* newPADOP(I32 type, I32 flags, SV* sv)
5960
5961 newPMOP Constructs, checks, and returns an op of any pattern matching
5962 type. "type" is the opcode. "flags" gives the eight bits of
5963 "op_flags" and, shifted up eight bits, the eight bits of
5964 "op_private".
5965
5966 OP* newPMOP(I32 type, I32 flags)
5967
5968 newPVOP Constructs, checks, and returns an op of any type that involves
5969 an embedded C-level pointer (PV). "type" is the opcode.
5970 "flags" gives the eight bits of "op_flags". "pv" supplies the
5971 C-level pointer. Depending on the op type, the memory
5972 referenced by "pv" may be freed when the op is destroyed. If
5973 the op is of a freeing type, "pv" must have been allocated
5974 using "PerlMemShared_malloc".
5975
5976 OP* newPVOP(I32 type, I32 flags, char* pv)
5977
5978 newRANGE
5979 Constructs and returns a "range" op, with subordinate "flip"
5980 and "flop" ops. "flags" gives the eight bits of "op_flags" for
5981 the "flip" op and, shifted up eight bits, the eight bits of
5982 "op_private" for both the "flip" and "range" ops, except that
5983 the bit with value 1 is automatically set. "left" and "right"
5984 supply the expressions controlling the endpoints of the range;
5985 they are consumed by this function and become part of the
5986 constructed op tree.
5987
5988 OP* newRANGE(I32 flags, OP* left, OP* right)
5989
5990 newSLICEOP
5991 Constructs, checks, and returns an "lslice" (list slice) op.
5992 "flags" gives the eight bits of "op_flags", except that
5993 "OPf_KIDS" will be set automatically, and, shifted up eight
5994 bits, the eight bits of "op_private", except that the bit with
5995 value 1 or 2 is automatically set as required. "listval" and
5996 "subscript" supply the parameters of the slice; they are
5997 consumed by this function and become part of the constructed op
5998 tree.
5999
6000 OP* newSLICEOP(I32 flags, OP* subscript, OP* listop)
6001
6002 newSTATEOP
6003 Constructs a state op (COP). The state op is normally a
6004 "nextstate" op, but will be a "dbstate" op if debugging is
6005 enabled for currently-compiled code. The state op is populated
6006 from "PL_curcop" (or "PL_compiling"). If "label" is non-null,
6007 it supplies the name of a label to attach to the state op; this
6008 function takes ownership of the memory pointed at by "label",
6009 and will free it. "flags" gives the eight bits of "op_flags"
6010 for the state op.
6011
6012 If "o" is null, the state op is returned. Otherwise the state
6013 op is combined with "o" into a "lineseq" list op, which is
6014 returned. "o" is consumed by this function and becomes part of
6015 the returned op tree.
6016
6017 OP* newSTATEOP(I32 flags, char* label, OP* o)
6018
6019 newSVOP Constructs, checks, and returns an op of any type that involves
6020 an embedded SV. "type" is the opcode. "flags" gives the eight
6021 bits of "op_flags". "sv" gives the SV to embed in the op; this
6022 function takes ownership of one reference to it.
6023
6024 OP* newSVOP(I32 type, I32 flags, SV* sv)
6025
6026 newUNOP Constructs, checks, and returns an op of any unary type.
6027 "type" is the opcode. "flags" gives the eight bits of
6028 "op_flags", except that "OPf_KIDS" will be set automatically if
6029 required, and, shifted up eight bits, the eight bits of
6030 "op_private", except that the bit with value 1 is automatically
6031 set. "first" supplies an optional op to be the direct child of
6032 the unary op; it is consumed by this function and become part
6033 of the constructed op tree.
6034
6035 OP* newUNOP(I32 type, I32 flags, OP* first)
6036
6037 newUNOP_AUX
6038 Similar to "newUNOP", but creates an "UNOP_AUX" struct instead,
6039 with "op_aux" initialised to "aux"
6040
6041 OP* newUNOP_AUX(I32 type, I32 flags, OP* first,
6042 UNOP_AUX_item *aux)
6043
6044 newWHENOP
6045 Constructs, checks, and returns an op tree expressing a "when"
6046 block. "cond" supplies the test expression, and "block"
6047 supplies the block that will be executed if the test evaluates
6048 to true; they are consumed by this function and become part of
6049 the constructed op tree. "cond" will be interpreted
6050 DWIMically, often as a comparison against $_, and may be null
6051 to generate a "default" block.
6052
6053 OP* newWHENOP(OP* cond, OP* block)
6054
6055 newWHILEOP
6056 Constructs, checks, and returns an op tree expressing a "while"
6057 loop. This is a heavyweight loop, with structure that allows
6058 exiting the loop by "last" and suchlike.
6059
6060 "loop" is an optional preconstructed "enterloop" op to use in
6061 the loop; if it is null then a suitable op will be constructed
6062 automatically. "expr" supplies the loop's controlling
6063 expression. "block" supplies the main body of the loop, and
6064 "cont" optionally supplies a "continue" block that operates as
6065 a second half of the body. All of these optree inputs are
6066 consumed by this function and become part of the constructed op
6067 tree.
6068
6069 "flags" gives the eight bits of "op_flags" for the "leaveloop"
6070 op and, shifted up eight bits, the eight bits of "op_private"
6071 for the "leaveloop" op, except that (in both cases) some bits
6072 will be set automatically. "debuggable" is currently unused
6073 and should always be 1. "has_my" can be supplied as true to
6074 force the loop body to be enclosed in its own scope.
6075
6076 OP* newWHILEOP(I32 flags, I32 debuggable,
6077 LOOP* loop, OP* expr, OP* block,
6078 OP* cont, I32 has_my)
6079
6081 alloccopstash
6082 NOTE: this function is experimental and may change or be
6083 removed without notice.
6084
6085 Available only under threaded builds, this function allocates
6086 an entry in "PL_stashpad" for the stash passed to it.
6087
6088 PADOFFSET alloccopstash(HV *hv)
6089
6090 block_end
6091 Handles compile-time scope exit. "floor" is the savestack
6092 index returned by "block_start", and "seq" is the body of the
6093 block. Returns the block, possibly modified.
6094
6095 OP* block_end(I32 floor, OP* seq)
6096
6097 block_start
6098 Handles compile-time scope entry. Arranges for hints to be
6099 restored on block exit and also handles pad sequence numbers to
6100 make lexical variables scope right. Returns a savestack index
6101 for use with "block_end".
6102
6103 int block_start(int full)
6104
6105 ck_entersub_args_list
6106 Performs the default fixup of the arguments part of an
6107 "entersub" op tree. This consists of applying list context to
6108 each of the argument ops. This is the standard treatment used
6109 on a call marked with "&", or a method call, or a call through
6110 a subroutine reference, or any other call where the callee
6111 can't be identified at compile time, or a call where the callee
6112 has no prototype.
6113
6114 OP* ck_entersub_args_list(OP *entersubop)
6115
6116 ck_entersub_args_proto
6117 Performs the fixup of the arguments part of an "entersub" op
6118 tree based on a subroutine prototype. This makes various
6119 modifications to the argument ops, from applying context up to
6120 inserting "refgen" ops, and checking the number and syntactic
6121 types of arguments, as directed by the prototype. This is the
6122 standard treatment used on a subroutine call, not marked with
6123 "&", where the callee can be identified at compile time and has
6124 a prototype.
6125
6126 "protosv" supplies the subroutine prototype to be applied to
6127 the call. It may be a normal defined scalar, of which the
6128 string value will be used. Alternatively, for convenience, it
6129 may be a subroutine object (a "CV*" that has been cast to
6130 "SV*") which has a prototype. The prototype supplied, in
6131 whichever form, does not need to match the actual callee
6132 referenced by the op tree.
6133
6134 If the argument ops disagree with the prototype, for example by
6135 having an unacceptable number of arguments, a valid op tree is
6136 returned anyway. The error is reflected in the parser state,
6137 normally resulting in a single exception at the top level of
6138 parsing which covers all the compilation errors that occurred.
6139 In the error message, the callee is referred to by the name
6140 defined by the "namegv" parameter.
6141
6142 OP* ck_entersub_args_proto(OP *entersubop,
6143 GV *namegv, SV *protosv)
6144
6145 ck_entersub_args_proto_or_list
6146 Performs the fixup of the arguments part of an "entersub" op
6147 tree either based on a subroutine prototype or using default
6148 list-context processing. This is the standard treatment used
6149 on a subroutine call, not marked with "&", where the callee can
6150 be identified at compile time.
6151
6152 "protosv" supplies the subroutine prototype to be applied to
6153 the call, or indicates that there is no prototype. It may be a
6154 normal scalar, in which case if it is defined then the string
6155 value will be used as a prototype, and if it is undefined then
6156 there is no prototype. Alternatively, for convenience, it may
6157 be a subroutine object (a "CV*" that has been cast to "SV*"),
6158 of which the prototype will be used if it has one. The
6159 prototype (or lack thereof) supplied, in whichever form, does
6160 not need to match the actual callee referenced by the op tree.
6161
6162 If the argument ops disagree with the prototype, for example by
6163 having an unacceptable number of arguments, a valid op tree is
6164 returned anyway. The error is reflected in the parser state,
6165 normally resulting in a single exception at the top level of
6166 parsing which covers all the compilation errors that occurred.
6167 In the error message, the callee is referred to by the name
6168 defined by the "namegv" parameter.
6169
6170 OP* ck_entersub_args_proto_or_list(OP *entersubop,
6171 GV *namegv,
6172 SV *protosv)
6173
6174 cv_const_sv
6175 If "cv" is a constant sub eligible for inlining, returns the
6176 constant value returned by the sub. Otherwise, returns "NULL".
6177
6178 Constant subs can be created with "newCONSTSUB" or as described
6179 in "Constant Functions" in perlsub.
6180
6181 SV* cv_const_sv(const CV *const cv)
6182
6183 cv_get_call_checker
6184 The original form of "cv_get_call_checker_flags", which does
6185 not return checker flags. When using a checker function
6186 returned by this function, it is only safe to call it with a
6187 genuine GV as its "namegv" argument.
6188
6189 void cv_get_call_checker(CV *cv,
6190 Perl_call_checker *ckfun_p,
6191 SV **ckobj_p)
6192
6193 cv_get_call_checker_flags
6194 Retrieves the function that will be used to fix up a call to
6195 "cv". Specifically, the function is applied to an "entersub"
6196 op tree for a subroutine call, not marked with "&", where the
6197 callee can be identified at compile time as "cv".
6198
6199 The C-level function pointer is returned in *ckfun_p, an SV
6200 argument for it is returned in *ckobj_p, and control flags are
6201 returned in *ckflags_p. The function is intended to be called
6202 in this manner:
6203
6204 entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
6205
6206 In this call, "entersubop" is a pointer to the "entersub" op,
6207 which may be replaced by the check function, and "namegv"
6208 supplies the name that should be used by the check function to
6209 refer to the callee of the "entersub" op if it needs to emit
6210 any diagnostics. It is permitted to apply the check function
6211 in non-standard situations, such as to a call to a different
6212 subroutine or to a method call.
6213
6214 "namegv" may not actually be a GV. If the
6215 "CALL_CHECKER_REQUIRE_GV" bit is clear in *ckflags_p, it is
6216 permitted to pass a CV or other SV instead, anything that can
6217 be used as the first argument to "cv_name". If the
6218 "CALL_CHECKER_REQUIRE_GV" bit is set in *ckflags_p then the
6219 check function requires "namegv" to be a genuine GV.
6220
6221 By default, the check function is
6222 Perl_ck_entersub_args_proto_or_list, the SV parameter is "cv"
6223 itself, and the "CALL_CHECKER_REQUIRE_GV" flag is clear. This
6224 implements standard prototype processing. It can be changed,
6225 for a particular subroutine, by "cv_set_call_checker_flags".
6226
6227 If the "CALL_CHECKER_REQUIRE_GV" bit is set in "gflags" then it
6228 indicates that the caller only knows about the genuine GV
6229 version of "namegv", and accordingly the corresponding bit will
6230 always be set in *ckflags_p, regardless of the check function's
6231 recorded requirements. If the "CALL_CHECKER_REQUIRE_GV" bit is
6232 clear in "gflags" then it indicates the caller knows about the
6233 possibility of passing something other than a GV as "namegv",
6234 and accordingly the corresponding bit may be either set or
6235 clear in *ckflags_p, indicating the check function's recorded
6236 requirements.
6237
6238 "gflags" is a bitset passed into "cv_get_call_checker_flags",
6239 in which only the "CALL_CHECKER_REQUIRE_GV" bit currently has a
6240 defined meaning (for which see above). All other bits should
6241 be clear.
6242
6243 void cv_get_call_checker_flags(
6244 CV *cv, U32 gflags,
6245 Perl_call_checker *ckfun_p, SV **ckobj_p,
6246 U32 *ckflags_p
6247 )
6248
6249 cv_set_call_checker
6250 The original form of "cv_set_call_checker_flags", which passes
6251 it the "CALL_CHECKER_REQUIRE_GV" flag for backward-
6252 compatibility. The effect of that flag setting is that the
6253 check function is guaranteed to get a genuine GV as its
6254 "namegv" argument.
6255
6256 void cv_set_call_checker(CV *cv,
6257 Perl_call_checker ckfun,
6258 SV *ckobj)
6259
6260 cv_set_call_checker_flags
6261 Sets the function that will be used to fix up a call to "cv".
6262 Specifically, the function is applied to an "entersub" op tree
6263 for a subroutine call, not marked with "&", where the callee
6264 can be identified at compile time as "cv".
6265
6266 The C-level function pointer is supplied in "ckfun", an SV
6267 argument for it is supplied in "ckobj", and control flags are
6268 supplied in "ckflags". The function should be defined like
6269 this:
6270
6271 STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
6272
6273 It is intended to be called in this manner:
6274
6275 entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
6276
6277 In this call, "entersubop" is a pointer to the "entersub" op,
6278 which may be replaced by the check function, and "namegv"
6279 supplies the name that should be used by the check function to
6280 refer to the callee of the "entersub" op if it needs to emit
6281 any diagnostics. It is permitted to apply the check function
6282 in non-standard situations, such as to a call to a different
6283 subroutine or to a method call.
6284
6285 "namegv" may not actually be a GV. For efficiency, perl may
6286 pass a CV or other SV instead. Whatever is passed can be used
6287 as the first argument to "cv_name". You can force perl to pass
6288 a GV by including "CALL_CHECKER_REQUIRE_GV" in the "ckflags".
6289
6290 "ckflags" is a bitset, in which only the
6291 "CALL_CHECKER_REQUIRE_GV" bit currently has a defined meaning
6292 (for which see above). All other bits should be clear.
6293
6294 The current setting for a particular CV can be retrieved by
6295 "cv_get_call_checker_flags".
6296
6297 void cv_set_call_checker_flags(
6298 CV *cv, Perl_call_checker ckfun, SV *ckobj,
6299 U32 ckflags
6300 )
6301
6302 LINKLIST
6303 Given the root of an optree, link the tree in execution order
6304 using the "op_next" pointers and return the first op executed.
6305 If this has already been done, it will not be redone, and
6306 "o->op_next" will be returned. If "o->op_next" is not already
6307 set, "o" should be at least an "UNOP".
6308
6309 OP* LINKLIST(OP *o)
6310
6311 newCONSTSUB
6312 Behaves like "newCONSTSUB_flags", except that "name" is nul-
6313 terminated rather than of counted length, and no flags are set.
6314 (This means that "name" is always interpreted as Latin-1.)
6315
6316 CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
6317
6318 newCONSTSUB_flags
6319 Construct a constant subroutine, also performing some
6320 surrounding jobs. A scalar constant-valued subroutine is
6321 eligible for inlining at compile-time, and in Perl code can be
6322 created by "sub FOO () { 123 }". Other kinds of constant
6323 subroutine have other treatment.
6324
6325 The subroutine will have an empty prototype and will ignore any
6326 arguments when called. Its constant behaviour is determined by
6327 "sv". If "sv" is null, the subroutine will yield an empty
6328 list. If "sv" points to a scalar, the subroutine will always
6329 yield that scalar. If "sv" points to an array, the subroutine
6330 will always yield a list of the elements of that array in list
6331 context, or the number of elements in the array in scalar
6332 context. This function takes ownership of one counted
6333 reference to the scalar or array, and will arrange for the
6334 object to live as long as the subroutine does. If "sv" points
6335 to a scalar then the inlining assumes that the value of the
6336 scalar will never change, so the caller must ensure that the
6337 scalar is not subsequently written to. If "sv" points to an
6338 array then no such assumption is made, so it is ostensibly safe
6339 to mutate the array or its elements, but whether this is really
6340 supported has not been determined.
6341
6342 The subroutine will have "CvFILE" set according to "PL_curcop".
6343 Other aspects of the subroutine will be left in their default
6344 state. The caller is free to mutate the subroutine beyond its
6345 initial state after this function has returned.
6346
6347 If "name" is null then the subroutine will be anonymous, with
6348 its "CvGV" referring to an "__ANON__" glob. If "name" is non-
6349 null then the subroutine will be named accordingly, referenced
6350 by the appropriate glob. "name" is a string of length "len"
6351 bytes giving a sigilless symbol name, in UTF-8 if "flags" has
6352 the "SVf_UTF8" bit set and in Latin-1 otherwise. The name may
6353 be either qualified or unqualified. If the name is unqualified
6354 then it defaults to being in the stash specified by "stash" if
6355 that is non-null, or to "PL_curstash" if "stash" is null. The
6356 symbol is always added to the stash if necessary, with
6357 "GV_ADDMULTI" semantics.
6358
6359 "flags" should not have bits set other than "SVf_UTF8".
6360
6361 If there is already a subroutine of the specified name, then
6362 the new sub will replace the existing one in the glob. A
6363 warning may be generated about the redefinition.
6364
6365 If the subroutine has one of a few special names, such as
6366 "BEGIN" or "END", then it will be claimed by the appropriate
6367 queue for automatic running of phase-related subroutines. In
6368 this case the relevant glob will be left not containing any
6369 subroutine, even if it did contain one before. Execution of
6370 the subroutine will likely be a no-op, unless "sv" was a tied
6371 array or the caller modified the subroutine in some interesting
6372 way before it was executed. In the case of "BEGIN", the
6373 treatment is buggy: the sub will be executed when only half
6374 built, and may be deleted prematurely, possibly causing a
6375 crash.
6376
6377 The function returns a pointer to the constructed subroutine.
6378 If the sub is anonymous then ownership of one counted reference
6379 to the subroutine is transferred to the caller. If the sub is
6380 named then the caller does not get ownership of a reference.
6381 In most such cases, where the sub has a non-phase name, the sub
6382 will be alive at the point it is returned by virtue of being
6383 contained in the glob that names it. A phase-named subroutine
6384 will usually be alive by virtue of the reference owned by the
6385 phase's automatic run queue. A "BEGIN" subroutine may have
6386 been destroyed already by the time this function returns, but
6387 currently bugs occur in that case before the caller gets
6388 control. It is the caller's responsibility to ensure that it
6389 knows which of these situations applies.
6390
6391 CV* newCONSTSUB_flags(HV* stash, const char* name,
6392 STRLEN len, U32 flags, SV* sv)
6393
6394 newXS Used by "xsubpp" to hook up XSUBs as Perl subs. "filename"
6395 needs to be static storage, as it is used directly as CvFILE(),
6396 without a copy being made.
6397
6398 op_append_elem
6399 Append an item to the list of ops contained directly within a
6400 list-type op, returning the lengthened list. "first" is the
6401 list-type op, and "last" is the op to append to the list.
6402 "optype" specifies the intended opcode for the list. If
6403 "first" is not already a list of the right type, it will be
6404 upgraded into one. If either "first" or "last" is null, the
6405 other is returned unchanged.
6406
6407 OP* op_append_elem(I32 optype, OP* first, OP* last)
6408
6409 op_append_list
6410 Concatenate the lists of ops contained directly within two
6411 list-type ops, returning the combined list. "first" and "last"
6412 are the list-type ops to concatenate. "optype" specifies the
6413 intended opcode for the list. If either "first" or "last" is
6414 not already a list of the right type, it will be upgraded into
6415 one. If either "first" or "last" is null, the other is
6416 returned unchanged.
6417
6418 OP* op_append_list(I32 optype, OP* first, OP* last)
6419
6420 OP_CLASS
6421 Return the class of the provided OP: that is, which of the *OP
6422 structures it uses. For core ops this currently gets the
6423 information out of "PL_opargs", which does not always
6424 accurately reflect the type used; in v5.26 onwards, see also
6425 the function "op_class" which can do a better job of
6426 determining the used type.
6427
6428 For custom ops the type is returned from the registration, and
6429 it is up to the registree to ensure it is accurate. The value
6430 returned will be one of the "OA_"* constants from op.h.
6431
6432 U32 OP_CLASS(OP *o)
6433
6434 op_contextualize
6435 Applies a syntactic context to an op tree representing an
6436 expression. "o" is the op tree, and "context" must be
6437 "G_SCALAR", "G_ARRAY", or "G_VOID" to specify the context to
6438 apply. The modified op tree is returned.
6439
6440 OP* op_contextualize(OP* o, I32 context)
6441
6442 op_convert_list
6443 Converts "o" into a list op if it is not one already, and then
6444 converts it into the specified "type", calling its check
6445 function, allocating a target if it needs one, and folding
6446 constants.
6447
6448 A list-type op is usually constructed one kid at a time via
6449 "newLISTOP", "op_prepend_elem" and "op_append_elem". Then
6450 finally it is passed to "op_convert_list" to make it the right
6451 type.
6452
6453 OP* op_convert_list(I32 optype, I32 flags, OP* o)
6454
6455 OP_DESC Return a short description of the provided OP.
6456
6457 const char * OP_DESC(OP *o)
6458
6459 op_free Free an op and its children. Only use this when an op is no
6460 longer linked to from any optree.
6461
6462 void op_free(OP* arg)
6463
6464 OpHAS_SIBLING
6465 Returns true if "o" has a sibling
6466
6467 bool OpHAS_SIBLING(OP *o)
6468
6469 OpLASTSIB_set
6470 Marks "o" as having no further siblings and marks o as having
6471 the specified parent. See also "OpMORESIB_set" and
6472 "OpMAYBESIB_set". For a higher-level interface, see
6473 "op_sibling_splice".
6474
6475 void OpLASTSIB_set(OP *o, OP *parent)
6476
6477 op_linklist
6478 This function is the implementation of the "LINKLIST" macro.
6479 It should not be called directly.
6480
6481 OP* op_linklist(OP *o)
6482
6483 op_lvalue
6484 NOTE: this function is experimental and may change or be
6485 removed without notice.
6486
6487 Propagate lvalue ("modifiable") context to an op and its
6488 children. "type" represents the context type, roughly based on
6489 the type of op that would do the modifying, although "local()"
6490 is represented by "OP_NULL", because it has no op type of its
6491 own (it is signalled by a flag on the lvalue op).
6492
6493 This function detects things that can't be modified, such as
6494 "$x+1", and generates errors for them. For example, "$x+1 = 2"
6495 would cause it to be called with an op of type "OP_ADD" and a
6496 "type" argument of "OP_SASSIGN".
6497
6498 It also flags things that need to behave specially in an lvalue
6499 context, such as "$$x = 5" which might have to vivify a
6500 reference in $x.
6501
6502 OP* op_lvalue(OP* o, I32 type)
6503
6504 OpMAYBESIB_set
6505 Conditionally does "OpMORESIB_set" or "OpLASTSIB_set" depending
6506 on whether "sib" is non-null. For a higher-level interface, see
6507 "op_sibling_splice".
6508
6509 void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
6510
6511 OpMORESIB_set
6512 Sets the sibling of "o" to the non-zero value "sib". See also
6513 "OpLASTSIB_set" and "OpMAYBESIB_set". For a higher-level
6514 interface, see "op_sibling_splice".
6515
6516 void OpMORESIB_set(OP *o, OP *sib)
6517
6518 OP_NAME Return the name of the provided OP. For core ops this looks up
6519 the name from the op_type; for custom ops from the op_ppaddr.
6520
6521 const char * OP_NAME(OP *o)
6522
6523 op_null Neutralizes an op when it is no longer needed, but is still
6524 linked to from other ops.
6525
6526 void op_null(OP* o)
6527
6528 op_parent
6529 Returns the parent OP of "o", if it has a parent. Returns
6530 "NULL" otherwise.
6531
6532 OP* op_parent(OP *o)
6533
6534 op_prepend_elem
6535 Prepend an item to the list of ops contained directly within a
6536 list-type op, returning the lengthened list. "first" is the op
6537 to prepend to the list, and "last" is the list-type op.
6538 "optype" specifies the intended opcode for the list. If "last"
6539 is not already a list of the right type, it will be upgraded
6540 into one. If either "first" or "last" is null, the other is
6541 returned unchanged.
6542
6543 OP* op_prepend_elem(I32 optype, OP* first, OP* last)
6544
6545 op_scope
6546 NOTE: this function is experimental and may change or be
6547 removed without notice.
6548
6549 Wraps up an op tree with some additional ops so that at runtime
6550 a dynamic scope will be created. The original ops run in the
6551 new dynamic scope, and then, provided that they exit normally,
6552 the scope will be unwound. The additional ops used to create
6553 and unwind the dynamic scope will normally be an
6554 "enter"/"leave" pair, but a "scope" op may be used instead if
6555 the ops are simple enough to not need the full dynamic scope
6556 structure.
6557
6558 OP* op_scope(OP* o)
6559
6560 OpSIBLING
6561 Returns the sibling of "o", or "NULL" if there is no sibling
6562
6563 OP* OpSIBLING(OP *o)
6564
6565 op_sibling_splice
6566 A general function for editing the structure of an existing
6567 chain of op_sibling nodes. By analogy with the perl-level
6568 "splice()" function, allows you to delete zero or more
6569 sequential nodes, replacing them with zero or more different
6570 nodes. Performs the necessary op_first/op_last housekeeping on
6571 the parent node and op_sibling manipulation on the children.
6572 The last deleted node will be marked as the last node by
6573 updating the op_sibling/op_sibparent or op_moresib field as
6574 appropriate.
6575
6576 Note that op_next is not manipulated, and nodes are not freed;
6577 that is the responsibility of the caller. It also won't create
6578 a new list op for an empty list etc; use higher-level functions
6579 like op_append_elem() for that.
6580
6581 "parent" is the parent node of the sibling chain. It may passed
6582 as "NULL" if the splicing doesn't affect the first or last op
6583 in the chain.
6584
6585 "start" is the node preceding the first node to be spliced.
6586 Node(s) following it will be deleted, and ops will be inserted
6587 after it. If it is "NULL", the first node onwards is deleted,
6588 and nodes are inserted at the beginning.
6589
6590 "del_count" is the number of nodes to delete. If zero, no
6591 nodes are deleted. If -1 or greater than or equal to the
6592 number of remaining kids, all remaining kids are deleted.
6593
6594 "insert" is the first of a chain of nodes to be inserted in
6595 place of the nodes. If "NULL", no nodes are inserted.
6596
6597 The head of the chain of deleted ops is returned, or "NULL" if
6598 no ops were deleted.
6599
6600 For example:
6601
6602 action before after returns
6603 ------ ----- ----- -------
6604
6605 P P
6606 splice(P, A, 2, X-Y-Z) | | B-C
6607 A-B-C-D A-X-Y-Z-D
6608
6609 P P
6610 splice(P, NULL, 1, X-Y) | | A
6611 A-B-C-D X-Y-B-C-D
6612
6613 P P
6614 splice(P, NULL, 3, NULL) | | A-B-C
6615 A-B-C-D D
6616
6617 P P
6618 splice(P, B, 0, X-Y) | | NULL
6619 A-B-C-D A-B-X-Y-C-D
6620
6621 For lower-level direct manipulation of "op_sibparent" and
6622 "op_moresib", see "OpMORESIB_set", "OpLASTSIB_set",
6623 "OpMAYBESIB_set".
6624
6625 OP* op_sibling_splice(OP *parent, OP *start,
6626 int del_count, OP* insert)
6627
6628 OP_TYPE_IS
6629 Returns true if the given OP is not a "NULL" pointer and if it
6630 is of the given type.
6631
6632 The negation of this macro, "OP_TYPE_ISNT" is also available as
6633 well as "OP_TYPE_IS_NN" and "OP_TYPE_ISNT_NN" which elide the
6634 NULL pointer check.
6635
6636 bool OP_TYPE_IS(OP *o, Optype type)
6637
6638 OP_TYPE_IS_OR_WAS
6639 Returns true if the given OP is not a NULL pointer and if it is
6640 of the given type or used to be before being replaced by an OP
6641 of type OP_NULL.
6642
6643 The negation of this macro, "OP_TYPE_ISNT_AND_WASNT" is also
6644 available as well as "OP_TYPE_IS_OR_WAS_NN" and
6645 "OP_TYPE_ISNT_AND_WASNT_NN" which elide the "NULL" pointer
6646 check.
6647
6648 bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
6649
6650 rv2cv_op_cv
6651 Examines an op, which is expected to identify a subroutine at
6652 runtime, and attempts to determine at compile time which
6653 subroutine it identifies. This is normally used during Perl
6654 compilation to determine whether a prototype can be applied to
6655 a function call. "cvop" is the op being considered, normally
6656 an "rv2cv" op. A pointer to the identified subroutine is
6657 returned, if it could be determined statically, and a null
6658 pointer is returned if it was not possible to determine
6659 statically.
6660
6661 Currently, the subroutine can be identified statically if the
6662 RV that the "rv2cv" is to operate on is provided by a suitable
6663 "gv" or "const" op. A "gv" op is suitable if the GV's CV slot
6664 is populated. A "const" op is suitable if the constant value
6665 must be an RV pointing to a CV. Details of this process may
6666 change in future versions of Perl. If the "rv2cv" op has the
6667 "OPpENTERSUB_AMPER" flag set then no attempt is made to
6668 identify the subroutine statically: this flag is used to
6669 suppress compile-time magic on a subroutine call, forcing it to
6670 use default runtime behaviour.
6671
6672 If "flags" has the bit "RV2CVOPCV_MARK_EARLY" set, then the
6673 handling of a GV reference is modified. If a GV was examined
6674 and its CV slot was found to be empty, then the "gv" op has the
6675 "OPpEARLY_CV" flag set. If the op is not optimised away, and
6676 the CV slot is later populated with a subroutine having a
6677 prototype, that flag eventually triggers the warning "called
6678 too early to check prototype".
6679
6680 If "flags" has the bit "RV2CVOPCV_RETURN_NAME_GV" set, then
6681 instead of returning a pointer to the subroutine it returns a
6682 pointer to the GV giving the most appropriate name for the
6683 subroutine in this context. Normally this is just the "CvGV"
6684 of the subroutine, but for an anonymous ("CvANON") subroutine
6685 that is referenced through a GV it will be the referencing GV.
6686 The resulting "GV*" is cast to "CV*" to be returned. A null
6687 pointer is returned as usual if there is no statically-
6688 determinable subroutine.
6689
6690 CV* rv2cv_op_cv(OP *cvop, U32 flags)
6691
6693 packlist
6694 The engine implementing "pack()" Perl function.
6695
6696 void packlist(SV *cat, const char *pat,
6697 const char *patend, SV **beglist,
6698 SV **endlist)
6699
6700 unpackstring
6701 The engine implementing the "unpack()" Perl function.
6702
6703 Using the template "pat..patend", this function unpacks the
6704 string "s..strend" into a number of mortal SVs, which it pushes
6705 onto the perl argument (@_) stack (so you will need to issue a
6706 "PUTBACK" before and "SPAGAIN" after the call to this
6707 function). It returns the number of pushed elements.
6708
6709 The "strend" and "patend" pointers should point to the byte
6710 following the last character of each string.
6711
6712 Although this function returns its values on the perl argument
6713 stack, it doesn't take any parameters from that stack (and thus
6714 in particular there's no need to do a "PUSHMARK" before calling
6715 it, unlike "call_pv" for example).
6716
6717 SSize_t unpackstring(const char *pat,
6718 const char *patend, const char *s,
6719 const char *strend, U32 flags)
6720
6722 CvPADLIST
6723 NOTE: this function is experimental and may change or be
6724 removed without notice.
6725
6726 CV's can have CvPADLIST(cv) set to point to a PADLIST. This is
6727 the CV's scratchpad, which stores lexical variables and opcode
6728 temporary and per-thread values.
6729
6730 For these purposes "formats" are a kind-of CV; eval""s are too
6731 (except they're not callable at will and are always thrown away
6732 after the eval"" is done executing). Require'd files are
6733 simply evals without any outer lexical scope.
6734
6735 XSUBs do not have a "CvPADLIST". "dXSTARG" fetches values from
6736 "PL_curpad", but that is really the callers pad (a slot of
6737 which is allocated by every entersub). Do not get or set
6738 "CvPADLIST" if a CV is an XSUB (as determined by "CvISXSUB()"),
6739 "CvPADLIST" slot is reused for a different internal purpose in
6740 XSUBs.
6741
6742 The PADLIST has a C array where pads are stored.
6743
6744 The 0th entry of the PADLIST is a PADNAMELIST which represents
6745 the "names" or rather the "static type information" for
6746 lexicals. The individual elements of a PADNAMELIST are
6747 PADNAMEs. Future refactorings might stop the PADNAMELIST from
6748 being stored in the PADLIST's array, so don't rely on it. See
6749 "PadlistNAMES".
6750
6751 The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the
6752 stack frame at that depth of recursion into the CV. The 0th
6753 slot of a frame AV is an AV which is @_. Other entries are
6754 storage for variables and op targets.
6755
6756 Iterating over the PADNAMELIST iterates over all possible pad
6757 items. Pad slots for targets ("SVs_PADTMP") and GVs end up
6758 having &PL_padname_undef "names", while slots for constants
6759 have &PL_padname_const "names" (see "pad_alloc"). That
6760 &PL_padname_undef and &PL_padname_const are used is an
6761 implementation detail subject to change. To test for them, use
6762 "!PadnamePV(name)" and "PadnamePV(name) && !PadnameLEN(name)",
6763 respectively.
6764
6765 Only "my"/"our" variable slots get valid names. The rest are
6766 op targets/GVs/constants which are statically allocated or
6767 resolved at compile time. These don't have names by which they
6768 can be looked up from Perl code at run time through eval"" the
6769 way "my"/"our" variables can be. Since they can't be looked up
6770 by "name" but only by their index allocated at compile time
6771 (which is usually in "PL_op->op_targ"), wasting a name SV for
6772 them doesn't make sense.
6773
6774 The pad names in the PADNAMELIST have their PV holding the name
6775 of the variable. The "COP_SEQ_RANGE_LOW" and "_HIGH" fields
6776 form a range (low+1..high inclusive) of cop_seq numbers for
6777 which the name is valid. During compilation, these fields may
6778 hold the special value PERL_PADSEQ_INTRO to indicate various
6779 stages:
6780
6781 COP_SEQ_RANGE_LOW _HIGH
6782 ----------------- -----
6783 PERL_PADSEQ_INTRO 0 variable not yet introduced:
6784 { my ($x
6785 valid-seq# PERL_PADSEQ_INTRO variable in scope:
6786 { my ($x);
6787 valid-seq# valid-seq# compilation of scope complete:
6788 { my ($x); .... }
6789
6790 When a lexical var hasn't yet been introduced, it already
6791 exists from the perspective of duplicate declarations, but not
6792 for variable lookups, e.g.
6793
6794 my ($x, $x); # '"my" variable $x masks earlier declaration'
6795 my $x = $x; # equal to my $x = $::x;
6796
6797 For typed lexicals "PadnameTYPE" points at the type stash. For
6798 "our" lexicals, "PadnameOURSTASH" points at the stash of the
6799 associated global (so that duplicate "our" declarations in the
6800 same package can be detected). "PadnameGEN" is sometimes used
6801 to store the generation number during compilation.
6802
6803 If "PadnameOUTER" is set on the pad name, then that slot in the
6804 frame AV is a REFCNT'ed reference to a lexical from "outside".
6805 Such entries are sometimes referred to as 'fake'. In this
6806 case, the name does not use 'low' and 'high' to store a cop_seq
6807 range, since it is in scope throughout. Instead 'high' stores
6808 some flags containing info about the real lexical (is it
6809 declared in an anon, and is it capable of being instantiated
6810 multiple times?), and for fake ANONs, 'low' contains the index
6811 within the parent's pad where the lexical's value is stored, to
6812 make cloning quicker.
6813
6814 If the 'name' is "&" the corresponding entry in the PAD is a CV
6815 representing a possible closure.
6816
6817 Note that formats are treated as anon subs, and are cloned each
6818 time write is called (if necessary).
6819
6820 The flag "SVs_PADSTALE" is cleared on lexicals each time the
6821 "my()" is executed, and set on scope exit. This allows the
6822 "Variable $x is not available" warning to be generated in
6823 evals, such as
6824
6825 { my $x = 1; sub f { eval '$x'} } f();
6826
6827 For state vars, "SVs_PADSTALE" is overloaded to mean 'not yet
6828 initialised', but this internal state is stored in a separate
6829 pad entry.
6830
6831 PADLIST * CvPADLIST(CV *cv)
6832
6833 pad_add_name_pvs
6834 Exactly like "pad_add_name_pvn", but takes a literal string
6835 instead of a string/length pair.
6836
6837 PADOFFSET pad_add_name_pvs("name", U32 flags,
6838 HV *typestash, HV *ourstash)
6839
6840 PadARRAY
6841 NOTE: this function is experimental and may change or be
6842 removed without notice.
6843
6844 The C array of pad entries.
6845
6846 SV ** PadARRAY(PAD * pad)
6847
6848 pad_findmy_pvs
6849 Exactly like "pad_findmy_pvn", but takes a literal string
6850 instead of a string/length pair.
6851
6852 PADOFFSET pad_findmy_pvs("name", U32 flags)
6853
6854 PadlistARRAY
6855 NOTE: this function is experimental and may change or be
6856 removed without notice.
6857
6858 The C array of a padlist, containing the pads. Only subscript
6859 it with numbers >= 1, as the 0th entry is not guaranteed to
6860 remain usable.
6861
6862 PAD ** PadlistARRAY(PADLIST * padlist)
6863
6864 PadlistMAX
6865 NOTE: this function is experimental and may change or be
6866 removed without notice.
6867
6868 The index of the last allocated space in the padlist. Note
6869 that the last pad may be in an earlier slot. Any entries
6870 following it will be "NULL" in that case.
6871
6872 SSize_t PadlistMAX(PADLIST * padlist)
6873
6874 PadlistNAMES
6875 NOTE: this function is experimental and may change or be
6876 removed without notice.
6877
6878 The names associated with pad entries.
6879
6880 PADNAMELIST * PadlistNAMES(PADLIST * padlist)
6881
6882 PadlistNAMESARRAY
6883 NOTE: this function is experimental and may change or be
6884 removed without notice.
6885
6886 The C array of pad names.
6887
6888 PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
6889
6890 PadlistNAMESMAX
6891 NOTE: this function is experimental and may change or be
6892 removed without notice.
6893
6894 The index of the last pad name.
6895
6896 SSize_t PadlistNAMESMAX(PADLIST * padlist)
6897
6898 PadlistREFCNT
6899 NOTE: this function is experimental and may change or be
6900 removed without notice.
6901
6902 The reference count of the padlist. Currently this is always
6903 1.
6904
6905 U32 PadlistREFCNT(PADLIST * padlist)
6906
6907 PadMAX NOTE: this function is experimental and may change or be
6908 removed without notice.
6909
6910 The index of the last pad entry.
6911
6912 SSize_t PadMAX(PAD * pad)
6913
6914 PadnameLEN
6915 NOTE: this function is experimental and may change or be
6916 removed without notice.
6917
6918 The length of the name.
6919
6920 STRLEN PadnameLEN(PADNAME * pn)
6921
6922 PadnamelistARRAY
6923 NOTE: this function is experimental and may change or be
6924 removed without notice.
6925
6926 The C array of pad names.
6927
6928 PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
6929
6930 PadnamelistMAX
6931 NOTE: this function is experimental and may change or be
6932 removed without notice.
6933
6934 The index of the last pad name.
6935
6936 SSize_t PadnamelistMAX(PADNAMELIST * pnl)
6937
6938 PadnamelistREFCNT
6939 NOTE: this function is experimental and may change or be
6940 removed without notice.
6941
6942 The reference count of the pad name list.
6943
6944 SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
6945
6946 PadnamelistREFCNT_dec
6947 NOTE: this function is experimental and may change or be
6948 removed without notice.
6949
6950 Lowers the reference count of the pad name list.
6951
6952 void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
6953
6954 PadnamePV
6955 NOTE: this function is experimental and may change or be
6956 removed without notice.
6957
6958 The name stored in the pad name struct. This returns "NULL"
6959 for a target slot.
6960
6961 char * PadnamePV(PADNAME * pn)
6962
6963 PadnameREFCNT
6964 NOTE: this function is experimental and may change or be
6965 removed without notice.
6966
6967 The reference count of the pad name.
6968
6969 SSize_t PadnameREFCNT(PADNAME * pn)
6970
6971 PadnameREFCNT_dec
6972 NOTE: this function is experimental and may change or be
6973 removed without notice.
6974
6975 Lowers the reference count of the pad name.
6976
6977 void PadnameREFCNT_dec(PADNAME * pn)
6978
6979 PadnameSV
6980 NOTE: this function is experimental and may change or be
6981 removed without notice.
6982
6983 Returns the pad name as a mortal SV.
6984
6985 SV * PadnameSV(PADNAME * pn)
6986
6987 PadnameUTF8
6988 NOTE: this function is experimental and may change or be
6989 removed without notice.
6990
6991 Whether PadnamePV is in UTF-8. Currently, this is always true.
6992
6993 bool PadnameUTF8(PADNAME * pn)
6994
6995 pad_new Create a new padlist, updating the global variables for the
6996 currently-compiling padlist to point to the new padlist. The
6997 following flags can be OR'ed together:
6998
6999 padnew_CLONE this pad is for a cloned CV
7000 padnew_SAVE save old globals on the save stack
7001 padnew_SAVESUB also save extra stuff for start of sub
7002
7003 PADLIST* pad_new(int flags)
7004
7005 PL_comppad
7006 NOTE: this function is experimental and may change or be
7007 removed without notice.
7008
7009 During compilation, this points to the array containing the
7010 values part of the pad for the currently-compiling code. (At
7011 runtime a CV may have many such value arrays; at compile time
7012 just one is constructed.) At runtime, this points to the array
7013 containing the currently-relevant values for the pad for the
7014 currently-executing code.
7015
7016 PL_comppad_name
7017 NOTE: this function is experimental and may change or be
7018 removed without notice.
7019
7020 During compilation, this points to the array containing the
7021 names part of the pad for the currently-compiling code.
7022
7023 PL_curpad
7024 NOTE: this function is experimental and may change or be
7025 removed without notice.
7026
7027 Points directly to the body of the "PL_comppad" array. (I.e.,
7028 this is "PadARRAY(PL_comppad)".)
7029
7031 PL_curcop
7032 The currently active COP (control op) roughly representing the
7033 current statement in the source.
7034
7035 COP* PL_curcop
7036
7037 PL_curstash
7038 The stash for the package code will be compiled into.
7039
7040 HV* PL_curstash
7041
7042 PL_defgv
7043 The GV representing *_. Useful for access to $_.
7044
7045 GV * PL_defgv
7046
7047 PL_exit_flags
7048 Contains flags controlling perl's behaviour on exit():
7049
7050 · "PERL_EXIT_DESTRUCT_END"
7051
7052 If set, END blocks are executed when the interpreter is
7053 destroyed. This is normally set by perl itself after the
7054 interpreter is constructed.
7055
7056 · "PERL_EXIT_ABORT"
7057
7058 Call "abort()" on exit. This is used internally by perl
7059 itself to abort if exit is called while processing exit.
7060
7061 · "PERL_EXIT_WARN"
7062
7063 Warn on exit.
7064
7065 · "PERL_EXIT_EXPECTED"
7066
7067 Set by the "exit" in perlfunc operator.
7068
7069 U8 PL_exit_flags
7070
7071 PL_modglobal
7072 "PL_modglobal" is a general purpose, interpreter global HV for
7073 use by extensions that need to keep information on a per-
7074 interpreter basis. In a pinch, it can also be used as a symbol
7075 table for extensions to share data among each other. It is a
7076 good idea to use keys prefixed by the package name of the
7077 extension that owns the data.
7078
7079 HV* PL_modglobal
7080
7081 PL_na A convenience variable which is typically used with "SvPV" when
7082 one doesn't care about the length of the string. It is usually
7083 more efficient to either declare a local variable and use that
7084 instead or to use the "SvPV_nolen" macro.
7085
7086 STRLEN PL_na
7087
7088 PL_opfreehook
7089 When non-"NULL", the function pointed by this variable will be
7090 called each time an OP is freed with the corresponding OP as
7091 the argument. This allows extensions to free any extra
7092 attribute they have locally attached to an OP. It is also
7093 assured to first fire for the parent OP and then for its kids.
7094
7095 When you replace this variable, it is considered a good
7096 practice to store the possibly previously installed hook and
7097 that you recall it inside your own.
7098
7099 Perl_ophook_t PL_opfreehook
7100
7101 PL_peepp
7102 Pointer to the per-subroutine peephole optimiser. This is a
7103 function that gets called at the end of compilation of a Perl
7104 subroutine (or equivalently independent piece of Perl code) to
7105 perform fixups of some ops and to perform small-scale
7106 optimisations. The function is called once for each subroutine
7107 that is compiled, and is passed, as sole parameter, a pointer
7108 to the op that is the entry point to the subroutine. It
7109 modifies the op tree in place.
7110
7111 The peephole optimiser should never be completely replaced.
7112 Rather, add code to it by wrapping the existing optimiser. The
7113 basic way to do this can be seen in "Compile pass 3: peephole
7114 optimization" in perlguts. If the new code wishes to operate
7115 on ops throughout the subroutine's structure, rather than just
7116 at the top level, it is likely to be more convenient to wrap
7117 the "PL_rpeepp" hook.
7118
7119 peep_t PL_peepp
7120
7121 PL_perl_destruct_level
7122 This value may be set when embedding for full cleanup.
7123
7124 Possible values:
7125
7126 · 0 - none
7127
7128 · 1 - full
7129
7130 · 2 or greater - full with checks.
7131
7132 If $ENV{PERL_DESTRUCT_LEVEL} is set to an integer greater than
7133 the value of "PL_perl_destruct_level" its value is used
7134 instead.
7135
7136 signed char PL_perl_destruct_level
7137
7138 PL_rpeepp
7139 Pointer to the recursive peephole optimiser. This is a
7140 function that gets called at the end of compilation of a Perl
7141 subroutine (or equivalently independent piece of Perl code) to
7142 perform fixups of some ops and to perform small-scale
7143 optimisations. The function is called once for each chain of
7144 ops linked through their "op_next" fields; it is recursively
7145 called to handle each side chain. It is passed, as sole
7146 parameter, a pointer to the op that is at the head of the
7147 chain. It modifies the op tree in place.
7148
7149 The peephole optimiser should never be completely replaced.
7150 Rather, add code to it by wrapping the existing optimiser. The
7151 basic way to do this can be seen in "Compile pass 3: peephole
7152 optimization" in perlguts. If the new code wishes to operate
7153 only on ops at a subroutine's top level, rather than throughout
7154 the structure, it is likely to be more convenient to wrap the
7155 "PL_peepp" hook.
7156
7157 peep_t PL_rpeepp
7158
7159 PL_runops
7160 See "Pluggable runops" in perlguts.
7161
7162 runops_proc_t PL_runops
7163
7164 PL_sv_no
7165 This is the "false" SV. See "PL_sv_yes". Always refer to this
7166 as &PL_sv_no.
7167
7168 SV PL_sv_no
7169
7170 PL_sv_undef
7171 This is the "undef" SV. Always refer to this as &PL_sv_undef.
7172
7173 SV PL_sv_undef
7174
7175 PL_sv_yes
7176 This is the "true" SV. See "PL_sv_no". Always refer to this
7177 as &PL_sv_yes.
7178
7179 SV PL_sv_yes
7180
7181 PL_sv_zero
7182 This readonly SV has a zero numeric value and a "0" string
7183 value. It's similar to "PL_sv_no" except for its string value.
7184 Can be used as a cheap alternative to mXPUSHi(0) for example.
7185 Always refer to this as &PL_sv_zero. Introduced in 5.28.
7186
7187 SV PL_sv_zero
7188
7190 SvRX Convenience macro to get the REGEXP from a SV. This is
7191 approximately equivalent to the following snippet:
7192
7193 if (SvMAGICAL(sv))
7194 mg_get(sv);
7195 if (SvROK(sv))
7196 sv = MUTABLE_SV(SvRV(sv));
7197 if (SvTYPE(sv) == SVt_REGEXP)
7198 return (REGEXP*) sv;
7199
7200 "NULL" will be returned if a REGEXP* is not found.
7201
7202 REGEXP * SvRX(SV *sv)
7203
7204 SvRXOK Returns a boolean indicating whether the SV (or the one it
7205 references) is a REGEXP.
7206
7207 If you want to do something with the REGEXP* later use SvRX
7208 instead and check for NULL.
7209
7210 bool SvRXOK(SV* sv)
7211
7213 dMARK Declare a stack marker variable, "mark", for the XSUB. See
7214 "MARK" and "dORIGMARK".
7215
7216 dMARK;
7217
7218 dORIGMARK
7219 Saves the original stack mark for the XSUB. See "ORIGMARK".
7220
7221 dORIGMARK;
7222
7223 dSP Declares a local copy of perl's stack pointer for the XSUB,
7224 available via the "SP" macro. See "SP".
7225
7226 dSP;
7227
7228 EXTEND Used to extend the argument stack for an XSUB's return values.
7229 Once used, guarantees that there is room for at least "nitems"
7230 to be pushed onto the stack.
7231
7232 void EXTEND(SP, SSize_t nitems)
7233
7234 MARK Stack marker variable for the XSUB. See "dMARK".
7235
7236 mPUSHi Push an integer onto the stack. The stack must have room for
7237 this element. Does not use "TARG". See also "PUSHi",
7238 "mXPUSHi" and "XPUSHi".
7239
7240 void mPUSHi(IV iv)
7241
7242 mPUSHn Push a double onto the stack. The stack must have room for
7243 this element. Does not use "TARG". See also "PUSHn",
7244 "mXPUSHn" and "XPUSHn".
7245
7246 void mPUSHn(NV nv)
7247
7248 mPUSHp Push a string onto the stack. The stack must have room for
7249 this element. The "len" indicates the length of the string.
7250 Does not use "TARG". See also "PUSHp", "mXPUSHp" and "XPUSHp".
7251
7252 void mPUSHp(char* str, STRLEN len)
7253
7254 mPUSHs Push an SV onto the stack and mortalizes the SV. The stack
7255 must have room for this element. Does not use "TARG". See
7256 also "PUSHs" and "mXPUSHs".
7257
7258 void mPUSHs(SV* sv)
7259
7260 mPUSHu Push an unsigned integer onto the stack. The stack must have
7261 room for this element. Does not use "TARG". See also "PUSHu",
7262 "mXPUSHu" and "XPUSHu".
7263
7264 void mPUSHu(UV uv)
7265
7266 mXPUSHi Push an integer onto the stack, extending the stack if
7267 necessary. Does not use "TARG". See also "XPUSHi", "mPUSHi"
7268 and "PUSHi".
7269
7270 void mXPUSHi(IV iv)
7271
7272 mXPUSHn Push a double onto the stack, extending the stack if necessary.
7273 Does not use "TARG". See also "XPUSHn", "mPUSHn" and "PUSHn".
7274
7275 void mXPUSHn(NV nv)
7276
7277 mXPUSHp Push a string onto the stack, extending the stack if necessary.
7278 The "len" indicates the length of the string. Does not use
7279 "TARG". See also "XPUSHp", "mPUSHp" and "PUSHp".
7280
7281 void mXPUSHp(char* str, STRLEN len)
7282
7283 mXPUSHs Push an SV onto the stack, extending the stack if necessary and
7284 mortalizes the SV. Does not use "TARG". See also "XPUSHs" and
7285 "mPUSHs".
7286
7287 void mXPUSHs(SV* sv)
7288
7289 mXPUSHu Push an unsigned integer onto the stack, extending the stack if
7290 necessary. Does not use "TARG". See also "XPUSHu", "mPUSHu"
7291 and "PUSHu".
7292
7293 void mXPUSHu(UV uv)
7294
7295 ORIGMARK
7296 The original stack mark for the XSUB. See "dORIGMARK".
7297
7298 POPi Pops an integer off the stack.
7299
7300 IV POPi
7301
7302 POPl Pops a long off the stack.
7303
7304 long POPl
7305
7306 POPn Pops a double off the stack.
7307
7308 NV POPn
7309
7310 POPp Pops a string off the stack.
7311
7312 char* POPp
7313
7314 POPpbytex
7315 Pops a string off the stack which must consist of bytes i.e.
7316 characters < 256.
7317
7318 char* POPpbytex
7319
7320 POPpx Pops a string off the stack. Identical to POPp. There are two
7321 names for historical reasons.
7322
7323 char* POPpx
7324
7325 POPs Pops an SV off the stack.
7326
7327 SV* POPs
7328
7329 POPu Pops an unsigned integer off the stack.
7330
7331 UV POPu
7332
7333 POPul Pops an unsigned long off the stack.
7334
7335 long POPul
7336
7337 PUSHi Push an integer onto the stack. The stack must have room for
7338 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
7339 or "dXSTARG" should be called to declare it. Do not call
7340 multiple "TARG"-oriented macros to return lists from XSUB's -
7341 see "mPUSHi" instead. See also "XPUSHi" and "mXPUSHi".
7342
7343 void PUSHi(IV iv)
7344
7345 PUSHMARK
7346 Opening bracket for arguments on a callback. See "PUTBACK" and
7347 perlcall.
7348
7349 void PUSHMARK(SP)
7350
7351 PUSHmortal
7352 Push a new mortal SV onto the stack. The stack must have room
7353 for this element. Does not use "TARG". See also "PUSHs",
7354 "XPUSHmortal" and "XPUSHs".
7355
7356 void PUSHmortal
7357
7358 PUSHn Push a double onto the stack. The stack must have room for
7359 this element. Handles 'set' magic. Uses "TARG", so "dTARGET"
7360 or "dXSTARG" should be called to declare it. Do not call
7361 multiple "TARG"-oriented macros to return lists from XSUB's -
7362 see "mPUSHn" instead. See also "XPUSHn" and "mXPUSHn".
7363
7364 void PUSHn(NV nv)
7365
7366 PUSHp Push a string onto the stack. The stack must have room for
7367 this element. The "len" indicates the length of the string.
7368 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
7369 should be called to declare it. Do not call multiple
7370 "TARG"-oriented macros to return lists from XSUB's - see
7371 "mPUSHp" instead. See also "XPUSHp" and "mXPUSHp".
7372
7373 void PUSHp(char* str, STRLEN len)
7374
7375 PUSHs Push an SV onto the stack. The stack must have room for this
7376 element. Does not handle 'set' magic. Does not use "TARG".
7377 See also "PUSHmortal", "XPUSHs", and "XPUSHmortal".
7378
7379 void PUSHs(SV* sv)
7380
7381 PUSHu Push an unsigned integer onto the stack. The stack must have
7382 room for this element. Handles 'set' magic. Uses "TARG", so
7383 "dTARGET" or "dXSTARG" should be called to declare it. Do not
7384 call multiple "TARG"-oriented macros to return lists from
7385 XSUB's - see "mPUSHu" instead. See also "XPUSHu" and
7386 "mXPUSHu".
7387
7388 void PUSHu(UV uv)
7389
7390 PUTBACK Closing bracket for XSUB arguments. This is usually handled by
7391 "xsubpp". See "PUSHMARK" and perlcall for other uses.
7392
7393 PUTBACK;
7394
7395 SP Stack pointer. This is usually handled by "xsubpp". See "dSP"
7396 and "SPAGAIN".
7397
7398 SPAGAIN Refetch the stack pointer. Used after a callback. See
7399 perlcall.
7400
7401 SPAGAIN;
7402
7403 XPUSHi Push an integer onto the stack, extending the stack if
7404 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
7405 "dXSTARG" should be called to declare it. Do not call multiple
7406 "TARG"-oriented macros to return lists from XSUB's - see
7407 "mXPUSHi" instead. See also "PUSHi" and "mPUSHi".
7408
7409 void XPUSHi(IV iv)
7410
7411 XPUSHmortal
7412 Push a new mortal SV onto the stack, extending the stack if
7413 necessary. Does not use "TARG". See also "XPUSHs",
7414 "PUSHmortal" and "PUSHs".
7415
7416 void XPUSHmortal
7417
7418 XPUSHn Push a double onto the stack, extending the stack if necessary.
7419 Handles 'set' magic. Uses "TARG", so "dTARGET" or "dXSTARG"
7420 should be called to declare it. Do not call multiple
7421 "TARG"-oriented macros to return lists from XSUB's - see
7422 "mXPUSHn" instead. See also "PUSHn" and "mPUSHn".
7423
7424 void XPUSHn(NV nv)
7425
7426 XPUSHp Push a string onto the stack, extending the stack if necessary.
7427 The "len" indicates the length of the string. Handles 'set'
7428 magic. Uses "TARG", so "dTARGET" or "dXSTARG" should be called
7429 to declare it. Do not call multiple "TARG"-oriented macros to
7430 return lists from XSUB's - see "mXPUSHp" instead. See also
7431 "PUSHp" and "mPUSHp".
7432
7433 void XPUSHp(char* str, STRLEN len)
7434
7435 XPUSHs Push an SV onto the stack, extending the stack if necessary.
7436 Does not handle 'set' magic. Does not use "TARG". See also
7437 "XPUSHmortal", "PUSHs" and "PUSHmortal".
7438
7439 void XPUSHs(SV* sv)
7440
7441 XPUSHu Push an unsigned integer onto the stack, extending the stack if
7442 necessary. Handles 'set' magic. Uses "TARG", so "dTARGET" or
7443 "dXSTARG" should be called to declare it. Do not call multiple
7444 "TARG"-oriented macros to return lists from XSUB's - see
7445 "mXPUSHu" instead. See also "PUSHu" and "mPUSHu".
7446
7447 void XPUSHu(UV uv)
7448
7449 XSRETURN
7450 Return from XSUB, indicating number of items on the stack.
7451 This is usually handled by "xsubpp".
7452
7453 void XSRETURN(int nitems)
7454
7455 XSRETURN_EMPTY
7456 Return an empty list from an XSUB immediately.
7457
7458 XSRETURN_EMPTY;
7459
7460 XSRETURN_IV
7461 Return an integer from an XSUB immediately. Uses "XST_mIV".
7462
7463 void XSRETURN_IV(IV iv)
7464
7465 XSRETURN_NO
7466 Return &PL_sv_no from an XSUB immediately. Uses "XST_mNO".
7467
7468 XSRETURN_NO;
7469
7470 XSRETURN_NV
7471 Return a double from an XSUB immediately. Uses "XST_mNV".
7472
7473 void XSRETURN_NV(NV nv)
7474
7475 XSRETURN_PV
7476 Return a copy of a string from an XSUB immediately. Uses
7477 "XST_mPV".
7478
7479 void XSRETURN_PV(char* str)
7480
7481 XSRETURN_UNDEF
7482 Return &PL_sv_undef from an XSUB immediately. Uses
7483 "XST_mUNDEF".
7484
7485 XSRETURN_UNDEF;
7486
7487 XSRETURN_UV
7488 Return an integer from an XSUB immediately. Uses "XST_mUV".
7489
7490 void XSRETURN_UV(IV uv)
7491
7492 XSRETURN_YES
7493 Return &PL_sv_yes from an XSUB immediately. Uses "XST_mYES".
7494
7495 XSRETURN_YES;
7496
7497 XST_mIV Place an integer into the specified position "pos" on the
7498 stack. The value is stored in a new mortal SV.
7499
7500 void XST_mIV(int pos, IV iv)
7501
7502 XST_mNO Place &PL_sv_no into the specified position "pos" on the stack.
7503
7504 void XST_mNO(int pos)
7505
7506 XST_mNV Place a double into the specified position "pos" on the stack.
7507 The value is stored in a new mortal SV.
7508
7509 void XST_mNV(int pos, NV nv)
7510
7511 XST_mPV Place a copy of a string into the specified position "pos" on
7512 the stack. The value is stored in a new mortal SV.
7513
7514 void XST_mPV(int pos, char* str)
7515
7516 XST_mUNDEF
7517 Place &PL_sv_undef into the specified position "pos" on the
7518 stack.
7519
7520 void XST_mUNDEF(int pos)
7521
7522 XST_mUV Place an unsigned integer into the specified position "pos" on
7523 the stack. The value is stored in a new mortal SV.
7524
7525 void XST_mUV(int pos, UV uv)
7526
7527 XST_mYES
7528 Place &PL_sv_yes into the specified position "pos" on the
7529 stack.
7530
7531 void XST_mYES(int pos)
7532
7534 SVt_IV Type flag for scalars. See "svtype".
7535
7536 SVt_NULL
7537 Type flag for scalars. See "svtype".
7538
7539 SVt_NV Type flag for scalars. See "svtype".
7540
7541 SVt_PV Type flag for scalars. See "svtype".
7542
7543 SVt_PVAV
7544 Type flag for arrays. See "svtype".
7545
7546 SVt_PVCV
7547 Type flag for subroutines. See "svtype".
7548
7549 SVt_PVFM
7550 Type flag for formats. See "svtype".
7551
7552 SVt_PVGV
7553 Type flag for typeglobs. See "svtype".
7554
7555 SVt_PVHV
7556 Type flag for hashes. See "svtype".
7557
7558 SVt_PVIO
7559 Type flag for I/O objects. See "svtype".
7560
7561 SVt_PVIV
7562 Type flag for scalars. See "svtype".
7563
7564 SVt_PVLV
7565 Type flag for scalars. See "svtype".
7566
7567 SVt_PVMG
7568 Type flag for scalars. See "svtype".
7569
7570 SVt_PVNV
7571 Type flag for scalars. See "svtype".
7572
7573 SVt_REGEXP
7574 Type flag for regular expressions. See "svtype".
7575
7576 svtype An enum of flags for Perl types. These are found in the file
7577 sv.h in the "svtype" enum. Test these flags with the "SvTYPE"
7578 macro.
7579
7580 The types are:
7581
7582 SVt_NULL
7583 SVt_IV
7584 SVt_NV
7585 SVt_RV
7586 SVt_PV
7587 SVt_PVIV
7588 SVt_PVNV
7589 SVt_PVMG
7590 SVt_INVLIST
7591 SVt_REGEXP
7592 SVt_PVGV
7593 SVt_PVLV
7594 SVt_PVAV
7595 SVt_PVHV
7596 SVt_PVCV
7597 SVt_PVFM
7598 SVt_PVIO
7599
7600 These are most easily explained from the bottom up.
7601
7602 "SVt_PVIO" is for I/O objects, "SVt_PVFM" for formats,
7603 "SVt_PVCV" for subroutines, "SVt_PVHV" for hashes and
7604 "SVt_PVAV" for arrays.
7605
7606 All the others are scalar types, that is, things that can be
7607 bound to a "$" variable. For these, the internal types are
7608 mostly orthogonal to types in the Perl language.
7609
7610 Hence, checking "SvTYPE(sv) < SVt_PVAV" is the best way to see
7611 whether something is a scalar.
7612
7613 "SVt_PVGV" represents a typeglob. If "!SvFAKE(sv)", then it is
7614 a real, incoercible typeglob. If "SvFAKE(sv)", then it is a
7615 scalar to which a typeglob has been assigned. Assigning to it
7616 again will stop it from being a typeglob. "SVt_PVLV"
7617 represents a scalar that delegates to another scalar behind the
7618 scenes. It is used, e.g., for the return value of "substr" and
7619 for tied hash and array elements. It can hold any scalar
7620 value, including a typeglob. "SVt_REGEXP" is for regular
7621 expressions. "SVt_INVLIST" is for Perl core internal use only.
7622
7623 "SVt_PVMG" represents a "normal" scalar (not a typeglob,
7624 regular expression, or delegate). Since most scalars do not
7625 need all the internal fields of a PVMG, we save memory by
7626 allocating smaller structs when possible. All the other types
7627 are just simpler forms of "SVt_PVMG", with fewer internal
7628 fields. "SVt_NULL" can only hold undef. "SVt_IV" can hold
7629 undef, an integer, or a reference. ("SVt_RV" is an alias for
7630 "SVt_IV", which exists for backward compatibility.) "SVt_NV"
7631 can hold any of those or a double. "SVt_PV" can only hold
7632 "undef" or a string. "SVt_PVIV" is a superset of "SVt_PV" and
7633 "SVt_IV". "SVt_PVNV" is similar. "SVt_PVMG" can hold anything
7634 "SVt_PVNV" can hold, but it can, but does not have to, be
7635 blessed or magical.
7636
7638 boolSV Returns a true SV if "b" is a true value, or a false SV if "b"
7639 is 0.
7640
7641 See also "PL_sv_yes" and "PL_sv_no".
7642
7643 SV * boolSV(bool b)
7644
7645 croak_xs_usage
7646 A specialised variant of "croak()" for emitting the usage
7647 message for xsubs
7648
7649 croak_xs_usage(cv, "eee_yow");
7650
7651 works out the package name and subroutine name from "cv", and
7652 then calls "croak()". Hence if "cv" is &ouch::awk, it would
7653 call "croak" as:
7654
7655 Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
7656 "eee_yow");
7657
7658 void croak_xs_usage(const CV *const cv,
7659 const char *const params)
7660
7661 get_sv Returns the SV of the specified Perl scalar. "flags" are
7662 passed to "gv_fetchpv". If "GV_ADD" is set and the Perl
7663 variable does not exist then it will be created. If "flags" is
7664 zero and the variable does not exist then NULL is returned.
7665
7666 NOTE: the perl_ form of this function is deprecated.
7667
7668 SV* get_sv(const char *name, I32 flags)
7669
7670 looks_like_number
7671 Test if the content of an SV looks like a number (or is a
7672 number). "Inf" and "Infinity" are treated as numbers (so will
7673 not issue a non-numeric warning), even if your "atof()" doesn't
7674 grok them. Get-magic is ignored.
7675
7676 I32 looks_like_number(SV *const sv)
7677
7678 newRV_inc
7679 Creates an RV wrapper for an SV. The reference count for the
7680 original SV is incremented.
7681
7682 SV* newRV_inc(SV* sv)
7683
7684 newRV_noinc
7685 Creates an RV wrapper for an SV. The reference count for the
7686 original SV is not incremented.
7687
7688 SV* newRV_noinc(SV *const tmpRef)
7689
7690 newSV Creates a new SV. A non-zero "len" parameter indicates the
7691 number of bytes of preallocated string space the SV should
7692 have. An extra byte for a trailing "NUL" is also reserved.
7693 ("SvPOK" is not set for the SV even if string space is
7694 allocated.) The reference count for the new SV is set to 1.
7695
7696 In 5.9.3, "newSV()" replaces the older "NEWSV()" API, and drops
7697 the first parameter, x, a debug aid which allowed callers to
7698 identify themselves. This aid has been superseded by a new
7699 build option, "PERL_MEM_LOG" (see "PERL_MEM_LOG" in
7700 perlhacktips). The older API is still there for use in XS
7701 modules supporting older perls.
7702
7703 SV* newSV(const STRLEN len)
7704
7705 newSVhek
7706 Creates a new SV from the hash key structure. It will generate
7707 scalars that point to the shared string table where possible.
7708 Returns a new (undefined) SV if "hek" is NULL.
7709
7710 SV* newSVhek(const HEK *const hek)
7711
7712 newSViv Creates a new SV and copies an integer into it. The reference
7713 count for the SV is set to 1.
7714
7715 SV* newSViv(const IV i)
7716
7717 newSVnv Creates a new SV and copies a floating point value into it.
7718 The reference count for the SV is set to 1.
7719
7720 SV* newSVnv(const NV n)
7721
7722 newSVpadname
7723 NOTE: this function is experimental and may change or be
7724 removed without notice.
7725
7726 Creates a new SV containing the pad name.
7727
7728 SV* newSVpadname(PADNAME *pn)
7729
7730 newSVpv Creates a new SV and copies a string (which may contain "NUL"
7731 ("\0") characters) into it. The reference count for the SV is
7732 set to 1. If "len" is zero, Perl will compute the length using
7733 "strlen()", (which means if you use this option, that "s" can't
7734 have embedded "NUL" characters and has to have a terminating
7735 "NUL" byte).
7736
7737 This function can cause reliability issues if you are likely to
7738 pass in empty strings that are not null terminated, because it
7739 will run strlen on the string and potentially run past valid
7740 memory.
7741
7742 Using "newSVpvn" is a safer alternative for non "NUL"
7743 terminated strings. For string literals use "newSVpvs"
7744 instead. This function will work fine for "NUL" terminated
7745 strings, but if you want to avoid the if statement on whether
7746 to call "strlen" use "newSVpvn" instead (calling "strlen"
7747 yourself).
7748
7749 SV* newSVpv(const char *const s, const STRLEN len)
7750
7751 newSVpvf
7752 Creates a new SV and initializes it with the string formatted
7753 like "sv_catpvf".
7754
7755 SV* newSVpvf(const char *const pat, ...)
7756
7757 newSVpvn
7758 Creates a new SV and copies a string into it, which may contain
7759 "NUL" characters ("\0") and other binary data. The reference
7760 count for the SV is set to 1. Note that if "len" is zero, Perl
7761 will create a zero length (Perl) string. You are responsible
7762 for ensuring that the source buffer is at least "len" bytes
7763 long. If the "buffer" argument is NULL the new SV will be
7764 undefined.
7765
7766 SV* newSVpvn(const char *const buffer,
7767 const STRLEN len)
7768
7769 newSVpvn_flags
7770 Creates a new SV and copies a string (which may contain "NUL"
7771 ("\0") characters) into it. The reference count for the SV is
7772 set to 1. Note that if "len" is zero, Perl will create a zero
7773 length string. You are responsible for ensuring that the
7774 source string is at least "len" bytes long. If the "s"
7775 argument is NULL the new SV will be undefined. Currently the
7776 only flag bits accepted are "SVf_UTF8" and "SVs_TEMP". If
7777 "SVs_TEMP" is set, then "sv_2mortal()" is called on the result
7778 before returning. If "SVf_UTF8" is set, "s" is considered to
7779 be in UTF-8 and the "SVf_UTF8" flag will be set on the new SV.
7780 "newSVpvn_utf8()" is a convenience wrapper for this function,
7781 defined as
7782
7783 #define newSVpvn_utf8(s, len, u) \
7784 newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
7785
7786 SV* newSVpvn_flags(const char *const s,
7787 const STRLEN len,
7788 const U32 flags)
7789
7790 newSVpvn_share
7791 Creates a new SV with its "SvPVX_const" pointing to a shared
7792 string in the string table. If the string does not already
7793 exist in the table, it is created first. Turns on the
7794 "SvIsCOW" flag (or "READONLY" and "FAKE" in 5.16 and earlier).
7795 If the "hash" parameter is non-zero, that value is used;
7796 otherwise the hash is computed. The string's hash can later be
7797 retrieved from the SV with the "SvSHARED_HASH()" macro. The
7798 idea here is that as the string table is used for shared hash
7799 keys these strings will have "SvPVX_const == HeKEY" and hash
7800 lookup will avoid string compare.
7801
7802 SV* newSVpvn_share(const char* s, I32 len, U32 hash)
7803
7804 newSVpvn_utf8
7805 Creates a new SV and copies a string (which may contain "NUL"
7806 ("\0") characters) into it. If "utf8" is true, calls
7807 "SvUTF8_on" on the new SV. Implemented as a wrapper around
7808 "newSVpvn_flags".
7809
7810 SV* newSVpvn_utf8(const char* s, STRLEN len,
7811 U32 utf8)
7812
7813 newSVpvs
7814 Like "newSVpvn", but takes a literal string instead of a
7815 string/length pair.
7816
7817 SV* newSVpvs("literal string")
7818
7819 newSVpvs_flags
7820 Like "newSVpvn_flags", but takes a literal string instead of a
7821 string/length pair.
7822
7823 SV* newSVpvs_flags("literal string", U32 flags)
7824
7825 newSVpv_share
7826 Like "newSVpvn_share", but takes a "NUL"-terminated string
7827 instead of a string/length pair.
7828
7829 SV* newSVpv_share(const char* s, U32 hash)
7830
7831 newSVpvs_share
7832 Like "newSVpvn_share", but takes a literal string instead of a
7833 string/length pair and omits the hash parameter.
7834
7835 SV* newSVpvs_share("literal string")
7836
7837 newSVrv Creates a new SV for the existing RV, "rv", to point to. If
7838 "rv" is not an RV then it will be upgraded to one. If
7839 "classname" is non-null then the new SV will be blessed in the
7840 specified package. The new SV is returned and its reference
7841 count is 1. The reference count 1 is owned by "rv". See also
7842 newRV_inc() and newRV_noinc() for creating a new RV properly.
7843
7844 SV* newSVrv(SV *const rv,
7845 const char *const classname)
7846
7847 newSVsv Creates a new SV which is an exact duplicate of the original
7848 SV. (Uses "sv_setsv".)
7849
7850 SV* newSVsv(SV *const old)
7851
7852 newSVsv_nomg
7853 Like "newSVsv" but does not process get magic.
7854
7855 SV* newSVsv_nomg(SV *const old)
7856
7857 newSV_type
7858 Creates a new SV, of the type specified. The reference count
7859 for the new SV is set to 1.
7860
7861 SV* newSV_type(const svtype type)
7862
7863 newSVuv Creates a new SV and copies an unsigned integer into it. The
7864 reference count for the SV is set to 1.
7865
7866 SV* newSVuv(const UV u)
7867
7868 sortsv_flags
7869 In-place sort an array of SV pointers with the given comparison
7870 routine, with various SORTf_* flag options.
7871
7872 void sortsv_flags(SV** array, size_t num_elts,
7873 SVCOMPARE_t cmp, U32 flags)
7874
7875 sv_2bool
7876 This macro is only used by "sv_true()" or its macro equivalent,
7877 and only if the latter's argument is neither "SvPOK", "SvIOK"
7878 nor "SvNOK". It calls "sv_2bool_flags" with the "SV_GMAGIC"
7879 flag.
7880
7881 bool sv_2bool(SV *const sv)
7882
7883 sv_2bool_flags
7884 This function is only used by "sv_true()" and friends, and
7885 only if the latter's argument is neither "SvPOK", "SvIOK" nor
7886 "SvNOK". If the flags contain "SV_GMAGIC", then it does an
7887 "mg_get()" first.
7888
7889 bool sv_2bool_flags(SV *sv, I32 flags)
7890
7891 sv_2cv Using various gambits, try to get a CV from an SV; in addition,
7892 try if possible to set *st and *gvp to the stash and GV
7893 associated with it. The flags in "lref" are passed to
7894 "gv_fetchsv".
7895
7896 CV* sv_2cv(SV* sv, HV **const st, GV **const gvp,
7897 const I32 lref)
7898
7899 sv_2io Using various gambits, try to get an IO from an SV: the IO slot
7900 if its a GV; or the recursive result if we're an RV; or the IO
7901 slot of the symbol named after the PV if we're a string.
7902
7903 'Get' magic is ignored on the "sv" passed in, but will be
7904 called on "SvRV(sv)" if "sv" is an RV.
7905
7906 IO* sv_2io(SV *const sv)
7907
7908 sv_2iv_flags
7909 Return the integer value of an SV, doing any necessary string
7910 conversion. If "flags" has the "SV_GMAGIC" bit set, does an
7911 "mg_get()" first. Normally used via the "SvIV(sv)" and
7912 "SvIVx(sv)" macros.
7913
7914 IV sv_2iv_flags(SV *const sv, const I32 flags)
7915
7916 sv_2mortal
7917 Marks an existing SV as mortal. The SV will be destroyed
7918 "soon", either by an explicit call to "FREETMPS", or by an
7919 implicit call at places such as statement boundaries.
7920 "SvTEMP()" is turned on which means that the SV's string buffer
7921 can be "stolen" if this SV is copied. See also "sv_newmortal"
7922 and "sv_mortalcopy".
7923
7924 SV* sv_2mortal(SV *const sv)
7925
7926 sv_2nv_flags
7927 Return the num value of an SV, doing any necessary string or
7928 integer conversion. If "flags" has the "SV_GMAGIC" bit set,
7929 does an "mg_get()" first. Normally used via the "SvNV(sv)" and
7930 "SvNVx(sv)" macros.
7931
7932 NV sv_2nv_flags(SV *const sv, const I32 flags)
7933
7934 sv_2pvbyte
7935 Return a pointer to the byte-encoded representation of the SV,
7936 and set *lp to its length. If the SV is marked as being
7937 encoded as UTF-8, it will downgrade it to a byte string as a
7938 side-effect, if possible. If the SV cannot be downgraded, this
7939 croaks.
7940
7941 Usually accessed via the "SvPVbyte" macro.
7942
7943 char* sv_2pvbyte(SV *sv, STRLEN *const lp)
7944
7945 sv_2pvutf8
7946 Return a pointer to the UTF-8-encoded representation of the SV,
7947 and set *lp to its length. May cause the SV to be upgraded to
7948 UTF-8 as a side-effect.
7949
7950 Usually accessed via the "SvPVutf8" macro.
7951
7952 char* sv_2pvutf8(SV *sv, STRLEN *const lp)
7953
7954 sv_2pv_flags
7955 Returns a pointer to the string value of an SV, and sets *lp to
7956 its length. If flags has the "SV_GMAGIC" bit set, does an
7957 "mg_get()" first. Coerces "sv" to a string if necessary.
7958 Normally invoked via the "SvPV_flags" macro. "sv_2pv()" and
7959 "sv_2pv_nomg" usually end up here too.
7960
7961 char* sv_2pv_flags(SV *const sv, STRLEN *const lp,
7962 const I32 flags)
7963
7964 sv_2uv_flags
7965 Return the unsigned integer value of an SV, doing any necessary
7966 string conversion. If "flags" has the "SV_GMAGIC" bit set,
7967 does an "mg_get()" first. Normally used via the "SvUV(sv)" and
7968 "SvUVx(sv)" macros.
7969
7970 UV sv_2uv_flags(SV *const sv, const I32 flags)
7971
7972 sv_backoff
7973 Remove any string offset. You should normally use the
7974 "SvOOK_off" macro wrapper instead.
7975
7976 void sv_backoff(SV *const sv)
7977
7978 sv_bless
7979 Blesses an SV into a specified package. The SV must be an RV.
7980 The package must be designated by its stash (see "gv_stashpv").
7981 The reference count of the SV is unaffected.
7982
7983 SV* sv_bless(SV *const sv, HV *const stash)
7984
7985 sv_catpv
7986 Concatenates the "NUL"-terminated string onto the end of the
7987 string which is in the SV. If the SV has the UTF-8 status set,
7988 then the bytes appended should be valid UTF-8. Handles 'get'
7989 magic, but not 'set' magic. See "sv_catpv_mg".
7990
7991 void sv_catpv(SV *const sv, const char* ptr)
7992
7993 sv_catpvf
7994 Processes its arguments like "sprintf", and appends the
7995 formatted output to an SV. As with "sv_vcatpvfn" called with a
7996 non-null C-style variable argument list, argument reordering is
7997 not supported. If the appended data contains "wide" characters
7998 (including, but not limited to, SVs with a UTF-8 PV formatted
7999 with %s, and characters >255 formatted with %c), the original
8000 SV might get upgraded to UTF-8. Handles 'get' magic, but not
8001 'set' magic. See "sv_catpvf_mg". If the original SV was
8002 UTF-8, the pattern should be valid UTF-8; if the original SV
8003 was bytes, the pattern should be too.
8004
8005 void sv_catpvf(SV *const sv, const char *const pat,
8006 ...)
8007
8008 sv_catpvf_mg
8009 Like "sv_catpvf", but also handles 'set' magic.
8010
8011 void sv_catpvf_mg(SV *const sv,
8012 const char *const pat, ...)
8013
8014 sv_catpvn
8015 Concatenates the string onto the end of the string which is in
8016 the SV. "len" indicates number of bytes to copy. If the SV
8017 has the UTF-8 status set, then the bytes appended should be
8018 valid UTF-8. Handles 'get' magic, but not 'set' magic. See
8019 "sv_catpvn_mg".
8020
8021 void sv_catpvn(SV *dsv, const char *sstr, STRLEN len)
8022
8023 sv_catpvn_flags
8024 Concatenates the string onto the end of the string which is in
8025 the SV. The "len" indicates number of bytes to copy.
8026
8027 By default, the string appended is assumed to be valid UTF-8 if
8028 the SV has the UTF-8 status set, and a string of bytes
8029 otherwise. One can force the appended string to be interpreted
8030 as UTF-8 by supplying the "SV_CATUTF8" flag, and as bytes by
8031 supplying the "SV_CATBYTES" flag; the SV or the string appended
8032 will be upgraded to UTF-8 if necessary.
8033
8034 If "flags" has the "SV_SMAGIC" bit set, will "mg_set" on "dsv"
8035 afterwards if appropriate. "sv_catpvn" and "sv_catpvn_nomg"
8036 are implemented in terms of this function.
8037
8038 void sv_catpvn_flags(SV *const dstr,
8039 const char *sstr,
8040 const STRLEN len,
8041 const I32 flags)
8042
8043 sv_catpvn_nomg
8044 Like "sv_catpvn" but doesn't process magic.
8045
8046 void sv_catpvn_nomg(SV* sv, const char* ptr,
8047 STRLEN len)
8048
8049 sv_catpvs
8050 Like "sv_catpvn", but takes a literal string instead of a
8051 string/length pair.
8052
8053 void sv_catpvs(SV* sv, "literal string")
8054
8055 sv_catpvs_flags
8056 Like "sv_catpvn_flags", but takes a literal string instead of a
8057 string/length pair.
8058
8059 void sv_catpvs_flags(SV* sv, "literal string",
8060 I32 flags)
8061
8062 sv_catpvs_mg
8063 Like "sv_catpvn_mg", but takes a literal string instead of a
8064 string/length pair.
8065
8066 void sv_catpvs_mg(SV* sv, "literal string")
8067
8068 sv_catpvs_nomg
8069 Like "sv_catpvn_nomg", but takes a literal string instead of a
8070 string/length pair.
8071
8072 void sv_catpvs_nomg(SV* sv, "literal string")
8073
8074 sv_catpv_flags
8075 Concatenates the "NUL"-terminated string onto the end of the
8076 string which is in the SV. If the SV has the UTF-8 status set,
8077 then the bytes appended should be valid UTF-8. If "flags" has
8078 the "SV_SMAGIC" bit set, will "mg_set" on the modified SV if
8079 appropriate.
8080
8081 void sv_catpv_flags(SV *dstr, const char *sstr,
8082 const I32 flags)
8083
8084 sv_catpv_mg
8085 Like "sv_catpv", but also handles 'set' magic.
8086
8087 void sv_catpv_mg(SV *const sv, const char *const ptr)
8088
8089 sv_catpv_nomg
8090 Like "sv_catpv" but doesn't process magic.
8091
8092 void sv_catpv_nomg(SV* sv, const char* ptr)
8093
8094 sv_catsv
8095 Concatenates the string from SV "ssv" onto the end of the
8096 string in SV "dsv". If "ssv" is null, does nothing; otherwise
8097 modifies only "dsv". Handles 'get' magic on both SVs, but no
8098 'set' magic. See "sv_catsv_mg" and "sv_catsv_nomg".
8099
8100 void sv_catsv(SV *dstr, SV *sstr)
8101
8102 sv_catsv_flags
8103 Concatenates the string from SV "ssv" onto the end of the
8104 string in SV "dsv". If "ssv" is null, does nothing; otherwise
8105 modifies only "dsv". If "flags" has the "SV_GMAGIC" bit set,
8106 will call "mg_get" on both SVs if appropriate. If "flags" has
8107 the "SV_SMAGIC" bit set, "mg_set" will be called on the
8108 modified SV afterward, if appropriate. "sv_catsv",
8109 "sv_catsv_nomg", and "sv_catsv_mg" are implemented in terms of
8110 this function.
8111
8112 void sv_catsv_flags(SV *const dsv, SV *const ssv,
8113 const I32 flags)
8114
8115 sv_catsv_nomg
8116 Like "sv_catsv" but doesn't process magic.
8117
8118 void sv_catsv_nomg(SV* dsv, SV* ssv)
8119
8120 sv_chop Efficient removal of characters from the beginning of the
8121 string buffer. "SvPOK(sv)", or at least "SvPOKp(sv)", must be
8122 true and "ptr" must be a pointer to somewhere inside the string
8123 buffer. "ptr" becomes the first character of the adjusted
8124 string. Uses the "OOK" hack. On return, only "SvPOK(sv)" and
8125 "SvPOKp(sv)" among the "OK" flags will be true.
8126
8127 Beware: after this function returns, "ptr" and SvPVX_const(sv)
8128 may no longer refer to the same chunk of data.
8129
8130 The unfortunate similarity of this function's name to that of
8131 Perl's "chop" operator is strictly coincidental. This function
8132 works from the left; "chop" works from the right.
8133
8134 void sv_chop(SV *const sv, const char *const ptr)
8135
8136 sv_clear
8137 Clear an SV: call any destructors, free up any memory used by
8138 the body, and free the body itself. The SV's head is not
8139 freed, although its type is set to all 1's so that it won't
8140 inadvertently be assumed to be live during global destruction
8141 etc. This function should only be called when "REFCNT" is
8142 zero. Most of the time you'll want to call "sv_free()" (or its
8143 macro wrapper "SvREFCNT_dec") instead.
8144
8145 void sv_clear(SV *const orig_sv)
8146
8147 sv_cmp Compares the strings in two SVs. Returns -1, 0, or 1
8148 indicating whether the string in "sv1" is less than, equal to,
8149 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
8150 aware, handles get magic, and will coerce its args to strings
8151 if necessary. See also "sv_cmp_locale".
8152
8153 I32 sv_cmp(SV *const sv1, SV *const sv2)
8154
8155 sv_cmp_flags
8156 Compares the strings in two SVs. Returns -1, 0, or 1
8157 indicating whether the string in "sv1" is less than, equal to,
8158 or greater than the string in "sv2". Is UTF-8 and 'use bytes'
8159 aware and will coerce its args to strings if necessary. If the
8160 flags has the "SV_GMAGIC" bit set, it handles get magic. See
8161 also "sv_cmp_locale_flags".
8162
8163 I32 sv_cmp_flags(SV *const sv1, SV *const sv2,
8164 const U32 flags)
8165
8166 sv_cmp_locale
8167 Compares the strings in two SVs in a locale-aware manner. Is
8168 UTF-8 and 'use bytes' aware, handles get magic, and will coerce
8169 its args to strings if necessary. See also "sv_cmp".
8170
8171 I32 sv_cmp_locale(SV *const sv1, SV *const sv2)
8172
8173 sv_cmp_locale_flags
8174 Compares the strings in two SVs in a locale-aware manner. Is
8175 UTF-8 and 'use bytes' aware and will coerce its args to strings
8176 if necessary. If the flags contain "SV_GMAGIC", it handles get
8177 magic. See also "sv_cmp_flags".
8178
8179 I32 sv_cmp_locale_flags(SV *const sv1,
8180 SV *const sv2,
8181 const U32 flags)
8182
8183 sv_collxfrm
8184 This calls "sv_collxfrm_flags" with the SV_GMAGIC flag. See
8185 "sv_collxfrm_flags".
8186
8187 char* sv_collxfrm(SV *const sv, STRLEN *const nxp)
8188
8189 sv_collxfrm_flags
8190 Add Collate Transform magic to an SV if it doesn't already have
8191 it. If the flags contain "SV_GMAGIC", it handles get-magic.
8192
8193 Any scalar variable may carry "PERL_MAGIC_collxfrm" magic that
8194 contains the scalar data of the variable, but transformed to
8195 such a format that a normal memory comparison can be used to
8196 compare the data according to the locale settings.
8197
8198 char* sv_collxfrm_flags(SV *const sv,
8199 STRLEN *const nxp,
8200 I32 const flags)
8201
8202 sv_copypv
8203 Copies a stringified representation of the source SV into the
8204 destination SV. Automatically performs any necessary "mg_get"
8205 and coercion of numeric values into strings. Guaranteed to
8206 preserve "UTF8" flag even from overloaded objects. Similar in
8207 nature to "sv_2pv[_flags]" but operates directly on an SV
8208 instead of just the string. Mostly uses "sv_2pv_flags" to do
8209 its work, except when that would lose the UTF-8'ness of the PV.
8210
8211 void sv_copypv(SV *const dsv, SV *const ssv)
8212
8213 sv_copypv_flags
8214 Implementation of "sv_copypv" and "sv_copypv_nomg". Calls get
8215 magic iff flags has the "SV_GMAGIC" bit set.
8216
8217 void sv_copypv_flags(SV *const dsv, SV *const ssv,
8218 const I32 flags)
8219
8220 sv_copypv_nomg
8221 Like "sv_copypv", but doesn't invoke get magic first.
8222
8223 void sv_copypv_nomg(SV *const dsv, SV *const ssv)
8224
8225 SvCUR Returns the length of the string which is in the SV. See
8226 "SvLEN".
8227
8228 STRLEN SvCUR(SV* sv)
8229
8230 SvCUR_set
8231 Set the current length of the string which is in the SV. See
8232 "SvCUR" and "SvIV_set">.
8233
8234 void SvCUR_set(SV* sv, STRLEN len)
8235
8236 sv_dec Auto-decrement of the value in the SV, doing string to numeric
8237 conversion if necessary. Handles 'get' magic and operator
8238 overloading.
8239
8240 void sv_dec(SV *const sv)
8241
8242 sv_dec_nomg
8243 Auto-decrement of the value in the SV, doing string to numeric
8244 conversion if necessary. Handles operator overloading. Skips
8245 handling 'get' magic.
8246
8247 void sv_dec_nomg(SV *const sv)
8248
8249 sv_derived_from
8250 Exactly like "sv_derived_from_pv", but doesn't take a "flags"
8251 parameter.
8252
8253 bool sv_derived_from(SV* sv, const char *const name)
8254
8255 sv_derived_from_pv
8256 Exactly like "sv_derived_from_pvn", but takes a nul-terminated
8257 string instead of a string/length pair.
8258
8259 bool sv_derived_from_pv(SV* sv,
8260 const char *const name,
8261 U32 flags)
8262
8263 sv_derived_from_pvn
8264 Returns a boolean indicating whether the SV is derived from the
8265 specified class at the C level. To check derivation at the
8266 Perl level, call "isa()" as a normal Perl method.
8267
8268 Currently, the only significant value for "flags" is SVf_UTF8.
8269
8270 bool sv_derived_from_pvn(SV* sv,
8271 const char *const name,
8272 const STRLEN len, U32 flags)
8273
8274 sv_derived_from_sv
8275 Exactly like "sv_derived_from_pvn", but takes the name string
8276 in the form of an SV instead of a string/length pair. This is
8277 the advised form.
8278
8279 bool sv_derived_from_sv(SV* sv, SV *namesv,
8280 U32 flags)
8281
8282 sv_does Like "sv_does_pv", but doesn't take a "flags" parameter.
8283
8284 bool sv_does(SV* sv, const char *const name)
8285
8286 sv_does_pv
8287 Like "sv_does_sv", but takes a nul-terminated string instead of
8288 an SV.
8289
8290 bool sv_does_pv(SV* sv, const char *const name,
8291 U32 flags)
8292
8293 sv_does_pvn
8294 Like "sv_does_sv", but takes a string/length pair instead of an
8295 SV.
8296
8297 bool sv_does_pvn(SV* sv, const char *const name,
8298 const STRLEN len, U32 flags)
8299
8300 sv_does_sv
8301 Returns a boolean indicating whether the SV performs a
8302 specific, named role. The SV can be a Perl object or the name
8303 of a Perl class.
8304
8305 bool sv_does_sv(SV* sv, SV* namesv, U32 flags)
8306
8307 SvEND Returns a pointer to the spot just after the last character in
8308 the string which is in the SV, where there is usually a
8309 trailing "NUL" character (even though Perl scalars do not
8310 strictly require it). See "SvCUR". Access the character as
8311 "*(SvEND(sv))".
8312
8313 Warning: If "SvCUR" is equal to "SvLEN", then "SvEND" points to
8314 unallocated memory.
8315
8316 char* SvEND(SV* sv)
8317
8318 sv_eq Returns a boolean indicating whether the strings in the two SVs
8319 are identical. Is UTF-8 and 'use bytes' aware, handles get
8320 magic, and will coerce its args to strings if necessary.
8321
8322 I32 sv_eq(SV* sv1, SV* sv2)
8323
8324 sv_eq_flags
8325 Returns a boolean indicating whether the strings in the two SVs
8326 are identical. Is UTF-8 and 'use bytes' aware and coerces its
8327 args to strings if necessary. If the flags has the "SV_GMAGIC"
8328 bit set, it handles get-magic, too.
8329
8330 I32 sv_eq_flags(SV* sv1, SV* sv2, const U32 flags)
8331
8332 sv_force_normal_flags
8333 Undo various types of fakery on an SV, where fakery means "more
8334 than" a string: if the PV is a shared string, make a private
8335 copy; if we're a ref, stop refing; if we're a glob, downgrade
8336 to an "xpvmg"; if we're a copy-on-write scalar, this is the on-
8337 write time when we do the copy, and is also used locally; if
8338 this is a vstring, drop the vstring magic. If "SV_COW_DROP_PV"
8339 is set then a copy-on-write scalar drops its PV buffer (if any)
8340 and becomes "SvPOK_off" rather than making a copy. (Used where
8341 this scalar is about to be set to some other value.) In
8342 addition, the "flags" parameter gets passed to
8343 "sv_unref_flags()" when unreffing. "sv_force_normal" calls
8344 this function with flags set to 0.
8345
8346 This function is expected to be used to signal to perl that
8347 this SV is about to be written to, and any extra book-keeping
8348 needs to be taken care of. Hence, it croaks on read-only
8349 values.
8350
8351 void sv_force_normal_flags(SV *const sv,
8352 const U32 flags)
8353
8354 sv_free Decrement an SV's reference count, and if it drops to zero,
8355 call "sv_clear" to invoke destructors and free up any memory
8356 used by the body; finally, deallocating the SV's head itself.
8357 Normally called via a wrapper macro "SvREFCNT_dec".
8358
8359 void sv_free(SV *const sv)
8360
8361 SvGAMAGIC
8362 Returns true if the SV has get magic or overloading. If either
8363 is true then the scalar is active data, and has the potential
8364 to return a new value every time it is accessed. Hence you
8365 must be careful to only read it once per user logical operation
8366 and work with that returned value. If neither is true then the
8367 scalar's value cannot change unless written to.
8368
8369 U32 SvGAMAGIC(SV* sv)
8370
8371 sv_gets Get a line from the filehandle and store it into the SV,
8372 optionally appending to the currently-stored string. If
8373 "append" is not 0, the line is appended to the SV instead of
8374 overwriting it. "append" should be set to the byte offset that
8375 the appended string should start at in the SV (typically,
8376 "SvCUR(sv)" is a suitable choice).
8377
8378 char* sv_gets(SV *const sv, PerlIO *const fp,
8379 I32 append)
8380
8381 sv_get_backrefs
8382 NOTE: this function is experimental and may change or be
8383 removed without notice.
8384
8385 If "sv" is the target of a weak reference then it returns the
8386 back references structure associated with the sv; otherwise
8387 return "NULL".
8388
8389 When returning a non-null result the type of the return is
8390 relevant. If it is an AV then the elements of the AV are the
8391 weak reference RVs which point at this item. If it is any other
8392 type then the item itself is the weak reference.
8393
8394 See also "Perl_sv_add_backref()", "Perl_sv_del_backref()",
8395 "Perl_sv_kill_backrefs()"
8396
8397 SV* sv_get_backrefs(SV *const sv)
8398
8399 SvGROW Expands the character buffer in the SV so that it has room for
8400 the indicated number of bytes (remember to reserve space for an
8401 extra trailing "NUL" character). Calls "sv_grow" to perform
8402 the expansion if necessary. Returns a pointer to the character
8403 buffer. SV must be of type >= "SVt_PV". One alternative is to
8404 call "sv_grow" if you are not sure of the type of SV.
8405
8406 You might mistakenly think that "len" is the number of bytes to
8407 add to the existing size, but instead it is the total size "sv"
8408 should be.
8409
8410 char * SvGROW(SV* sv, STRLEN len)
8411
8412 sv_grow Expands the character buffer in the SV. If necessary, uses
8413 "sv_unref" and upgrades the SV to "SVt_PV". Returns a pointer
8414 to the character buffer. Use the "SvGROW" wrapper instead.
8415
8416 char* sv_grow(SV *const sv, STRLEN newlen)
8417
8418 sv_inc Auto-increment of the value in the SV, doing string to numeric
8419 conversion if necessary. Handles 'get' magic and operator
8420 overloading.
8421
8422 void sv_inc(SV *const sv)
8423
8424 sv_inc_nomg
8425 Auto-increment of the value in the SV, doing string to numeric
8426 conversion if necessary. Handles operator overloading. Skips
8427 handling 'get' magic.
8428
8429 void sv_inc_nomg(SV *const sv)
8430
8431 sv_insert
8432 Inserts and/or replaces a string at the specified offset/length
8433 within the SV. Similar to the Perl "substr()" function, with
8434 "littlelen" bytes starting at "little" replacing "len" bytes of
8435 the string in "bigstr" starting at "offset". Handles get
8436 magic.
8437
8438 void sv_insert(SV *const bigstr, const STRLEN offset,
8439 const STRLEN len,
8440 const char *const little,
8441 const STRLEN littlelen)
8442
8443 sv_insert_flags
8444 Same as "sv_insert", but the extra "flags" are passed to the
8445 "SvPV_force_flags" that applies to "bigstr".
8446
8447 void sv_insert_flags(SV *const bigstr,
8448 const STRLEN offset,
8449 const STRLEN len,
8450 const char *little,
8451 const STRLEN littlelen,
8452 const U32 flags)
8453
8454 SvIOK Returns a U32 value indicating whether the SV contains an
8455 integer.
8456
8457 U32 SvIOK(SV* sv)
8458
8459 SvIOK_notUV
8460 Returns a boolean indicating whether the SV contains a signed
8461 integer.
8462
8463 bool SvIOK_notUV(SV* sv)
8464
8465 SvIOK_off
8466 Unsets the IV status of an SV.
8467
8468 void SvIOK_off(SV* sv)
8469
8470 SvIOK_on
8471 Tells an SV that it is an integer.
8472
8473 void SvIOK_on(SV* sv)
8474
8475 SvIOK_only
8476 Tells an SV that it is an integer and disables all other "OK"
8477 bits.
8478
8479 void SvIOK_only(SV* sv)
8480
8481 SvIOK_only_UV
8482 Tells an SV that it is an unsigned integer and disables all
8483 other "OK" bits.
8484
8485 void SvIOK_only_UV(SV* sv)
8486
8487 SvIOKp Returns a U32 value indicating whether the SV contains an
8488 integer. Checks the private setting. Use "SvIOK" instead.
8489
8490 U32 SvIOKp(SV* sv)
8491
8492 SvIOK_UV
8493 Returns a boolean indicating whether the SV contains an integer
8494 that must be interpreted as unsigned. A non-negative integer
8495 whose value is within the range of both an IV and a UV may be
8496 flagged as either "SvUOK" or "SvIOK".
8497
8498 bool SvIOK_UV(SV* sv)
8499
8500 sv_isa Returns a boolean indicating whether the SV is blessed into the
8501 specified class.
8502
8503 This does not check for subtypes or method overloading. Use
8504 "sv_isa_sv" to verify an inheritance relationship in the same
8505 way as the "isa" operator by respecting any "isa()" method
8506 overloading; or "sv_derived_from_sv" to test directly on the
8507 actual object type.
8508
8509 int sv_isa(SV* sv, const char *const name)
8510
8511 sv_isa_sv
8512 NOTE: this function is experimental and may change or be
8513 removed without notice.
8514
8515 Returns a boolean indicating whether the SV is an object
8516 reference and is derived from the specified class, respecting
8517 any "isa()" method overloading it may have. Returns false if
8518 "sv" is not a reference to an object, or is not derived from
8519 the specified class.
8520
8521 This is the function used to implement the behaviour of the
8522 "isa" operator.
8523
8524 Does not invoke magic on "sv".
8525
8526 Not to be confused with the older "sv_isa" function, which does
8527 not use an overloaded "isa()" method, nor will check
8528 subclassing.
8529
8530 bool sv_isa_sv(SV* sv, SV* namesv)
8531
8532 SvIsCOW Returns a U32 value indicating whether the SV is Copy-On-Write
8533 (either shared hash key scalars, or full Copy On Write scalars
8534 if 5.9.0 is configured for COW).
8535
8536 U32 SvIsCOW(SV* sv)
8537
8538 SvIsCOW_shared_hash
8539 Returns a boolean indicating whether the SV is Copy-On-Write
8540 shared hash key scalar.
8541
8542 bool SvIsCOW_shared_hash(SV* sv)
8543
8544 sv_isobject
8545 Returns a boolean indicating whether the SV is an RV pointing
8546 to a blessed object. If the SV is not an RV, or if the object
8547 is not blessed, then this will return false.
8548
8549 int sv_isobject(SV* sv)
8550
8551 SvIV Coerces the given SV to IV and returns it. The returned value
8552 in many circumstances will get stored in "sv"'s IV slot, but
8553 not in all cases. (Use "sv_setiv" to make sure it does).
8554
8555 See "SvIVx" for a version which guarantees to evaluate "sv"
8556 only once.
8557
8558 IV SvIV(SV* sv)
8559
8560 SvIV_nomg
8561 Like "SvIV" but doesn't process magic.
8562
8563 IV SvIV_nomg(SV* sv)
8564
8565 SvIV_set
8566 Set the value of the IV pointer in sv to val. It is possible
8567 to perform the same function of this macro with an lvalue
8568 assignment to "SvIVX". With future Perls, however, it will be
8569 more efficient to use "SvIV_set" instead of the lvalue
8570 assignment to "SvIVX".
8571
8572 void SvIV_set(SV* sv, IV val)
8573
8574 SvIVX Returns the raw value in the SV's IV slot, without checks or
8575 conversions. Only use when you are sure "SvIOK" is true. See
8576 also "SvIV".
8577
8578 IV SvIVX(SV* sv)
8579
8580 SvIVx Coerces the given SV to IV and returns it. The returned value
8581 in many circumstances will get stored in "sv"'s IV slot, but
8582 not in all cases. (Use "sv_setiv" to make sure it does).
8583
8584 This form guarantees to evaluate "sv" only once. Only use this
8585 if "sv" is an expression with side effects, otherwise use the
8586 more efficient "SvIV".
8587
8588 IV SvIVx(SV* sv)
8589
8590 SvLEN Returns the size of the string buffer in the SV, not including
8591 any part attributable to "SvOOK". See "SvCUR".
8592
8593 STRLEN SvLEN(SV* sv)
8594
8595 sv_len Returns the length of the string in the SV. Handles magic and
8596 type coercion and sets the UTF8 flag appropriately. See also
8597 "SvCUR", which gives raw access to the "xpv_cur" slot.
8598
8599 STRLEN sv_len(SV *const sv)
8600
8601 SvLEN_set
8602 Set the size of the string buffer for the SV. See "SvLEN".
8603
8604 void SvLEN_set(SV* sv, STRLEN len)
8605
8606 sv_len_utf8
8607 Returns the number of characters in the string in an SV,
8608 counting wide UTF-8 bytes as a single character. Handles magic
8609 and type coercion.
8610
8611 STRLEN sv_len_utf8(SV *const sv)
8612
8613 sv_magic
8614 Adds magic to an SV. First upgrades "sv" to type "SVt_PVMG" if
8615 necessary, then adds a new magic item of type "how" to the head
8616 of the magic list.
8617
8618 See "sv_magicext" (which "sv_magic" now calls) for a
8619 description of the handling of the "name" and "namlen"
8620 arguments.
8621
8622 You need to use "sv_magicext" to add magic to "SvREADONLY" SVs
8623 and also to add more than one instance of the same "how".
8624
8625 void sv_magic(SV *const sv, SV *const obj,
8626 const int how, const char *const name,
8627 const I32 namlen)
8628
8629 sv_magicext
8630 Adds magic to an SV, upgrading it if necessary. Applies the
8631 supplied "vtable" and returns a pointer to the magic added.
8632
8633 Note that "sv_magicext" will allow things that "sv_magic" will
8634 not. In particular, you can add magic to "SvREADONLY" SVs, and
8635 add more than one instance of the same "how".
8636
8637 If "namlen" is greater than zero then a "savepvn" copy of
8638 "name" is stored, if "namlen" is zero then "name" is stored as-
8639 is and - as another special case - if "(name && namlen ==
8640 HEf_SVKEY)" then "name" is assumed to contain an SV* and is
8641 stored as-is with its "REFCNT" incremented.
8642
8643 (This is now used as a subroutine by "sv_magic".)
8644
8645 MAGIC * sv_magicext(SV *const sv, SV *const obj,
8646 const int how,
8647 const MGVTBL *const vtbl,
8648 const char *const name,
8649 const I32 namlen)
8650
8651 SvMAGIC_set
8652 Set the value of the MAGIC pointer in "sv" to val. See
8653 "SvIV_set".
8654
8655 void SvMAGIC_set(SV* sv, MAGIC* val)
8656
8657 sv_mortalcopy
8658 Creates a new SV which is a copy of the original SV (using
8659 "sv_setsv"). The new SV is marked as mortal. It will be
8660 destroyed "soon", either by an explicit call to "FREETMPS", or
8661 by an implicit call at places such as statement boundaries.
8662 See also "sv_newmortal" and "sv_2mortal".
8663
8664 SV* sv_mortalcopy(SV *const oldsv)
8665
8666 sv_mortalcopy_flags
8667 Like "sv_mortalcopy", but the extra "flags" are passed to the
8668 "sv_setsv_flags".
8669
8670 SV* sv_mortalcopy_flags(SV *const oldsv, U32 flags)
8671
8672 sv_newmortal
8673 Creates a new null SV which is mortal. The reference count of
8674 the SV is set to 1. It will be destroyed "soon", either by an
8675 explicit call to "FREETMPS", or by an implicit call at places
8676 such as statement boundaries. See also "sv_mortalcopy" and
8677 "sv_2mortal".
8678
8679 SV* sv_newmortal()
8680
8681 sv_newref
8682 Increment an SV's reference count. Use the "SvREFCNT_inc()"
8683 wrapper instead.
8684
8685 SV* sv_newref(SV *const sv)
8686
8687 SvNIOK Returns a U32 value indicating whether the SV contains a
8688 number, integer or double.
8689
8690 U32 SvNIOK(SV* sv)
8691
8692 SvNIOK_off
8693 Unsets the NV/IV status of an SV.
8694
8695 void SvNIOK_off(SV* sv)
8696
8697 SvNIOKp Returns a U32 value indicating whether the SV contains a
8698 number, integer or double. Checks the private setting. Use
8699 "SvNIOK" instead.
8700
8701 U32 SvNIOKp(SV* sv)
8702
8703 SvNOK Returns a U32 value indicating whether the SV contains a
8704 double.
8705
8706 U32 SvNOK(SV* sv)
8707
8708 SvNOK_off
8709 Unsets the NV status of an SV.
8710
8711 void SvNOK_off(SV* sv)
8712
8713 SvNOK_on
8714 Tells an SV that it is a double.
8715
8716 void SvNOK_on(SV* sv)
8717
8718 SvNOK_only
8719 Tells an SV that it is a double and disables all other OK bits.
8720
8721 void SvNOK_only(SV* sv)
8722
8723 SvNOKp Returns a U32 value indicating whether the SV contains a
8724 double. Checks the private setting. Use "SvNOK" instead.
8725
8726 U32 SvNOKp(SV* sv)
8727
8728 SvNV Coerces the given SV to NV and returns it. The returned value
8729 in many circumstances will get stored in "sv"'s NV slot, but
8730 not in all cases. (Use "sv_setnv" to make sure it does).
8731
8732 See "SvNVx" for a version which guarantees to evaluate "sv"
8733 only once.
8734
8735 NV SvNV(SV* sv)
8736
8737 SvNV_nomg
8738 Like "SvNV" but doesn't process magic.
8739
8740 NV SvNV_nomg(SV* sv)
8741
8742 SvNV_set
8743 Set the value of the NV pointer in "sv" to val. See
8744 "SvIV_set".
8745
8746 void SvNV_set(SV* sv, NV val)
8747
8748 SvNVX Returns the raw value in the SV's NV slot, without checks or
8749 conversions. Only use when you are sure "SvNOK" is true. See
8750 also "SvNV".
8751
8752 NV SvNVX(SV* sv)
8753
8754 SvNVx Coerces the given SV to NV and returns it. The returned value
8755 in many circumstances will get stored in "sv"'s NV slot, but
8756 not in all cases. (Use "sv_setnv" to make sure it does).
8757
8758 This form guarantees to evaluate "sv" only once. Only use this
8759 if "sv" is an expression with side effects, otherwise use the
8760 more efficient "SvNV".
8761
8762 NV SvNVx(SV* sv)
8763
8764 SvOK Returns a U32 value indicating whether the value is defined.
8765 This is only meaningful for scalars.
8766
8767 U32 SvOK(SV* sv)
8768
8769 SvOOK Returns a U32 indicating whether the pointer to the string
8770 buffer is offset. This hack is used internally to speed up
8771 removal of characters from the beginning of a "SvPV". When
8772 "SvOOK" is true, then the start of the allocated string buffer
8773 is actually "SvOOK_offset()" bytes before "SvPVX". This offset
8774 used to be stored in "SvIVX", but is now stored within the
8775 spare part of the buffer.
8776
8777 U32 SvOOK(SV* sv)
8778
8779 SvOOK_offset
8780 Reads into "len" the offset from "SvPVX" back to the true start
8781 of the allocated buffer, which will be non-zero if "sv_chop"
8782 has been used to efficiently remove characters from start of
8783 the buffer. Implemented as a macro, which takes the address of
8784 "len", which must be of type "STRLEN". Evaluates "sv" more
8785 than once. Sets "len" to 0 if "SvOOK(sv)" is false.
8786
8787 void SvOOK_offset(SV*sv, STRLEN len)
8788
8789 SvPOK Returns a U32 value indicating whether the SV contains a
8790 character string.
8791
8792 U32 SvPOK(SV* sv)
8793
8794 SvPOK_off
8795 Unsets the PV status of an SV.
8796
8797 void SvPOK_off(SV* sv)
8798
8799 SvPOK_on
8800 Tells an SV that it is a string.
8801
8802 void SvPOK_on(SV* sv)
8803
8804 SvPOK_only
8805 Tells an SV that it is a string and disables all other "OK"
8806 bits. Will also turn off the UTF-8 status.
8807
8808 void SvPOK_only(SV* sv)
8809
8810 SvPOK_only_UTF8
8811 Tells an SV that it is a string and disables all other "OK"
8812 bits, and leaves the UTF-8 status as it was.
8813
8814 void SvPOK_only_UTF8(SV* sv)
8815
8816 SvPOKp Returns a U32 value indicating whether the SV contains a
8817 character string. Checks the private setting. Use "SvPOK"
8818 instead.
8819
8820 U32 SvPOKp(SV* sv)
8821
8822 sv_pos_b2u
8823 Converts the value pointed to by "offsetp" from a count of
8824 bytes from the start of the string, to a count of the
8825 equivalent number of UTF-8 chars. Handles magic and type
8826 coercion.
8827
8828 Use "sv_pos_b2u_flags" in preference, which correctly handles
8829 strings longer than 2Gb.
8830
8831 void sv_pos_b2u(SV *const sv, I32 *const offsetp)
8832
8833 sv_pos_b2u_flags
8834 Converts "offset" from a count of bytes from the start of the
8835 string, to a count of the equivalent number of UTF-8 chars.
8836 Handles type coercion. "flags" is passed to "SvPV_flags", and
8837 usually should be "SV_GMAGIC|SV_CONST_RETURN" to handle magic.
8838
8839 STRLEN sv_pos_b2u_flags(SV *const sv,
8840 STRLEN const offset, U32 flags)
8841
8842 sv_pos_u2b
8843 Converts the value pointed to by "offsetp" from a count of
8844 UTF-8 chars from the start of the string, to a count of the
8845 equivalent number of bytes; if "lenp" is non-zero, it does the
8846 same to "lenp", but this time starting from the offset, rather
8847 than from the start of the string. Handles magic and type
8848 coercion.
8849
8850 Use "sv_pos_u2b_flags" in preference, which correctly handles
8851 strings longer than 2Gb.
8852
8853 void sv_pos_u2b(SV *const sv, I32 *const offsetp,
8854 I32 *const lenp)
8855
8856 sv_pos_u2b_flags
8857 Converts the offset from a count of UTF-8 chars from the start
8858 of the string, to a count of the equivalent number of bytes; if
8859 "lenp" is non-zero, it does the same to "lenp", but this time
8860 starting from "offset", rather than from the start of the
8861 string. Handles type coercion. "flags" is passed to
8862 "SvPV_flags", and usually should be "SV_GMAGIC|SV_CONST_RETURN"
8863 to handle magic.
8864
8865 STRLEN sv_pos_u2b_flags(SV *const sv, STRLEN uoffset,
8866 STRLEN *const lenp, U32 flags)
8867
8868 SvPV Returns a pointer to the string in the SV, or a stringified
8869 form of the SV if the SV does not contain a string. The SV may
8870 cache the stringified version becoming "SvPOK". Handles 'get'
8871 magic. The "len" variable will be set to the length of the
8872 string (this is a macro, so don't use &len). See also "SvPVx"
8873 for a version which guarantees to evaluate "sv" only once.
8874
8875 Note that there is no guarantee that the return value of
8876 "SvPV()" is equal to "SvPVX(sv)", or that "SvPVX(sv)" contains
8877 valid data, or that successive calls to "SvPV(sv)" will return
8878 the same pointer value each time. This is due to the way that
8879 things like overloading and Copy-On-Write are handled. In
8880 these cases, the return value may point to a temporary buffer
8881 or similar. If you absolutely need the "SvPVX" field to be
8882 valid (for example, if you intend to write to it), then see
8883 "SvPV_force".
8884
8885 char* SvPV(SV* sv, STRLEN len)
8886
8887 SvPVbyte
8888 Like "SvPV", but converts "sv" to byte representation first if
8889 necessary. If the SV cannot be downgraded from UTF-8, this
8890 croaks.
8891
8892 char* SvPVbyte(SV* sv, STRLEN len)
8893
8894 SvPVbyte_force
8895 Like "SvPV_force", but converts "sv" to byte representation
8896 first if necessary. If the SV cannot be downgraded from UTF-8,
8897 this croaks.
8898
8899 char* SvPVbyte_force(SV* sv, STRLEN len)
8900
8901 SvPVbyte_nolen
8902 Like "SvPV_nolen", but converts "sv" to byte representation
8903 first if necessary. If the SV cannot be downgraded from UTF-8,
8904 this croaks.
8905
8906 char* SvPVbyte_nolen(SV* sv)
8907
8908 SvPVbyte_nomg
8909 Like "SvPVbyte", but does not process get magic.
8910
8911 char* SvPVbyte_nomg(SV* sv, STRLEN len)
8912
8913 sv_pvbyten_force
8914 The backend for the "SvPVbytex_force" macro. Always use the
8915 macro instead. If the SV cannot be downgraded from UTF-8, this
8916 croaks.
8917
8918 char* sv_pvbyten_force(SV *const sv, STRLEN *const lp)
8919
8920 SvPVbyte_or_null
8921 Like "SvPVbyte", but when "sv" is undef, returns "NULL".
8922
8923 char* SvPVbyte_or_null(SV* sv, STRLEN len)
8924
8925 SvPVbyte_or_null_nomg
8926 Like "SvPVbyte_or_null", but does not process get magic.
8927
8928 char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
8929
8930 SvPVbytex
8931 Like "SvPV", but converts "sv" to byte representation first if
8932 necessary. Guarantees to evaluate "sv" only once; use the more
8933 efficient "SvPVbyte" otherwise. If the SV cannot be downgraded
8934 from UTF-8, this croaks.
8935
8936 char* SvPVbytex(SV* sv, STRLEN len)
8937
8938 SvPVbytex_force
8939 Like "SvPV_force", but converts "sv" to byte representation
8940 first if necessary. Guarantees to evaluate "sv" only once; use
8941 the more efficient "SvPVbyte_force" otherwise. If the SV
8942 cannot be downgraded from UTF-8, this croaks.
8943
8944 char* SvPVbytex_force(SV* sv, STRLEN len)
8945
8946 SvPVCLEAR
8947 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that
8948 it is properly null terminated. Equivalent to sv_setpvs(""),
8949 but more efficient.
8950
8951 char * SvPVCLEAR(SV* sv)
8952
8953 SvPV_force
8954 Like "SvPV" but will force the SV into containing a string
8955 ("SvPOK"), and only a string ("SvPOK_only"), by hook or by
8956 crook. You need force if you are going to update the "SvPVX"
8957 directly. Processes get magic.
8958
8959 Note that coercing an arbitrary scalar into a plain PV will
8960 potentially strip useful data from it. For example if the SV
8961 was "SvROK", then the referent will have its reference count
8962 decremented, and the SV itself may be converted to an "SvPOK"
8963 scalar with a string buffer containing a value such as
8964 "ARRAY(0x1234)".
8965
8966 char* SvPV_force(SV* sv, STRLEN len)
8967
8968 SvPV_force_nomg
8969 Like "SvPV_force", but doesn't process get magic.
8970
8971 char* SvPV_force_nomg(SV* sv, STRLEN len)
8972
8973 SvPV_nolen
8974 Like "SvPV" but doesn't set a length variable.
8975
8976 char* SvPV_nolen(SV* sv)
8977
8978 SvPV_nomg
8979 Like "SvPV" but doesn't process magic.
8980
8981 char* SvPV_nomg(SV* sv, STRLEN len)
8982
8983 SvPV_nomg_nolen
8984 Like "SvPV_nolen" but doesn't process magic.
8985
8986 char* SvPV_nomg_nolen(SV* sv)
8987
8988 sv_pvn_force
8989 Get a sensible string out of the SV somehow. A private
8990 implementation of the "SvPV_force" macro for compilers which
8991 can't cope with complex macro expressions. Always use the
8992 macro instead.
8993
8994 char* sv_pvn_force(SV* sv, STRLEN* lp)
8995
8996 sv_pvn_force_flags
8997 Get a sensible string out of the SV somehow. If "flags" has
8998 the "SV_GMAGIC" bit set, will "mg_get" on "sv" if appropriate,
8999 else not. "sv_pvn_force" and "sv_pvn_force_nomg" are
9000 implemented in terms of this function. You normally want to
9001 use the various wrapper macros instead: see "SvPV_force" and
9002 "SvPV_force_nomg".
9003
9004 char* sv_pvn_force_flags(SV *const sv,
9005 STRLEN *const lp,
9006 const I32 flags)
9007
9008 SvPV_set
9009 This is probably not what you want to use, you probably wanted
9010 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
9011
9012 Set the value of the PV pointer in "sv" to the Perl allocated
9013 "NUL"-terminated string "val". See also "SvIV_set".
9014
9015 Remember to free the previous PV buffer. There are many things
9016 to check. Beware that the existing pointer may be involved in
9017 copy-on-write or other mischief, so do "SvOOK_off(sv)" and use
9018 "sv_force_normal" or "SvPV_force" (or check the "SvIsCOW" flag)
9019 first to make sure this modification is safe. Then finally, if
9020 it is not a COW, call "SvPV_free" to free the previous PV
9021 buffer.
9022
9023 void SvPV_set(SV* sv, char* val)
9024
9025 SvPVutf8
9026 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
9027
9028 char* SvPVutf8(SV* sv, STRLEN len)
9029
9030 sv_pvutf8n_force
9031 The backend for the "SvPVutf8x_force" macro. Always use the
9032 macro instead.
9033
9034 char* sv_pvutf8n_force(SV *const sv, STRLEN *const lp)
9035
9036 SvPVutf8x
9037 Like "SvPV", but converts "sv" to UTF-8 first if necessary.
9038 Guarantees to evaluate "sv" only once; use the more efficient
9039 "SvPVutf8" otherwise.
9040
9041 char* SvPVutf8x(SV* sv, STRLEN len)
9042
9043 SvPVutf8x_force
9044 Like "SvPV_force", but converts "sv" to UTF-8 first if
9045 necessary. Guarantees to evaluate "sv" only once; use the more
9046 efficient "SvPVutf8_force" otherwise.
9047
9048 char* SvPVutf8x_force(SV* sv, STRLEN len)
9049
9050 SvPVutf8_force
9051 Like "SvPV_force", but converts "sv" to UTF-8 first if
9052 necessary.
9053
9054 char* SvPVutf8_force(SV* sv, STRLEN len)
9055
9056 SvPVutf8_nolen
9057 Like "SvPV_nolen", but converts "sv" to UTF-8 first if
9058 necessary.
9059
9060 char* SvPVutf8_nolen(SV* sv)
9061
9062 SvPVutf8_nomg
9063 Like "SvPVutf8", but does not process get magic.
9064
9065 char* SvPVutf8_nomg(SV* sv, STRLEN len)
9066
9067 SvPVutf8_or_null
9068 Like "SvPVutf8", but when "sv" is undef, returns "NULL".
9069
9070 char* SvPVutf8_or_null(SV* sv, STRLEN len)
9071
9072 SvPVutf8_or_null_nomg
9073 Like "SvPVutf8_or_null", but does not process get magic.
9074
9075 char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
9076
9077 SvPVX Returns a pointer to the physical string in the SV. The SV
9078 must contain a string. Prior to 5.9.3 it is not safe to
9079 execute this macro unless the SV's type >= "SVt_PV".
9080
9081 This is also used to store the name of an autoloaded subroutine
9082 in an XS AUTOLOAD routine. See "Autoloading with XSUBs" in
9083 perlguts.
9084
9085 char* SvPVX(SV* sv)
9086
9087 SvPVx A version of "SvPV" which guarantees to evaluate "sv" only
9088 once. Only use this if "sv" is an expression with side
9089 effects, otherwise use the more efficient "SvPV".
9090
9091 char* SvPVx(SV* sv, STRLEN len)
9092
9093 SvREADONLY
9094 Returns true if the argument is readonly, otherwise returns
9095 false. Exposed to perl code via Internals::SvREADONLY().
9096
9097 U32 SvREADONLY(SV* sv)
9098
9099 SvREADONLY_off
9100 Mark an object as not-readonly. Exactly what this mean depends
9101 on the object type. Exposed to perl code via
9102 Internals::SvREADONLY().
9103
9104 U32 SvREADONLY_off(SV* sv)
9105
9106 SvREADONLY_on
9107 Mark an object as readonly. Exactly what this means depends on
9108 the object type. Exposed to perl code via
9109 Internals::SvREADONLY().
9110
9111 U32 SvREADONLY_on(SV* sv)
9112
9113 sv_ref Returns a SV describing what the SV passed in is a reference
9114 to.
9115
9116 dst can be a SV to be set to the description or NULL, in which
9117 case a mortal SV is returned.
9118
9119 If ob is true and the SV is blessed, the description is the
9120 class name, otherwise it is the type of the SV, "SCALAR",
9121 "ARRAY" etc.
9122
9123 SV* sv_ref(SV *dst, const SV *const sv,
9124 const int ob)
9125
9126 SvREFCNT
9127 Returns the value of the object's reference count. Exposed to
9128 perl code via Internals::SvREFCNT().
9129
9130 U32 SvREFCNT(SV* sv)
9131
9132 SvREFCNT_dec
9133 Decrements the reference count of the given SV. "sv" may be
9134 "NULL".
9135
9136 void SvREFCNT_dec(SV *sv)
9137
9138 SvREFCNT_dec_NN
9139 Same as "SvREFCNT_dec", but can only be used if you know "sv"
9140 is not "NULL". Since we don't have to check the NULLness, it's
9141 faster and smaller.
9142
9143 void SvREFCNT_dec_NN(SV *sv)
9144
9145 SvREFCNT_inc
9146 Increments the reference count of the given SV, returning the
9147 SV.
9148
9149 All of the following "SvREFCNT_inc"* are optimized versions of
9150 "SvREFCNT_inc", and can be replaced with "SvREFCNT_inc".
9151
9152 SV * SvREFCNT_inc(SV *sv)
9153
9154 SvREFCNT_inc_NN
9155 Same as "SvREFCNT_inc", but can only be used if you know "sv"
9156 is not "NULL". Since we don't have to check the NULLness, it's
9157 faster and smaller.
9158
9159 SV * SvREFCNT_inc_NN(SV *sv)
9160
9161 SvREFCNT_inc_simple
9162 Same as "SvREFCNT_inc", but can only be used with expressions
9163 without side effects. Since we don't have to store a temporary
9164 value, it's faster.
9165
9166 SV* SvREFCNT_inc_simple(SV* sv)
9167
9168 SvREFCNT_inc_simple_NN
9169 Same as "SvREFCNT_inc_simple", but can only be used if you know
9170 "sv" is not "NULL". Since we don't have to check the NULLness,
9171 it's faster and smaller.
9172
9173 SV* SvREFCNT_inc_simple_NN(SV* sv)
9174
9175 SvREFCNT_inc_simple_void
9176 Same as "SvREFCNT_inc_simple", but can only be used if you
9177 don't need the return value. The macro doesn't need to return
9178 a meaningful value.
9179
9180 void SvREFCNT_inc_simple_void(SV* sv)
9181
9182 SvREFCNT_inc_simple_void_NN
9183 Same as "SvREFCNT_inc", but can only be used if you don't need
9184 the return value, and you know that "sv" is not "NULL". The
9185 macro doesn't need to return a meaningful value, or check for
9186 NULLness, so it's smaller and faster.
9187
9188 void SvREFCNT_inc_simple_void_NN(SV* sv)
9189
9190 SvREFCNT_inc_void
9191 Same as "SvREFCNT_inc", but can only be used if you don't need
9192 the return value. The macro doesn't need to return a
9193 meaningful value.
9194
9195 void SvREFCNT_inc_void(SV *sv)
9196
9197 SvREFCNT_inc_void_NN
9198 Same as "SvREFCNT_inc", but can only be used if you don't need
9199 the return value, and you know that "sv" is not "NULL". The
9200 macro doesn't need to return a meaningful value, or check for
9201 NULLness, so it's smaller and faster.
9202
9203 void SvREFCNT_inc_void_NN(SV* sv)
9204
9205 sv_reftype
9206 Returns a string describing what the SV is a reference to.
9207
9208 If ob is true and the SV is blessed, the string is the class
9209 name, otherwise it is the type of the SV, "SCALAR", "ARRAY"
9210 etc.
9211
9212 const char* sv_reftype(const SV *const sv, const int ob)
9213
9214 sv_replace
9215 Make the first argument a copy of the second, then delete the
9216 original. The target SV physically takes over ownership of the
9217 body of the source SV and inherits its flags; however, the
9218 target keeps any magic it owns, and any magic in the source is
9219 discarded. Note that this is a rather specialist SV copying
9220 operation; most of the time you'll want to use "sv_setsv" or
9221 one of its many macro front-ends.
9222
9223 void sv_replace(SV *const sv, SV *const nsv)
9224
9225 sv_report_used
9226 Dump the contents of all SVs not yet freed (debugging aid).
9227
9228 void sv_report_used()
9229
9230 sv_reset
9231 Underlying implementation for the "reset" Perl function. Note
9232 that the perl-level function is vaguely deprecated.
9233
9234 void sv_reset(const char* s, HV *const stash)
9235
9236 SvROK Tests if the SV is an RV.
9237
9238 U32 SvROK(SV* sv)
9239
9240 SvROK_off
9241 Unsets the RV status of an SV.
9242
9243 void SvROK_off(SV* sv)
9244
9245 SvROK_on
9246 Tells an SV that it is an RV.
9247
9248 void SvROK_on(SV* sv)
9249
9250 SvRV Dereferences an RV to return the SV.
9251
9252 SV* SvRV(SV* sv)
9253
9254 SvRV_set
9255 Set the value of the RV pointer in "sv" to val. See
9256 "SvIV_set".
9257
9258 void SvRV_set(SV* sv, SV* val)
9259
9260 sv_rvunweaken
9261 Unweaken a reference: Clear the "SvWEAKREF" flag on this RV;
9262 remove the backreference to this RV from the array of
9263 backreferences associated with the target SV, increment the
9264 refcount of the target. Silently ignores "undef" and warns on
9265 non-weak references.
9266
9267 SV* sv_rvunweaken(SV *const sv)
9268
9269 sv_rvweaken
9270 Weaken a reference: set the "SvWEAKREF" flag on this RV; give
9271 the referred-to SV "PERL_MAGIC_backref" magic if it hasn't
9272 already; and push a back-reference to this RV onto the array of
9273 backreferences associated with that magic. If the RV is
9274 magical, set magic will be called after the RV is cleared.
9275 Silently ignores "undef" and warns on already-weak references.
9276
9277 SV* sv_rvweaken(SV *const sv)
9278
9279 sv_setiv
9280 Copies an integer into the given SV, upgrading first if
9281 necessary. Does not handle 'set' magic. See also
9282 "sv_setiv_mg".
9283
9284 void sv_setiv(SV *const sv, const IV num)
9285
9286 sv_setiv_mg
9287 Like "sv_setiv", but also handles 'set' magic.
9288
9289 void sv_setiv_mg(SV *const sv, const IV i)
9290
9291 sv_setnv
9292 Copies a double into the given SV, upgrading first if
9293 necessary. Does not handle 'set' magic. See also
9294 "sv_setnv_mg".
9295
9296 void sv_setnv(SV *const sv, const NV num)
9297
9298 sv_setnv_mg
9299 Like "sv_setnv", but also handles 'set' magic.
9300
9301 void sv_setnv_mg(SV *const sv, const NV num)
9302
9303 sv_setpv
9304 Copies a string into an SV. The string must be terminated with
9305 a "NUL" character, and not contain embeded "NUL"'s. Does not
9306 handle 'set' magic. See "sv_setpv_mg".
9307
9308 void sv_setpv(SV *const sv, const char *const ptr)
9309
9310 sv_setpvf
9311 Works like "sv_catpvf" but copies the text into the SV instead
9312 of appending it. Does not handle 'set' magic. See
9313 "sv_setpvf_mg".
9314
9315 void sv_setpvf(SV *const sv, const char *const pat,
9316 ...)
9317
9318 sv_setpvf_mg
9319 Like "sv_setpvf", but also handles 'set' magic.
9320
9321 void sv_setpvf_mg(SV *const sv,
9322 const char *const pat, ...)
9323
9324 sv_setpviv
9325 DEPRECATED! It is planned to remove this function from a
9326 future release of Perl. Do not use it for new code; remove it
9327 from existing code.
9328
9329 Copies an integer into the given SV, also updating its string
9330 value. Does not handle 'set' magic. See "sv_setpviv_mg".
9331
9332 void sv_setpviv(SV *const sv, const IV num)
9333
9334 sv_setpviv_mg
9335 DEPRECATED! It is planned to remove this function from a
9336 future release of Perl. Do not use it for new code; remove it
9337 from existing code.
9338
9339 Like "sv_setpviv", but also handles 'set' magic.
9340
9341 void sv_setpviv_mg(SV *const sv, const IV iv)
9342
9343 sv_setpvn
9344 Copies a string (possibly containing embedded "NUL" characters)
9345 into an SV. The "len" parameter indicates the number of bytes
9346 to be copied. If the "ptr" argument is NULL the SV will become
9347 undefined. Does not handle 'set' magic. See "sv_setpvn_mg".
9348
9349 The UTF-8 flag is not changed by this function. A terminating
9350 NUL byte is guaranteed.
9351
9352 void sv_setpvn(SV *const sv, const char *const ptr,
9353 const STRLEN len)
9354
9355 sv_setpvn_mg
9356 Like "sv_setpvn", but also handles 'set' magic.
9357
9358 void sv_setpvn_mg(SV *const sv,
9359 const char *const ptr,
9360 const STRLEN len)
9361
9362 sv_setpvs
9363 Like "sv_setpvn", but takes a literal string instead of a
9364 string/length pair.
9365
9366 void sv_setpvs(SV* sv, "literal string")
9367
9368 sv_setpvs_mg
9369 Like "sv_setpvn_mg", but takes a literal string instead of a
9370 string/length pair.
9371
9372 void sv_setpvs_mg(SV* sv, "literal string")
9373
9374 sv_setpv_bufsize
9375 Sets the SV to be a string of cur bytes length, with at least
9376 len bytes available. Ensures that there is a null byte at
9377 SvEND. Returns a char * pointer to the SvPV buffer.
9378
9379 char * sv_setpv_bufsize(SV *const sv, const STRLEN cur,
9380 const STRLEN len)
9381
9382 sv_setpv_mg
9383 Like "sv_setpv", but also handles 'set' magic.
9384
9385 void sv_setpv_mg(SV *const sv, const char *const ptr)
9386
9387 sv_setref_iv
9388 Copies an integer into a new SV, optionally blessing the SV.
9389 The "rv" argument will be upgraded to an RV. That RV will be
9390 modified to point to the new SV. The "classname" argument
9391 indicates the package for the blessing. Set "classname" to
9392 "NULL" to avoid the blessing. The new SV will have a reference
9393 count of 1, and the RV will be returned.
9394
9395 SV* sv_setref_iv(SV *const rv,
9396 const char *const classname,
9397 const IV iv)
9398
9399 sv_setref_nv
9400 Copies a double into a new SV, optionally blessing the SV. The
9401 "rv" argument will be upgraded to an RV. That RV will be
9402 modified to point to the new SV. The "classname" argument
9403 indicates the package for the blessing. Set "classname" to
9404 "NULL" to avoid the blessing. The new SV will have a reference
9405 count of 1, and the RV will be returned.
9406
9407 SV* sv_setref_nv(SV *const rv,
9408 const char *const classname,
9409 const NV nv)
9410
9411 sv_setref_pv
9412 Copies a pointer into a new SV, optionally blessing the SV.
9413 The "rv" argument will be upgraded to an RV. That RV will be
9414 modified to point to the new SV. If the "pv" argument is
9415 "NULL", then "PL_sv_undef" will be placed into the SV. The
9416 "classname" argument indicates the package for the blessing.
9417 Set "classname" to "NULL" to avoid the blessing. The new SV
9418 will have a reference count of 1, and the RV will be returned.
9419
9420 Do not use with other Perl types such as HV, AV, SV, CV,
9421 because those objects will become corrupted by the pointer copy
9422 process.
9423
9424 Note that "sv_setref_pvn" copies the string while this copies
9425 the pointer.
9426
9427 SV* sv_setref_pv(SV *const rv,
9428 const char *const classname,
9429 void *const pv)
9430
9431 sv_setref_pvn
9432 Copies a string into a new SV, optionally blessing the SV. The
9433 length of the string must be specified with "n". The "rv"
9434 argument will be upgraded to an RV. That RV will be modified
9435 to point to the new SV. The "classname" argument indicates the
9436 package for the blessing. Set "classname" to "NULL" to avoid
9437 the blessing. The new SV will have a reference count of 1, and
9438 the RV will be returned.
9439
9440 Note that "sv_setref_pv" copies the pointer while this copies
9441 the string.
9442
9443 SV* sv_setref_pvn(SV *const rv,
9444 const char *const classname,
9445 const char *const pv,
9446 const STRLEN n)
9447
9448 sv_setref_pvs
9449 Like "sv_setref_pvn", but takes a literal string instead of a
9450 string/length pair.
9451
9452 SV * sv_setref_pvs(SV *const rv,
9453 const char *const classname,
9454 "literal string")
9455
9456 sv_setref_uv
9457 Copies an unsigned integer into a new SV, optionally blessing
9458 the SV. The "rv" argument will be upgraded to an RV. That RV
9459 will be modified to point to the new SV. The "classname"
9460 argument indicates the package for the blessing. Set
9461 "classname" to "NULL" to avoid the blessing. The new SV will
9462 have a reference count of 1, and the RV will be returned.
9463
9464 SV* sv_setref_uv(SV *const rv,
9465 const char *const classname,
9466 const UV uv)
9467
9468 sv_setsv
9469 Copies the contents of the source SV "ssv" into the destination
9470 SV "dsv". The source SV may be destroyed if it is mortal, so
9471 don't use this function if the source SV needs to be reused.
9472 Does not handle 'set' magic on destination SV. Calls 'get'
9473 magic on source SV. Loosely speaking, it performs a copy-by-
9474 value, obliterating any previous content of the destination.
9475
9476 You probably want to use one of the assortment of wrappers,
9477 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
9478 "SvSetMagicSV_nosteal".
9479
9480 void sv_setsv(SV *dstr, SV *sstr)
9481
9482 sv_setsv_flags
9483 Copies the contents of the source SV "ssv" into the destination
9484 SV "dsv". The source SV may be destroyed if it is mortal, so
9485 don't use this function if the source SV needs to be reused.
9486 Does not handle 'set' magic. Loosely speaking, it performs a
9487 copy-by-value, obliterating any previous content of the
9488 destination. If the "flags" parameter has the "SV_GMAGIC" bit
9489 set, will "mg_get" on "ssv" if appropriate, else not. If the
9490 "flags" parameter has the "SV_NOSTEAL" bit set then the buffers
9491 of temps will not be stolen. "sv_setsv" and "sv_setsv_nomg"
9492 are implemented in terms of this function.
9493
9494 You probably want to use one of the assortment of wrappers,
9495 such as "SvSetSV", "SvSetSV_nosteal", "SvSetMagicSV" and
9496 "SvSetMagicSV_nosteal".
9497
9498 This is the primary function for copying scalars, and most
9499 other copy-ish functions and macros use this underneath.
9500
9501 void sv_setsv_flags(SV *dstr, SV *sstr,
9502 const I32 flags)
9503
9504 sv_setsv_mg
9505 Like "sv_setsv", but also handles 'set' magic.
9506
9507 void sv_setsv_mg(SV *const dstr, SV *const sstr)
9508
9509 sv_setsv_nomg
9510 Like "sv_setsv" but doesn't process magic.
9511
9512 void sv_setsv_nomg(SV* dsv, SV* ssv)
9513
9514 sv_setuv
9515 Copies an unsigned integer into the given SV, upgrading first
9516 if necessary. Does not handle 'set' magic. See also
9517 "sv_setuv_mg".
9518
9519 void sv_setuv(SV *const sv, const UV num)
9520
9521 sv_setuv_mg
9522 Like "sv_setuv", but also handles 'set' magic.
9523
9524 void sv_setuv_mg(SV *const sv, const UV u)
9525
9526 sv_set_undef
9527 Equivalent to "sv_setsv(sv, &PL_sv_undef)", but more efficient.
9528 Doesn't handle set magic.
9529
9530 The perl equivalent is "$sv = undef;". Note that it doesn't
9531 free any string buffer, unlike "undef $sv".
9532
9533 Introduced in perl 5.25.12.
9534
9535 void sv_set_undef(SV *sv)
9536
9537 SvSTASH Returns the stash of the SV.
9538
9539 HV* SvSTASH(SV* sv)
9540
9541 SvSTASH_set
9542 Set the value of the STASH pointer in "sv" to val. See
9543 "SvIV_set".
9544
9545 void SvSTASH_set(SV* sv, HV* val)
9546
9547 SvTAINT Taints an SV if tainting is enabled, and if some input to the
9548 current expression is tainted--usually a variable, but possibly
9549 also implicit inputs such as locale settings. "SvTAINT"
9550 propagates that taintedness to the outputs of an expression in
9551 a pessimistic fashion; i.e., without paying attention to
9552 precisely which outputs are influenced by which inputs.
9553
9554 void SvTAINT(SV* sv)
9555
9556 SvTAINTED
9557 Checks to see if an SV is tainted. Returns TRUE if it is,
9558 FALSE if not.
9559
9560 bool SvTAINTED(SV* sv)
9561
9562 sv_tainted
9563 Test an SV for taintedness. Use "SvTAINTED" instead.
9564
9565 bool sv_tainted(SV *const sv)
9566
9567 SvTAINTED_off
9568 Untaints an SV. Be very careful with this routine, as it
9569 short-circuits some of Perl's fundamental security features.
9570 XS module authors should not use this function unless they
9571 fully understand all the implications of unconditionally
9572 untainting the value. Untainting should be done in the
9573 standard perl fashion, via a carefully crafted regexp, rather
9574 than directly untainting variables.
9575
9576 void SvTAINTED_off(SV* sv)
9577
9578 SvTAINTED_on
9579 Marks an SV as tainted if tainting is enabled.
9580
9581 void SvTAINTED_on(SV* sv)
9582
9583 SvTRUE Returns a boolean indicating whether Perl would evaluate the SV
9584 as true or false. See "SvOK" for a defined/undefined test.
9585 Handles 'get' magic unless the scalar is already "SvPOK",
9586 "SvIOK" or "SvNOK" (the public, not the private flags).
9587
9588 As of Perl 5.32, this is guaranteed to evaluate "sv" only once.
9589 Prior to that release, use "SvTRUEx" for single evaluation.
9590
9591 bool SvTRUE(SV* sv)
9592
9593 sv_true Returns true if the SV has a true value by Perl's rules. Use
9594 the "SvTRUE" macro instead, which may call "sv_true()" or may
9595 instead use an in-line version.
9596
9597 I32 sv_true(SV *const sv)
9598
9599 SvTRUE_nomg
9600 Returns a boolean indicating whether Perl would evaluate the SV
9601 as true or false. See "SvOK" for a defined/undefined test.
9602 Does not handle 'get' magic.
9603
9604 bool SvTRUE_nomg(SV* sv)
9605
9606 SvTRUEx Returns a boolean indicating whether Perl would evaluate the SV
9607 as true or false. See "SvOK" for a defined/undefined test.
9608 Handles 'get' magic unless the scalar is already "SvPOK",
9609 "SvIOK" or "SvNOK" (the public, not the private flags).
9610
9611 This form guarantees to evaluate "sv" only once. Only use this
9612 if "sv" is an expression with side effects, otherwise use the
9613 more efficient "SvTRUE".
9614
9615 bool SvTRUEx(SV* sv)
9616
9617 SvTYPE Returns the type of the SV. See "svtype".
9618
9619 svtype SvTYPE(SV* sv)
9620
9621 sv_unmagic
9622 Removes all magic of type "type" from an SV.
9623
9624 int sv_unmagic(SV *const sv, const int type)
9625
9626 sv_unmagicext
9627 Removes all magic of type "type" with the specified "vtbl" from
9628 an SV.
9629
9630 int sv_unmagicext(SV *const sv, const int type,
9631 MGVTBL *vtbl)
9632
9633 sv_unref_flags
9634 Unsets the RV status of the SV, and decrements the reference
9635 count of whatever was being referenced by the RV. This can
9636 almost be thought of as a reversal of "newSVrv". The "cflags"
9637 argument can contain "SV_IMMEDIATE_UNREF" to force the
9638 reference count to be decremented (otherwise the decrementing
9639 is conditional on the reference count being different from one
9640 or the reference being a readonly SV). See "SvROK_off".
9641
9642 void sv_unref_flags(SV *const ref, const U32 flags)
9643
9644 sv_untaint
9645 Untaint an SV. Use "SvTAINTED_off" instead.
9646
9647 void sv_untaint(SV *const sv)
9648
9649 SvUOK Returns a boolean indicating whether the SV contains an integer
9650 that must be interpreted as unsigned. A non-negative integer
9651 whose value is within the range of both an IV and a UV may be
9652 flagged as either "SvUOK" or "SvIOK".
9653
9654 bool SvUOK(SV* sv)
9655
9656 SvUPGRADE
9657 Used to upgrade an SV to a more complex form. Uses
9658 "sv_upgrade" to perform the upgrade if necessary. See
9659 "svtype".
9660
9661 void SvUPGRADE(SV* sv, svtype type)
9662
9663 sv_upgrade
9664 Upgrade an SV to a more complex form. Generally adds a new
9665 body type to the SV, then copies across as much information as
9666 possible from the old body. It croaks if the SV is already in
9667 a more complex form than requested. You generally want to use
9668 the "SvUPGRADE" macro wrapper, which checks the type before
9669 calling "sv_upgrade", and hence does not croak. See also
9670 "svtype".
9671
9672 void sv_upgrade(SV *const sv, svtype new_type)
9673
9674 sv_usepvn_flags
9675 Tells an SV to use "ptr" to find its string value. Normally
9676 the string is stored inside the SV, but sv_usepvn allows the SV
9677 to use an outside string. "ptr" should point to memory that
9678 was allocated by "Newx". It must be the start of a "Newx"-ed
9679 block of memory, and not a pointer to the middle of it (beware
9680 of "OOK" and copy-on-write), and not be from a non-"Newx"
9681 memory allocator like "malloc". The string length, "len", must
9682 be supplied. By default this function will "Renew" (i.e.
9683 realloc, move) the memory pointed to by "ptr", so that pointer
9684 should not be freed or used by the programmer after giving it
9685 to "sv_usepvn", and neither should any pointers from "behind"
9686 that pointer (e.g. ptr + 1) be used.
9687
9688 If "flags & SV_SMAGIC" is true, will call "SvSETMAGIC". If
9689 "flags & SV_HAS_TRAILING_NUL" is true, then "ptr[len]" must be
9690 "NUL", and the realloc will be skipped (i.e. the buffer is
9691 actually at least 1 byte longer than "len", and already meets
9692 the requirements for storing in "SvPVX").
9693
9694 void sv_usepvn_flags(SV *const sv, char* ptr,
9695 const STRLEN len,
9696 const U32 flags)
9697
9698 SvUTF8 Returns a U32 value indicating the UTF-8 status of an SV. If
9699 things are set-up properly, this indicates whether or not the
9700 SV contains UTF-8 encoded data. You should use this after a
9701 call to "SvPV()" or one of its variants, in case any call to
9702 string overloading updates the internal flag.
9703
9704 If you want to take into account the bytes pragma, use
9705 "DO_UTF8" instead.
9706
9707 U32 SvUTF8(SV* sv)
9708
9709 sv_utf8_decode
9710 If the PV of the SV is an octet sequence in Perl's extended
9711 UTF-8 and contains a multiple-byte character, the "SvUTF8" flag
9712 is turned on so that it looks like a character. If the PV
9713 contains only single-byte characters, the "SvUTF8" flag stays
9714 off. Scans PV for validity and returns FALSE if the PV is
9715 invalid UTF-8.
9716
9717 bool sv_utf8_decode(SV *const sv)
9718
9719 sv_utf8_downgrade
9720 Attempts to convert the PV of an SV from characters to bytes.
9721 If the PV contains a character that cannot fit in a byte, this
9722 conversion will fail; in this case, either returns false or, if
9723 "fail_ok" is not true, croaks.
9724
9725 This is not a general purpose Unicode to byte encoding
9726 interface: use the "Encode" extension for that.
9727
9728 This function process get magic on "sv".
9729
9730 bool sv_utf8_downgrade(SV *const sv,
9731 const bool fail_ok)
9732
9733 sv_utf8_downgrade_flags
9734 Like "sv_utf8_downgrade", but with additional "flags". If
9735 "flags" has "SV_GMAGIC" bit set, processes get magic on "sv".
9736
9737 bool sv_utf8_downgrade_flags(SV *const sv,
9738 const bool fail_ok,
9739 const U32 flags)
9740
9741 sv_utf8_downgrade_nomg
9742 Like "sv_utf8_downgrade", but does not process get magic on
9743 "sv".
9744
9745 bool sv_utf8_downgrade_nomg(SV *const sv,
9746 const bool fail_ok)
9747
9748 sv_utf8_encode
9749 Converts the PV of an SV to UTF-8, but then turns the "SvUTF8"
9750 flag off so that it looks like octets again.
9751
9752 void sv_utf8_encode(SV *const sv)
9753
9754 sv_utf8_upgrade
9755 Converts the PV of an SV to its UTF-8-encoded form. Forces the
9756 SV to string form if it is not already. Will "mg_get" on "sv"
9757 if appropriate. Always sets the "SvUTF8" flag to avoid future
9758 validity checks even if the whole string is the same in UTF-8
9759 as not. Returns the number of bytes in the converted string
9760
9761 This is not a general purpose byte encoding to Unicode
9762 interface: use the Encode extension for that.
9763
9764 STRLEN sv_utf8_upgrade(SV *sv)
9765
9766 sv_utf8_upgrade_flags
9767 Converts the PV of an SV to its UTF-8-encoded form. Forces the
9768 SV to string form if it is not already. Always sets the SvUTF8
9769 flag to avoid future validity checks even if all the bytes are
9770 invariant in UTF-8. If "flags" has "SV_GMAGIC" bit set, will
9771 "mg_get" on "sv" if appropriate, else not.
9772
9773 The "SV_FORCE_UTF8_UPGRADE" flag is now ignored.
9774
9775 Returns the number of bytes in the converted string.
9776
9777 This is not a general purpose byte encoding to Unicode
9778 interface: use the Encode extension for that.
9779
9780 STRLEN sv_utf8_upgrade_flags(SV *const sv,
9781 const I32 flags)
9782
9783 sv_utf8_upgrade_flags_grow
9784 Like "sv_utf8_upgrade_flags", but has an additional parameter
9785 "extra", which is the number of unused bytes the string of "sv"
9786 is guaranteed to have free after it upon return. This allows
9787 the caller to reserve extra space that it intends to fill, to
9788 avoid extra grows.
9789
9790 "sv_utf8_upgrade", "sv_utf8_upgrade_nomg", and
9791 "sv_utf8_upgrade_flags" are implemented in terms of this
9792 function.
9793
9794 Returns the number of bytes in the converted string (not
9795 including the spares).
9796
9797 STRLEN sv_utf8_upgrade_flags_grow(SV *const sv,
9798 const I32 flags,
9799 STRLEN extra)
9800
9801 sv_utf8_upgrade_nomg
9802 Like "sv_utf8_upgrade", but doesn't do magic on "sv".
9803
9804 STRLEN sv_utf8_upgrade_nomg(SV *sv)
9805
9806 SvUTF8_off
9807 Unsets the UTF-8 status of an SV (the data is not changed, just
9808 the flag). Do not use frivolously.
9809
9810 void SvUTF8_off(SV *sv)
9811
9812 SvUTF8_on
9813 Turn on the UTF-8 status of an SV (the data is not changed,
9814 just the flag). Do not use frivolously.
9815
9816 void SvUTF8_on(SV *sv)
9817
9818 SvUV Coerces the given SV to UV and returns it. The returned value
9819 in many circumstances will get stored in "sv"'s UV slot, but
9820 not in all cases. (Use "sv_setuv" to make sure it does).
9821
9822 See "SvUVx" for a version which guarantees to evaluate "sv"
9823 only once.
9824
9825 UV SvUV(SV* sv)
9826
9827 SvUV_nomg
9828 Like "SvUV" but doesn't process magic.
9829
9830 UV SvUV_nomg(SV* sv)
9831
9832 SvUV_set
9833 Set the value of the UV pointer in "sv" to val. See
9834 "SvIV_set".
9835
9836 void SvUV_set(SV* sv, UV val)
9837
9838 SvUVX Returns the raw value in the SV's UV slot, without checks or
9839 conversions. Only use when you are sure "SvIOK" is true. See
9840 also "SvUV".
9841
9842 UV SvUVX(SV* sv)
9843
9844 SvUVx Coerces the given SV to UV and returns it. The returned value
9845 in many circumstances will get stored in "sv"'s UV slot, but
9846 not in all cases. (Use "sv_setuv" to make sure it does).
9847
9848 This form guarantees to evaluate "sv" only once. Only use this
9849 if "sv" is an expression with side effects, otherwise use the
9850 more efficient "SvUV".
9851
9852 UV SvUVx(SV* sv)
9853
9854 SvUVXx DEPRECATED! It is planned to remove this function from a
9855 future release of Perl. Do not use it for new code; remove it
9856 from existing code.
9857
9858 This is an unnecessary synonym for "SvUVX"
9859
9860 UV SvUVXx(SV* sv)
9861
9862 sv_vcatpvf
9863 Processes its arguments like "sv_vcatpvfn" called with a non-
9864 null C-style variable argument list, and appends the formatted
9865 output to an SV. Does not handle 'set' magic. See
9866 "sv_vcatpvf_mg".
9867
9868 Usually used via its frontend "sv_catpvf".
9869
9870 void sv_vcatpvf(SV *const sv, const char *const pat,
9871 va_list *const args)
9872
9873 sv_vcatpvfn
9874 void sv_vcatpvfn(SV *const sv, const char *const pat,
9875 const STRLEN patlen,
9876 va_list *const args,
9877 SV **const svargs,
9878 const Size_t sv_count,
9879 bool *const maybe_tainted)
9880
9881 sv_vcatpvfn_flags
9882 Processes its arguments like "vsprintf" and appends the
9883 formatted output to an SV. Uses an array of SVs if the C-style
9884 variable argument list is missing ("NULL"). Argument reordering
9885 (using format specifiers like "%2$d" or "%*2$d") is supported
9886 only when using an array of SVs; using a C-style "va_list"
9887 argument list with a format string that uses argument
9888 reordering will yield an exception.
9889
9890 When running with taint checks enabled, indicates via
9891 "maybe_tainted" if results are untrustworthy (often due to the
9892 use of locales).
9893
9894 If called as "sv_vcatpvfn" or flags has the "SV_GMAGIC" bit
9895 set, calls get magic.
9896
9897 It assumes that pat has the same utf8-ness as sv. It's the
9898 caller's responsibility to ensure that this is so.
9899
9900 Usually used via one of its frontends "sv_vcatpvf" and
9901 "sv_vcatpvf_mg".
9902
9903 void sv_vcatpvfn_flags(SV *const sv,
9904 const char *const pat,
9905 const STRLEN patlen,
9906 va_list *const args,
9907 SV **const svargs,
9908 const Size_t sv_count,
9909 bool *const maybe_tainted,
9910 const U32 flags)
9911
9912 sv_vcatpvf_mg
9913 Like "sv_vcatpvf", but also handles 'set' magic.
9914
9915 Usually used via its frontend "sv_catpvf_mg".
9916
9917 void sv_vcatpvf_mg(SV *const sv,
9918 const char *const pat,
9919 va_list *const args)
9920
9921 SvVOK Returns a boolean indicating whether the SV contains a
9922 v-string.
9923
9924 bool SvVOK(SV* sv)
9925
9926 sv_vsetpvf
9927 Works like "sv_vcatpvf" but copies the text into the SV instead
9928 of appending it. Does not handle 'set' magic. See
9929 "sv_vsetpvf_mg".
9930
9931 Usually used via its frontend "sv_setpvf".
9932
9933 void sv_vsetpvf(SV *const sv, const char *const pat,
9934 va_list *const args)
9935
9936 sv_vsetpvfn
9937 Works like "sv_vcatpvfn" but copies the text into the SV
9938 instead of appending it.
9939
9940 Usually used via one of its frontends "sv_vsetpvf" and
9941 "sv_vsetpvf_mg".
9942
9943 void sv_vsetpvfn(SV *const sv, const char *const pat,
9944 const STRLEN patlen,
9945 va_list *const args,
9946 SV **const svargs,
9947 const Size_t sv_count,
9948 bool *const maybe_tainted)
9949
9950 sv_vsetpvf_mg
9951 Like "sv_vsetpvf", but also handles 'set' magic.
9952
9953 Usually used via its frontend "sv_setpvf_mg".
9954
9955 void sv_vsetpvf_mg(SV *const sv,
9956 const char *const pat,
9957 va_list *const args)
9958
9960 "Unicode Support" in perlguts has an introduction to this API.
9961
9962 See also "Character classification", and "Character case changing".
9963 Various functions outside this section also work specially with
9964 Unicode. Search for the string "utf8" in this document.
9965
9966 BOM_UTF8
9967 This is a macro that evaluates to a string constant of the
9968 UTF-8 bytes that define the Unicode BYTE ORDER MARK (U+FEFF)
9969 for the platform that perl is compiled on. This allows code to
9970 use a mnemonic for this character that works on both ASCII and
9971 EBCDIC platforms. "sizeof(BOM_UTF8) - 1" can be used to get
9972 its length in bytes.
9973
9974 bytes_cmp_utf8
9975 Compares the sequence of characters (stored as octets) in "b",
9976 "blen" with the sequence of characters (stored as UTF-8) in
9977 "u", "ulen". Returns 0 if they are equal, -1 or -2 if the
9978 first string is less than the second string, +1 or +2 if the
9979 first string is greater than the second string.
9980
9981 -1 or +1 is returned if the shorter string was identical to the
9982 start of the longer string. -2 or +2 is returned if there was
9983 a difference between characters within the strings.
9984
9985 int bytes_cmp_utf8(const U8 *b, STRLEN blen,
9986 const U8 *u, STRLEN ulen)
9987
9988 bytes_from_utf8
9989 NOTE: this function is experimental and may change or be
9990 removed without notice.
9991
9992 Converts a potentially UTF-8 encoded string "s" of length *lenp
9993 into native byte encoding. On input, the boolean *is_utf8p
9994 gives whether or not "s" is actually encoded in UTF-8.
9995
9996 Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-
9997 destructive of the input string.
9998
9999 Do nothing if *is_utf8p is 0, or if there are code points in
10000 the string not expressible in native byte encoding. In these
10001 cases, *is_utf8p and *lenp are unchanged, and the return value
10002 is the original "s".
10003
10004 Otherwise, *is_utf8p is set to 0, and the return value is a
10005 pointer to a newly created string containing a downgraded copy
10006 of "s", and whose length is returned in *lenp, updated. The
10007 new string is "NUL"-terminated. The caller is responsible for
10008 arranging for the memory used by this string to get freed.
10009
10010 Upon successful return, the number of variants in the string
10011 can be computed by having saved the value of *lenp before the
10012 call, and subtracting the after-call value of *lenp from it.
10013
10014 U8* bytes_from_utf8(const U8 *s, STRLEN *lenp,
10015 bool *is_utf8p)
10016
10017 bytes_to_utf8
10018 NOTE: this function is experimental and may change or be
10019 removed without notice.
10020
10021 Converts a string "s" of length *lenp bytes from the native
10022 encoding into UTF-8. Returns a pointer to the newly-created
10023 string, and sets *lenp to reflect the new length in bytes. The
10024 caller is responsible for arranging for the memory used by this
10025 string to get freed.
10026
10027 Upon successful return, the number of variants in the string
10028 can be computed by having saved the value of *lenp before the
10029 call, and subtracting it from the after-call value of *lenp.
10030
10031 A "NUL" character will be written after the end of the string.
10032
10033 If you want to convert to UTF-8 from encodings other than the
10034 native (Latin1 or EBCDIC), see "sv_recode_to_utf8"().
10035
10036 U8* bytes_to_utf8(const U8 *s, STRLEN *lenp)
10037
10038 DO_UTF8 Returns a bool giving whether or not the PV in "sv" is to be
10039 treated as being encoded in UTF-8.
10040
10041 You should use this after a call to "SvPV()" or one of its
10042 variants, in case any call to string overloading updates the
10043 internal UTF-8 encoding flag.
10044
10045 bool DO_UTF8(SV* sv)
10046
10047 foldEQ_utf8
10048 Returns true if the leading portions of the strings "s1" and
10049 "s2" (either or both of which may be in UTF-8) are the same
10050 case-insensitively; false otherwise. How far into the strings
10051 to compare is determined by other input parameters.
10052
10053 If "u1" is true, the string "s1" is assumed to be in
10054 UTF-8-encoded Unicode; otherwise it is assumed to be in native
10055 8-bit encoding. Correspondingly for "u2" with respect to "s2".
10056
10057 If the byte length "l1" is non-zero, it says how far into "s1"
10058 to check for fold equality. In other words, "s1"+"l1" will be
10059 used as a goal to reach. The scan will not be considered to be
10060 a match unless the goal is reached, and scanning won't continue
10061 past that goal. Correspondingly for "l2" with respect to "s2".
10062
10063 If "pe1" is non-"NULL" and the pointer it points to is not
10064 "NULL", that pointer is considered an end pointer to the
10065 position 1 byte past the maximum point in "s1" beyond which
10066 scanning will not continue under any circumstances. (This
10067 routine assumes that UTF-8 encoded input strings are not
10068 malformed; malformed input can cause it to read past "pe1").
10069 This means that if both "l1" and "pe1" are specified, and "pe1"
10070 is less than "s1"+"l1", the match will never be successful
10071 because it can never get as far as its goal (and in fact is
10072 asserted against). Correspondingly for "pe2" with respect to
10073 "s2".
10074
10075 At least one of "s1" and "s2" must have a goal (at least one of
10076 "l1" and "l2" must be non-zero), and if both do, both have to
10077 be reached for a successful match. Also, if the fold of a
10078 character is multiple characters, all of them must be matched
10079 (see tr21 reference below for 'folding').
10080
10081 Upon a successful match, if "pe1" is non-"NULL", it will be set
10082 to point to the beginning of the next character of "s1" beyond
10083 what was matched. Correspondingly for "pe2" and "s2".
10084
10085 For case-insensitiveness, the "casefolding" of Unicode is used
10086 instead of upper/lowercasing both the characters, see
10087 <https://www.unicode.org/unicode/reports/tr21/> (Case
10088 Mappings).
10089
10090 I32 foldEQ_utf8(const char *s1, char **pe1, UV l1,
10091 bool u1, const char *s2, char **pe2,
10092 UV l2, bool u2)
10093
10094 is_ascii_string
10095 This is a misleadingly-named synonym for
10096 "is_utf8_invariant_string". On ASCII-ish platforms, the name
10097 isn't misleading: the ASCII-range characters are exactly the
10098 UTF-8 invariants. But EBCDIC machines have more invariants
10099 than just the ASCII characters, so "is_utf8_invariant_string"
10100 is preferred.
10101
10102 bool is_ascii_string(const U8* const s, STRLEN len)
10103
10104 is_c9strict_utf8_string
10105 Returns TRUE if the first "len" bytes of string "s" form a
10106 valid UTF-8-encoded string that conforms to Unicode Corrigendum
10107 #9 <http://www.unicode.org/versions/corrigendum9.html>;
10108 otherwise it returns FALSE. If "len" is 0, it will be
10109 calculated using strlen(s) (which means if you use this option,
10110 that "s" can't have embedded "NUL" characters and has to have a
10111 terminating "NUL" byte). Note that all characters being ASCII
10112 constitute 'a valid UTF-8 string'.
10113
10114 This function returns FALSE for strings containing any code
10115 points above the Unicode max of 0x10FFFF or surrogate code
10116 points, but accepts non-character code points per Corrigendum
10117 #9 <http://www.unicode.org/versions/corrigendum9.html>.
10118
10119 See also "is_utf8_invariant_string",
10120 "is_utf8_invariant_string_loc", "is_utf8_string",
10121 "is_utf8_string_flags", "is_utf8_string_loc",
10122 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
10123 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
10124 "is_utf8_fixed_width_buf_loc_flags",
10125 "is_utf8_fixed_width_buf_loclen_flags",
10126 "is_strict_utf8_string", "is_strict_utf8_string_loc",
10127 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string_loc",
10128 and "is_c9strict_utf8_string_loclen".
10129
10130 bool is_c9strict_utf8_string(const U8 *s, STRLEN len)
10131
10132 is_c9strict_utf8_string_loc
10133 Like "is_c9strict_utf8_string" but stores the location of the
10134 failure (in the case of "utf8ness failure") or the location
10135 "s"+"len" (in the case of "utf8ness success") in the "ep"
10136 pointer.
10137
10138 See also "is_c9strict_utf8_string_loclen".
10139
10140 bool is_c9strict_utf8_string_loc(const U8 *s,
10141 STRLEN len,
10142 const U8 **ep)
10143
10144 is_c9strict_utf8_string_loclen
10145 Like "is_c9strict_utf8_string" but stores the location of the
10146 failure (in the case of "utf8ness failure") or the location
10147 "s"+"len" (in the case of "utf8ness success") in the "ep"
10148 pointer, and the number of UTF-8 encoded characters in the "el"
10149 pointer.
10150
10151 See also "is_c9strict_utf8_string_loc".
10152
10153 bool is_c9strict_utf8_string_loclen(const U8 *s,
10154 STRLEN len,
10155 const U8 **ep,
10156 STRLEN *el)
10157
10158 isC9_STRICT_UTF8_CHAR
10159 Evaluates to non-zero if the first few bytes of the string
10160 starting at "s" and looking no further than "e - 1" are well-
10161 formed UTF-8 that represents some Unicode non-surrogate code
10162 point; otherwise it evaluates to 0. If non-zero, the value
10163 gives how many bytes starting at "s" comprise the code point's
10164 representation. Any bytes remaining before "e", but beyond the
10165 ones needed to form the first code point in "s", are not
10166 examined.
10167
10168 The largest acceptable code point is the Unicode maximum
10169 0x10FFFF. This differs from "isSTRICT_UTF8_CHAR" only in that
10170 it accepts non-character code points. This corresponds to
10171 Unicode Corrigendum #9
10172 <http://www.unicode.org/versions/corrigendum9.html>. which
10173 said that non-character code points are merely discouraged
10174 rather than completely forbidden in open interchange. See
10175 "Noncharacter code points" in perlunicode.
10176
10177 Use "isUTF8_CHAR" to check for Perl's extended UTF-8; and
10178 "isUTF8_CHAR_flags" for a more customized definition.
10179
10180 Use "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc",
10181 and "is_c9strict_utf8_string_loclen" to check entire strings.
10182
10183 Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
10184 const U8 * const e)
10185
10186 is_invariant_string
10187 This is a somewhat misleadingly-named synonym for
10188 "is_utf8_invariant_string". "is_utf8_invariant_string" is
10189 preferred, as it indicates under what conditions the string is
10190 invariant.
10191
10192 bool is_invariant_string(const U8* const s,
10193 STRLEN len)
10194
10195 isSTRICT_UTF8_CHAR
10196 Evaluates to non-zero if the first few bytes of the string
10197 starting at "s" and looking no further than "e - 1" are well-
10198 formed UTF-8 that represents some Unicode code point completely
10199 acceptable for open interchange between all applications;
10200 otherwise it evaluates to 0. If non-zero, the value gives how
10201 many bytes starting at "s" comprise the code point's
10202 representation. Any bytes remaining before "e", but beyond the
10203 ones needed to form the first code point in "s", are not
10204 examined.
10205
10206 The largest acceptable code point is the Unicode maximum
10207 0x10FFFF, and must not be a surrogate nor a non-character code
10208 point. Thus this excludes any code point from Perl's extended
10209 UTF-8.
10210
10211 This is used to efficiently decide if the next few bytes in "s"
10212 is legal Unicode-acceptable UTF-8 for a single character.
10213
10214 Use "isC9_STRICT_UTF8_CHAR" to use the Unicode Corrigendum #9
10215 <http://www.unicode.org/versions/corrigendum9.html> definition
10216 of allowable code points; "isUTF8_CHAR" to check for Perl's
10217 extended UTF-8; and "isUTF8_CHAR_flags" for a more customized
10218 definition.
10219
10220 Use "is_strict_utf8_string", "is_strict_utf8_string_loc", and
10221 "is_strict_utf8_string_loclen" to check entire strings.
10222
10223 Size_t isSTRICT_UTF8_CHAR(const U8 * const s0,
10224 const U8 * const e)
10225
10226 is_strict_utf8_string
10227 Returns TRUE if the first "len" bytes of string "s" form a
10228 valid UTF-8-encoded string that is fully interchangeable by any
10229 application using Unicode rules; otherwise it returns FALSE.
10230 If "len" is 0, it will be calculated using strlen(s) (which
10231 means if you use this option, that "s" can't have embedded
10232 "NUL" characters and has to have a terminating "NUL" byte).
10233 Note that all characters being ASCII constitute 'a valid UTF-8
10234 string'.
10235
10236 This function returns FALSE for strings containing any code
10237 points above the Unicode max of 0x10FFFF, surrogate code
10238 points, or non-character code points.
10239
10240 See also "is_utf8_invariant_string",
10241 "is_utf8_invariant_string_loc", "is_utf8_string",
10242 "is_utf8_string_flags", "is_utf8_string_loc",
10243 "is_utf8_string_loc_flags", "is_utf8_string_loclen",
10244 "is_utf8_string_loclen_flags", "is_utf8_fixed_width_buf_flags",
10245 "is_utf8_fixed_width_buf_loc_flags",
10246 "is_utf8_fixed_width_buf_loclen_flags",
10247 "is_strict_utf8_string_loc", "is_strict_utf8_string_loclen",
10248 "is_c9strict_utf8_string", "is_c9strict_utf8_string_loc", and
10249 "is_c9strict_utf8_string_loclen".
10250
10251 bool is_strict_utf8_string(const U8 *s, STRLEN len)
10252
10253 is_strict_utf8_string_loc
10254 Like "is_strict_utf8_string" but stores the location of the
10255 failure (in the case of "utf8ness failure") or the location
10256 "s"+"len" (in the case of "utf8ness success") in the "ep"
10257 pointer.
10258
10259 See also "is_strict_utf8_string_loclen".
10260
10261 bool is_strict_utf8_string_loc(const U8 *s,
10262 STRLEN len,
10263 const U8 **ep)
10264
10265 is_strict_utf8_string_loclen
10266 Like "is_strict_utf8_string" but stores the location of the
10267 failure (in the case of "utf8ness failure") or the location
10268 "s"+"len" (in the case of "utf8ness success") in the "ep"
10269 pointer, and the number of UTF-8 encoded characters in the "el"
10270 pointer.
10271
10272 See also "is_strict_utf8_string_loc".
10273
10274 bool is_strict_utf8_string_loclen(const U8 *s,
10275 STRLEN len,
10276 const U8 **ep,
10277 STRLEN *el)
10278
10279 is_utf8_fixed_width_buf_flags
10280 Returns TRUE if the fixed-width buffer starting at "s" with
10281 length "len" is entirely valid UTF-8, subject to the
10282 restrictions given by "flags"; otherwise it returns FALSE.
10283
10284 If "flags" is 0, any well-formed UTF-8, as extended by Perl, is
10285 accepted without restriction. If the final few bytes of the
10286 buffer do not form a complete code point, this will return TRUE
10287 anyway, provided that "is_utf8_valid_partial_char_flags"
10288 returns TRUE for them.
10289
10290 If "flags" in non-zero, it can be any combination of the
10291 "UTF8_DISALLOW_foo" flags accepted by "utf8n_to_uvchr", and
10292 with the same meanings.
10293
10294 This function differs from "is_utf8_string_flags" only in that
10295 the latter returns FALSE if the final few bytes of the string
10296 don't form a complete code point.
10297
10298 bool is_utf8_fixed_width_buf_flags(
10299 const U8 * const s, STRLEN len,
10300 const U32 flags
10301 )
10302
10303 is_utf8_fixed_width_buf_loclen_flags
10304 Like "is_utf8_fixed_width_buf_loc_flags" but stores the number
10305 of complete, valid characters found in the "el" pointer.
10306
10307 bool is_utf8_fixed_width_buf_loclen_flags(
10308 const U8 * const s, STRLEN len,
10309 const U8 **ep, STRLEN *el, const U32 flags
10310 )
10311
10312 is_utf8_fixed_width_buf_loc_flags
10313 Like "is_utf8_fixed_width_buf_flags" but stores the location of
10314 the failure in the "ep" pointer. If the function returns TRUE,
10315 *ep will point to the beginning of any partial character at the
10316 end of the buffer; if there is no partial character *ep will
10317 contain "s"+"len".
10318
10319 See also "is_utf8_fixed_width_buf_loclen_flags".
10320
10321 bool is_utf8_fixed_width_buf_loc_flags(
10322 const U8 * const s, STRLEN len,
10323 const U8 **ep, const U32 flags
10324 )
10325
10326 is_utf8_invariant_string
10327 Returns TRUE if the first "len" bytes of the string "s" are the
10328 same regardless of the UTF-8 encoding of the string (or UTF-
10329 EBCDIC encoding on EBCDIC machines); otherwise it returns
10330 FALSE. That is, it returns TRUE if they are UTF-8 invariant.
10331 On ASCII-ish machines, all the ASCII characters and only the
10332 ASCII characters fit this definition. On EBCDIC machines, the
10333 ASCII-range characters are invariant, but so also are the C1
10334 controls.
10335
10336 If "len" is 0, it will be calculated using strlen(s), (which
10337 means if you use this option, that "s" can't have embedded
10338 "NUL" characters and has to have a terminating "NUL" byte).
10339
10340 See also "is_utf8_string", "is_utf8_string_flags",
10341 "is_utf8_string_loc", "is_utf8_string_loc_flags",
10342 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
10343 "is_utf8_fixed_width_buf_flags",
10344 "is_utf8_fixed_width_buf_loc_flags",
10345 "is_utf8_fixed_width_buf_loclen_flags",
10346 "is_strict_utf8_string", "is_strict_utf8_string_loc",
10347 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
10348 "is_c9strict_utf8_string_loc", and
10349 "is_c9strict_utf8_string_loclen".
10350
10351 bool is_utf8_invariant_string(const U8* const s,
10352 STRLEN len)
10353
10354 is_utf8_invariant_string_loc
10355 Like "is_utf8_invariant_string" but upon failure, stores the
10356 location of the first UTF-8 variant character in the "ep"
10357 pointer; if all characters are UTF-8 invariant, this function
10358 does not change the contents of *ep.
10359
10360 bool is_utf8_invariant_string_loc(const U8* const s,
10361 STRLEN len,
10362 const U8 ** ep)
10363
10364 is_utf8_string
10365 Returns TRUE if the first "len" bytes of string "s" form a
10366 valid Perl-extended-UTF-8 string; returns FALSE otherwise. If
10367 "len" is 0, it will be calculated using strlen(s) (which means
10368 if you use this option, that "s" can't have embedded "NUL"
10369 characters and has to have a terminating "NUL" byte). Note
10370 that all characters being ASCII constitute 'a valid UTF-8
10371 string'.
10372
10373 This function considers Perl's extended UTF-8 to be valid.
10374 That means that code points above Unicode, surrogates, and non-
10375 character code points are considered valid by this function.
10376 Use "is_strict_utf8_string", "is_c9strict_utf8_string", or
10377 "is_utf8_string_flags" to restrict what code points are
10378 considered valid.
10379
10380 See also "is_utf8_invariant_string",
10381 "is_utf8_invariant_string_loc", "is_utf8_string_loc",
10382 "is_utf8_string_loclen", "is_utf8_fixed_width_buf_flags",
10383 "is_utf8_fixed_width_buf_loc_flags",
10384 "is_utf8_fixed_width_buf_loclen_flags",
10385
10386 bool is_utf8_string(const U8 *s, STRLEN len)
10387
10388 is_utf8_string_flags
10389 Returns TRUE if the first "len" bytes of string "s" form a
10390 valid UTF-8 string, subject to the restrictions imposed by
10391 "flags"; returns FALSE otherwise. If "len" is 0, it will be
10392 calculated using strlen(s) (which means if you use this option,
10393 that "s" can't have embedded "NUL" characters and has to have a
10394 terminating "NUL" byte). Note that all characters being ASCII
10395 constitute 'a valid UTF-8 string'.
10396
10397 If "flags" is 0, this gives the same results as
10398 "is_utf8_string"; if "flags" is
10399 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives the same
10400 results as "is_strict_utf8_string"; and if "flags" is
10401 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
10402 results as "is_c9strict_utf8_string". Otherwise "flags" may be
10403 any combination of the "UTF8_DISALLOW_foo" flags understood by
10404 "utf8n_to_uvchr", with the same meanings.
10405
10406 See also "is_utf8_invariant_string",
10407 "is_utf8_invariant_string_loc", "is_utf8_string",
10408 "is_utf8_string_loc", "is_utf8_string_loc_flags",
10409 "is_utf8_string_loclen", "is_utf8_string_loclen_flags",
10410 "is_utf8_fixed_width_buf_flags",
10411 "is_utf8_fixed_width_buf_loc_flags",
10412 "is_utf8_fixed_width_buf_loclen_flags",
10413 "is_strict_utf8_string", "is_strict_utf8_string_loc",
10414 "is_strict_utf8_string_loclen", "is_c9strict_utf8_string",
10415 "is_c9strict_utf8_string_loc", and
10416 "is_c9strict_utf8_string_loclen".
10417
10418 bool is_utf8_string_flags(const U8 *s, STRLEN len,
10419 const U32 flags)
10420
10421 is_utf8_string_loc
10422 Like "is_utf8_string" but stores the location of the failure
10423 (in the case of "utf8ness failure") or the location "s"+"len"
10424 (in the case of "utf8ness success") in the "ep" pointer.
10425
10426 See also "is_utf8_string_loclen".
10427
10428 bool is_utf8_string_loc(const U8 *s,
10429 const STRLEN len,
10430 const U8 **ep)
10431
10432 is_utf8_string_loclen
10433 Like "is_utf8_string" but stores the location of the failure
10434 (in the case of "utf8ness failure") or the location "s"+"len"
10435 (in the case of "utf8ness success") in the "ep" pointer, and
10436 the number of UTF-8 encoded characters in the "el" pointer.
10437
10438 See also "is_utf8_string_loc".
10439
10440 bool is_utf8_string_loclen(const U8 *s, STRLEN len,
10441 const U8 **ep, STRLEN *el)
10442
10443 is_utf8_string_loclen_flags
10444 Like "is_utf8_string_flags" but stores the location of the
10445 failure (in the case of "utf8ness failure") or the location
10446 "s"+"len" (in the case of "utf8ness success") in the "ep"
10447 pointer, and the number of UTF-8 encoded characters in the "el"
10448 pointer.
10449
10450 See also "is_utf8_string_loc_flags".
10451
10452 bool is_utf8_string_loclen_flags(const U8 *s,
10453 STRLEN len,
10454 const U8 **ep,
10455 STRLEN *el,
10456 const U32 flags)
10457
10458 is_utf8_string_loc_flags
10459 Like "is_utf8_string_flags" but stores the location of the
10460 failure (in the case of "utf8ness failure") or the location
10461 "s"+"len" (in the case of "utf8ness success") in the "ep"
10462 pointer.
10463
10464 See also "is_utf8_string_loclen_flags".
10465
10466 bool is_utf8_string_loc_flags(const U8 *s,
10467 STRLEN len,
10468 const U8 **ep,
10469 const U32 flags)
10470
10471 is_utf8_valid_partial_char
10472 Returns 0 if the sequence of bytes starting at "s" and looking
10473 no further than "e - 1" is the UTF-8 encoding, as extended by
10474 Perl, for one or more code points. Otherwise, it returns 1 if
10475 there exists at least one non-empty sequence of bytes that when
10476 appended to sequence "s", starting at position "e" causes the
10477 entire sequence to be the well-formed UTF-8 of some code point;
10478 otherwise returns 0.
10479
10480 In other words this returns TRUE if "s" points to a partial
10481 UTF-8-encoded code point.
10482
10483 This is useful when a fixed-length buffer is being tested for
10484 being well-formed UTF-8, but the final few bytes in it don't
10485 comprise a full character; that is, it is split somewhere in
10486 the middle of the final code point's UTF-8 representation.
10487 (Presumably when the buffer is refreshed with the next chunk of
10488 data, the new first bytes will complete the partial code
10489 point.) This function is used to verify that the final bytes
10490 in the current buffer are in fact the legal beginning of some
10491 code point, so that if they aren't, the failure can be
10492 signalled without having to wait for the next read.
10493
10494 bool is_utf8_valid_partial_char(const U8 * const s,
10495 const U8 * const e)
10496
10497 is_utf8_valid_partial_char_flags
10498 Like "is_utf8_valid_partial_char", it returns a boolean giving
10499 whether or not the input is a valid UTF-8 encoded partial
10500 character, but it takes an extra parameter, "flags", which can
10501 further restrict which code points are considered valid.
10502
10503 If "flags" is 0, this behaves identically to
10504 "is_utf8_valid_partial_char". Otherwise "flags" can be any
10505 combination of the "UTF8_DISALLOW_foo" flags accepted by
10506 "utf8n_to_uvchr". If there is any sequence of bytes that can
10507 complete the input partial character in such a way that a non-
10508 prohibited character is formed, the function returns TRUE;
10509 otherwise FALSE. Non character code points cannot be
10510 determined based on partial character input. But many of the
10511 other possible excluded types can be determined from just the
10512 first one or two bytes.
10513
10514 bool is_utf8_valid_partial_char_flags(
10515 const U8 * const s, const U8 * const e,
10516 const U32 flags
10517 )
10518
10519 isUTF8_CHAR
10520 Evaluates to non-zero if the first few bytes of the string
10521 starting at "s" and looking no further than "e - 1" are well-
10522 formed UTF-8, as extended by Perl, that represents some code
10523 point; otherwise it evaluates to 0. If non-zero, the value
10524 gives how many bytes starting at "s" comprise the code point's
10525 representation. Any bytes remaining before "e", but beyond the
10526 ones needed to form the first code point in "s", are not
10527 examined.
10528
10529 The code point can be any that will fit in an IV on this
10530 machine, using Perl's extension to official UTF-8 to represent
10531 those higher than the Unicode maximum of 0x10FFFF. That means
10532 that this macro is used to efficiently decide if the next few
10533 bytes in "s" is legal UTF-8 for a single character.
10534
10535 Use "isSTRICT_UTF8_CHAR" to restrict the acceptable code points
10536 to those defined by Unicode to be fully interchangeable across
10537 applications; "isC9_STRICT_UTF8_CHAR" to use the Unicode
10538 Corrigendum #9
10539 <http://www.unicode.org/versions/corrigendum9.html> definition
10540 of allowable code points; and "isUTF8_CHAR_flags" for a more
10541 customized definition.
10542
10543 Use "is_utf8_string", "is_utf8_string_loc", and
10544 "is_utf8_string_loclen" to check entire strings.
10545
10546 Note also that a UTF-8 "invariant" character (i.e. ASCII on
10547 non-EBCDIC machines) is a valid UTF-8 character.
10548
10549 Size_t isUTF8_CHAR(const U8 * const s0,
10550 const U8 * const e)
10551
10552 isUTF8_CHAR_flags
10553 Evaluates to non-zero if the first few bytes of the string
10554 starting at "s" and looking no further than "e - 1" are well-
10555 formed UTF-8, as extended by Perl, that represents some code
10556 point, subject to the restrictions given by "flags"; otherwise
10557 it evaluates to 0. If non-zero, the value gives how many bytes
10558 starting at "s" comprise the code point's representation. Any
10559 bytes remaining before "e", but beyond the ones needed to form
10560 the first code point in "s", are not examined.
10561
10562 If "flags" is 0, this gives the same results as "isUTF8_CHAR";
10563 if "flags" is "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", this gives
10564 the same results as "isSTRICT_UTF8_CHAR"; and if "flags" is
10565 "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE", this gives the same
10566 results as "isC9_STRICT_UTF8_CHAR". Otherwise "flags" may be
10567 any combination of the "UTF8_DISALLOW_foo" flags understood by
10568 "utf8n_to_uvchr", with the same meanings.
10569
10570 The three alternative macros are for the most commonly needed
10571 validations; they are likely to run somewhat faster than this
10572 more general one, as they can be inlined into your code.
10573
10574 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
10575 "is_utf8_string_loclen_flags" to check entire strings.
10576
10577 STRLEN isUTF8_CHAR_flags(const U8 *s, const U8 *e,
10578 const U32 flags)
10579
10580 LATIN1_TO_NATIVE
10581 Returns the native equivalent of the input Latin-1 code point
10582 (including ASCII and control characters) given by "ch". Thus,
10583 "LATIN1_TO_NATIVE(66)" on EBCDIC platforms returns 194. These
10584 each represent the character "B" on their respective platforms.
10585 On ASCII platforms no conversion is needed, so this macro
10586 expands to just its input, adding no time nor space
10587 requirements to the implementation.
10588
10589 For conversion of code points potentially larger than will fit
10590 in a character, use "UNI_TO_NATIVE".
10591
10592 U8 LATIN1_TO_NATIVE(U8 ch)
10593
10594 NATIVE_TO_LATIN1
10595 Returns the Latin-1 (including ASCII and control characters)
10596 equivalent of the input native code point given by "ch". Thus,
10597 "NATIVE_TO_LATIN1(193)" on EBCDIC platforms returns 65. These
10598 each represent the character "A" on their respective platforms.
10599 On ASCII platforms no conversion is needed, so this macro
10600 expands to just its input, adding no time nor space
10601 requirements to the implementation.
10602
10603 For conversion of code points potentially larger than will fit
10604 in a character, use "NATIVE_TO_UNI".
10605
10606 U8 NATIVE_TO_LATIN1(U8 ch)
10607
10608 NATIVE_TO_UNI
10609 Returns the Unicode equivalent of the input native code point
10610 given by "ch". Thus, "NATIVE_TO_UNI(195)" on EBCDIC platforms
10611 returns 67. These each represent the character "C" on their
10612 respective platforms. On ASCII platforms no conversion is
10613 needed, so this macro expands to just its input, adding no time
10614 nor space requirements to the implementation.
10615
10616 UV NATIVE_TO_UNI(UV ch)
10617
10618 pv_uni_display
10619 Build to the scalar "dsv" a displayable version of the UTF-8
10620 encoded string "spv", length "len", the displayable version
10621 being at most "pvlim" bytes long (if longer, the rest is
10622 truncated and "..." will be appended).
10623
10624 The "flags" argument can have "UNI_DISPLAY_ISPRINT" set to
10625 display "isPRINT()"able characters as themselves,
10626 "UNI_DISPLAY_BACKSLASH" to display the "\\[nrfta\\]" as the
10627 backslashed versions (like "\n") ("UNI_DISPLAY_BACKSLASH" is
10628 preferred over "UNI_DISPLAY_ISPRINT" for "\\").
10629 "UNI_DISPLAY_QQ" (and its alias "UNI_DISPLAY_REGEX") have both
10630 "UNI_DISPLAY_BACKSLASH" and "UNI_DISPLAY_ISPRINT" turned on.
10631
10632 Additionally, there is now "UNI_DISPLAY_BACKSPACE" which allows
10633 "\b" for a backspace, but only when "UNI_DISPLAY_BACKSLASH"
10634 also is set.
10635
10636 The pointer to the PV of the "dsv" is returned.
10637
10638 See also "sv_uni_display".
10639
10640 char* pv_uni_display(SV *dsv, const U8 *spv,
10641 STRLEN len, STRLEN pvlim,
10642 UV flags)
10643
10644 REPLACEMENT_CHARACTER_UTF8
10645 This is a macro that evaluates to a string constant of the
10646 UTF-8 bytes that define the Unicode REPLACEMENT CHARACTER
10647 (U+FFFD) for the platform that perl is compiled on. This
10648 allows code to use a mnemonic for this character that works on
10649 both ASCII and EBCDIC platforms.
10650 "sizeof(REPLACEMENT_CHARACTER_UTF8) - 1" can be used to get its
10651 length in bytes.
10652
10653 sv_cat_decode
10654 "encoding" is assumed to be an "Encode" object, the PV of "ssv"
10655 is assumed to be octets in that encoding and decoding the input
10656 starts from the position which "(PV + *offset)" pointed to.
10657 "dsv" will be concatenated with the decoded UTF-8 string from
10658 "ssv". Decoding will terminate when the string "tstr" appears
10659 in decoding output or the input ends on the PV of "ssv". The
10660 value which "offset" points will be modified to the last input
10661 position on "ssv".
10662
10663 Returns TRUE if the terminator was found, else returns FALSE.
10664
10665 bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv,
10666 int *offset, char* tstr, int tlen)
10667
10668 sv_recode_to_utf8
10669 "encoding" is assumed to be an "Encode" object, on entry the PV
10670 of "sv" is assumed to be octets in that encoding, and "sv" will
10671 be converted into Unicode (and UTF-8).
10672
10673 If "sv" already is UTF-8 (or if it is not "POK"), or if
10674 "encoding" is not a reference, nothing is done to "sv". If
10675 "encoding" is not an "Encode::XS" Encoding object, bad things
10676 will happen. (See cpan/Encode/encoding.pm and Encode.)
10677
10678 The PV of "sv" is returned.
10679
10680 char* sv_recode_to_utf8(SV* sv, SV *encoding)
10681
10682 sv_uni_display
10683 Build to the scalar "dsv" a displayable version of the scalar
10684 "sv", the displayable version being at most "pvlim" bytes long
10685 (if longer, the rest is truncated and "..." will be appended).
10686
10687 The "flags" argument is as in "pv_uni_display"().
10688
10689 The pointer to the PV of the "dsv" is returned.
10690
10691 char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim,
10692 UV flags)
10693
10694 UNICODE_REPLACEMENT
10695 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT
10696 CHARACTER
10697
10698 UNI_TO_NATIVE
10699 Returns the native equivalent of the input Unicode code point
10700 given by "ch". Thus, "UNI_TO_NATIVE(68)" on EBCDIC platforms
10701 returns 196. These each represent the character "D" on their
10702 respective platforms. On ASCII platforms no conversion is
10703 needed, so this macro expands to just its input, adding no time
10704 nor space requirements to the implementation.
10705
10706 UV UNI_TO_NATIVE(UV ch)
10707
10708 utf8n_to_uvchr
10709 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10710 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
10711 rather than call this directly.
10712
10713 Bottom level UTF-8 decode routine. Returns the native code
10714 point value of the first character in the string "s", which is
10715 assumed to be in UTF-8 (or UTF-EBCDIC) encoding, and no longer
10716 than "curlen" bytes; *retlen (if "retlen" isn't NULL) will be
10717 set to the length, in bytes, of that character.
10718
10719 The value of "flags" determines the behavior when "s" does not
10720 point to a well-formed UTF-8 character. If "flags" is 0,
10721 encountering a malformation causes zero to be returned and
10722 *retlen is set so that ("s" + *retlen) is the next possible
10723 position in "s" that could begin a non-malformed character.
10724 Also, if UTF-8 warnings haven't been lexically disabled, a
10725 warning is raised. Some UTF-8 input sequences may contain
10726 multiple malformations. This function tries to find every
10727 possible one in each call, so multiple warnings can be raised
10728 for the same sequence.
10729
10730 Various ALLOW flags can be set in "flags" to allow (and not
10731 warn on) individual types of malformations, such as the
10732 sequence being overlong (that is, when there is a shorter
10733 sequence that can express the same code point; overlong
10734 sequences are expressly forbidden in the UTF-8 standard due to
10735 potential security issues). Another malformation example is
10736 the first byte of a character not being a legal first byte.
10737 See utf8.h for the list of such flags. Even if allowed, this
10738 function generally returns the Unicode REPLACEMENT CHARACTER
10739 when it encounters a malformation. There are flags in utf8.h
10740 to override this behavior for the overlong malformations, but
10741 don't do that except for very specialized purposes.
10742
10743 The "UTF8_CHECK_ONLY" flag overrides the behavior when a non-
10744 allowed (by other flags) malformation is found. If this flag
10745 is set, the routine assumes that the caller will raise a
10746 warning, and this function will silently just set "retlen" to
10747 "-1" (cast to "STRLEN") and return zero.
10748
10749 Note that this API requires disambiguation between successful
10750 decoding a "NUL" character, and an error return (unless the
10751 "UTF8_CHECK_ONLY" flag is set), as in both cases, 0 is
10752 returned, and, depending on the malformation, "retlen" may be
10753 set to 1. To disambiguate, upon a zero return, see if the
10754 first byte of "s" is 0 as well. If so, the input was a "NUL";
10755 if not, the input had an error. Or you can use
10756 "utf8n_to_uvchr_error".
10757
10758 Certain code points are considered problematic. These are
10759 Unicode surrogates, Unicode non-characters, and code points
10760 above the Unicode maximum of 0x10FFFF. By default these are
10761 considered regular code points, but certain situations warrant
10762 special handling for them, which can be specified using the
10763 "flags" parameter. If "flags" contains
10764 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE", all three classes are
10765 treated as malformations and handled as such. The flags
10766 "UTF8_DISALLOW_SURROGATE", "UTF8_DISALLOW_NONCHAR", and
10767 "UTF8_DISALLOW_SUPER" (meaning above the legal Unicode maximum)
10768 can be set to disallow these categories individually.
10769 "UTF8_DISALLOW_ILLEGAL_INTERCHANGE" restricts the allowed
10770 inputs to the strict UTF-8 traditionally defined by Unicode.
10771 Use "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE" to use the
10772 strictness definition given by Unicode Corrigendum #9
10773 <https://www.unicode.org/versions/corrigendum9.html>. The
10774 difference between traditional strictness and C9 strictness is
10775 that the latter does not forbid non-character code points.
10776 (They are still discouraged, however.) For more discussion see
10777 "Noncharacter code points" in perlunicode.
10778
10779 The flags "UTF8_WARN_ILLEGAL_INTERCHANGE",
10780 "UTF8_WARN_ILLEGAL_C9_INTERCHANGE", "UTF8_WARN_SURROGATE",
10781 "UTF8_WARN_NONCHAR", and "UTF8_WARN_SUPER" will cause warning
10782 messages to be raised for their respective categories, but
10783 otherwise the code points are considered valid (not
10784 malformations). To get a category to both be treated as a
10785 malformation and raise a warning, specify both the WARN and
10786 DISALLOW flags. (But note that warnings are not raised if
10787 lexically disabled nor if "UTF8_CHECK_ONLY" is also specified.)
10788
10789 Extremely high code points were never specified in any
10790 standard, and require an extension to UTF-8 to express, which
10791 Perl does. It is likely that programs written in something
10792 other than Perl would not be able to read files that contain
10793 these; nor would Perl understand files written by something
10794 that uses a different extension. For these reasons, there is a
10795 separate set of flags that can warn and/or disallow these
10796 extremely high code points, even if other above-Unicode ones
10797 are accepted. They are the "UTF8_WARN_PERL_EXTENDED" and
10798 "UTF8_DISALLOW_PERL_EXTENDED" flags. For more information see
10799 ""UTF8_GOT_PERL_EXTENDED"". Of course "UTF8_DISALLOW_SUPER"
10800 will treat all above-Unicode code points, including these, as
10801 malformations. (Note that the Unicode standard considers
10802 anything above 0x10FFFF to be illegal, but there are standards
10803 predating it that allow up to 0x7FFF_FFFF (2**31 -1))
10804
10805 A somewhat misleadingly named synonym for
10806 "UTF8_WARN_PERL_EXTENDED" is retained for backward
10807 compatibility: "UTF8_WARN_ABOVE_31_BIT". Similarly,
10808 "UTF8_DISALLOW_ABOVE_31_BIT" is usable instead of the more
10809 accurately named "UTF8_DISALLOW_PERL_EXTENDED". The names are
10810 misleading because these flags can apply to code points that
10811 actually do fit in 31 bits. This happens on EBCDIC platforms,
10812 and sometimes when the overlong malformation is also present.
10813 The new names accurately describe the situation in all cases.
10814
10815 All other code points corresponding to Unicode characters,
10816 including private use and those yet to be assigned, are never
10817 considered malformed and never warn.
10818
10819 UV utf8n_to_uvchr(const U8 *s, STRLEN curlen,
10820 STRLEN *retlen, const U32 flags)
10821
10822 utf8n_to_uvchr_error
10823 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10824 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
10825 rather than call this directly.
10826
10827 This function is for code that needs to know what the precise
10828 malformation(s) are when an error is found. If you also need
10829 to know the generated warning messages, use
10830 "utf8n_to_uvchr_msgs"() instead.
10831
10832 It is like "utf8n_to_uvchr" but it takes an extra parameter
10833 placed after all the others, "errors". If this parameter is 0,
10834 this function behaves identically to "utf8n_to_uvchr".
10835 Otherwise, "errors" should be a pointer to a "U32" variable,
10836 which this function sets to indicate any errors found. Upon
10837 return, if *errors is 0, there were no errors found.
10838 Otherwise, *errors is the bit-wise "OR" of the bits described
10839 in the list below. Some of these bits will be set if a
10840 malformation is found, even if the input "flags" parameter
10841 indicates that the given malformation is allowed; those
10842 exceptions are noted:
10843
10844 "UTF8_GOT_PERL_EXTENDED"
10845 The input sequence is not standard UTF-8, but a Perl
10846 extension. This bit is set only if the input "flags"
10847 parameter contains either the "UTF8_DISALLOW_PERL_EXTENDED"
10848 or the "UTF8_WARN_PERL_EXTENDED" flags.
10849
10850 Code points above 0x7FFF_FFFF (2**31 - 1) were never
10851 specified in any standard, and so some extension must be
10852 used to express them. Perl uses a natural extension to
10853 UTF-8 to represent the ones up to 2**36-1, and invented a
10854 further extension to represent even higher ones, so that
10855 any code point that fits in a 64-bit word can be
10856 represented. Text using these extensions is not likely to
10857 be portable to non-Perl code. We lump both of these
10858 extensions together and refer to them as Perl extended
10859 UTF-8. There exist other extensions that people have
10860 invented, incompatible with Perl's.
10861
10862 On EBCDIC platforms starting in Perl v5.24, the Perl
10863 extension for representing extremely high code points kicks
10864 in at 0x3FFF_FFFF (2**30 -1), which is lower than on ASCII.
10865 Prior to that, code points 2**31 and higher were simply
10866 unrepresentable, and a different, incompatible method was
10867 used to represent code points between 2**30 and 2**31 - 1.
10868
10869 On both platforms, ASCII and EBCDIC,
10870 "UTF8_GOT_PERL_EXTENDED" is set if Perl extended UTF-8 is
10871 used.
10872
10873 In earlier Perls, this bit was named
10874 "UTF8_GOT_ABOVE_31_BIT", which you still may use for
10875 backward compatibility. That name is misleading, as this
10876 flag may be set when the code point actually does fit in 31
10877 bits. This happens on EBCDIC platforms, and sometimes when
10878 the overlong malformation is also present. The new name
10879 accurately describes the situation in all cases.
10880
10881 "UTF8_GOT_CONTINUATION"
10882 The input sequence was malformed in that the first byte was
10883 a UTF-8 continuation byte.
10884
10885 "UTF8_GOT_EMPTY"
10886 The input "curlen" parameter was 0.
10887
10888 "UTF8_GOT_LONG"
10889 The input sequence was malformed in that there is some
10890 other sequence that evaluates to the same code point, but
10891 that sequence is shorter than this one.
10892
10893 Until Unicode 3.1, it was legal for programs to accept this
10894 malformation, but it was discovered that this created
10895 security issues.
10896
10897 "UTF8_GOT_NONCHAR"
10898 The code point represented by the input UTF-8 sequence is
10899 for a Unicode non-character code point. This bit is set
10900 only if the input "flags" parameter contains either the
10901 "UTF8_DISALLOW_NONCHAR" or the "UTF8_WARN_NONCHAR" flags.
10902
10903 "UTF8_GOT_NON_CONTINUATION"
10904 The input sequence was malformed in that a non-continuation
10905 type byte was found in a position where only a continuation
10906 type one should be. See also ""UTF8_GOT_SHORT"".
10907
10908 "UTF8_GOT_OVERFLOW"
10909 The input sequence was malformed in that it is for a code
10910 point that is not representable in the number of bits
10911 available in an IV on the current platform.
10912
10913 "UTF8_GOT_SHORT"
10914 The input sequence was malformed in that "curlen" is
10915 smaller than required for a complete sequence. In other
10916 words, the input is for a partial character sequence.
10917
10918 "UTF8_GOT_SHORT" and "UTF8_GOT_NON_CONTINUATION" both
10919 indicate a too short sequence. The difference is that
10920 "UTF8_GOT_NON_CONTINUATION" indicates always that there is
10921 an error, while "UTF8_GOT_SHORT" means that an incomplete
10922 sequence was looked at. If no other flags are present, it
10923 means that the sequence was valid as far as it went.
10924 Depending on the application, this could mean one of three
10925 things:
10926
10927 · The "curlen" length parameter passed in was too small,
10928 and the function was prevented from examining all the
10929 necessary bytes.
10930
10931 · The buffer being looked at is based on reading data,
10932 and the data received so far stopped in the middle of a
10933 character, so that the next read will read the
10934 remainder of this character. (It is up to the caller
10935 to deal with the split bytes somehow.)
10936
10937 · This is a real error, and the partial sequence is all
10938 we're going to get.
10939
10940 "UTF8_GOT_SUPER"
10941 The input sequence was malformed in that it is for a non-
10942 Unicode code point; that is, one above the legal Unicode
10943 maximum. This bit is set only if the input "flags"
10944 parameter contains either the "UTF8_DISALLOW_SUPER" or the
10945 "UTF8_WARN_SUPER" flags.
10946
10947 "UTF8_GOT_SURROGATE"
10948 The input sequence was malformed in that it is for a
10949 -Unicode UTF-16 surrogate code point. This bit is set only
10950 if the input "flags" parameter contains either the
10951 "UTF8_DISALLOW_SURROGATE" or the "UTF8_WARN_SURROGATE"
10952 flags.
10953
10954 To do your own error handling, call this function with the
10955 "UTF8_CHECK_ONLY" flag to suppress any warnings, and then
10956 examine the *errors return.
10957
10958 UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
10959 STRLEN *retlen,
10960 const U32 flags,
10961 U32 * errors)
10962
10963 utf8n_to_uvchr_msgs
10964 NOTE: this function is experimental and may change or be
10965 removed without notice.
10966
10967 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
10968 CIRCUMSTANCES. Most code should use "utf8_to_uvchr_buf"()
10969 rather than call this directly.
10970
10971 This function is for code that needs to know what the precise
10972 malformation(s) are when an error is found, and wants the
10973 corresponding warning and/or error messages to be returned to
10974 the caller rather than be displayed. All messages that would
10975 have been displayed if all lexcial warnings are enabled will be
10976 returned.
10977
10978 It is just like "utf8n_to_uvchr_error" but it takes an extra
10979 parameter placed after all the others, "msgs". If this
10980 parameter is 0, this function behaves identically to
10981 "utf8n_to_uvchr_error". Otherwise, "msgs" should be a pointer
10982 to an "AV *" variable, in which this function creates a new AV
10983 to contain any appropriate messages. The elements of the array
10984 are ordered so that the first message that would have been
10985 displayed is in the 0th element, and so on. Each element is a
10986 hash with three key-value pairs, as follows:
10987
10988 "text"
10989 The text of the message as a "SVpv".
10990
10991 "warn_categories"
10992 The warning category (or categories) packed into a "SVuv".
10993
10994 "flag"
10995 A single flag bit associated with this message, in a
10996 "SVuv". The bit corresponds to some bit in the *errors
10997 return value, such as "UTF8_GOT_LONG".
10998
10999 It's important to note that specifying this parameter as non-
11000 null will cause any warnings this function would otherwise
11001 generate to be suppressed, and instead be placed in *msgs. The
11002 caller can check the lexical warnings state (or not) when
11003 choosing what to do with the returned messages.
11004
11005 If the flag "UTF8_CHECK_ONLY" is passed, no warnings are
11006 generated, and hence no AV is created.
11007
11008 The caller, of course, is responsible for freeing any returned
11009 AV.
11010
11011 UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
11012 STRLEN *retlen,
11013 const U32 flags,
11014 U32 * errors, AV ** msgs)
11015
11016 UTF8SKIP
11017 returns the number of bytes a non-malformed UTF-8 encoded
11018 character whose first (perhaps only) byte is pointed to by "s".
11019
11020 If there is a possibility of malformed input, use instead:
11021
11022 ""UTF8_SAFE_SKIP"" if you know the maximum ending pointer in
11023 the buffer pointed to by "s"; or
11024 ""UTF8_CHK_SKIP"" if you don't know it.
11025
11026 It is better to restructure your code so the end pointer is
11027 passed down so that you know what it actually is at the point
11028 of this call, but if that isn't possible, ""UTF8_CHK_SKIP"" can
11029 minimize the chance of accessing beyond the end of the input
11030 buffer.
11031
11032 STRLEN UTF8SKIP(char* s)
11033
11034 UTF8_CHK_SKIP
11035 This is a safer version of ""UTF8SKIP"", but still not as safe
11036 as ""UTF8_SAFE_SKIP"". This version doesn't blindly assume
11037 that the input string pointed to by "s" is well-formed, but
11038 verifies that there isn't a NUL terminating character before
11039 the expected end of the next character in "s". The length
11040 "UTF8_CHK_SKIP" returns stops just before any such NUL.
11041
11042 Perl tends to add NULs, as an insurance policy, after the end
11043 of strings in SV's, so it is likely that using this macro will
11044 prevent inadvertent reading beyond the end of the input buffer,
11045 even if it is malformed UTF-8.
11046
11047 This macro is intended to be used by XS modules where the
11048 inputs could be malformed, and it isn't feasible to restructure
11049 to use the safer ""UTF8_SAFE_SKIP"", for example when
11050 interfacing with a C library.
11051
11052 STRLEN UTF8_CHK_SKIP(char* s)
11053
11054 utf8_distance
11055 Returns the number of UTF-8 characters between the UTF-8
11056 pointers "a" and "b".
11057
11058 WARNING: use only if you *know* that the pointers point inside
11059 the same UTF-8 buffer.
11060
11061 IV utf8_distance(const U8 *a, const U8 *b)
11062
11063 utf8_hop
11064 Return the UTF-8 pointer "s" displaced by "off" characters,
11065 either forward or backward.
11066
11067 WARNING: do not use the following unless you *know* "off" is
11068 within the UTF-8 data pointed to by "s" *and* that on entry "s"
11069 is aligned on the first byte of character or just after the
11070 last byte of a character.
11071
11072 U8* utf8_hop(const U8 *s, SSize_t off)
11073
11074 utf8_hop_back
11075 Return the UTF-8 pointer "s" displaced by up to "off"
11076 characters, backward.
11077
11078 "off" must be non-positive.
11079
11080 "s" must be after or equal to "start".
11081
11082 When moving backward it will not move before "start".
11083
11084 Will not exceed this limit even if the string is not valid
11085 "UTF-8".
11086
11087 U8* utf8_hop_back(const U8 *s, SSize_t off,
11088 const U8 *start)
11089
11090 utf8_hop_forward
11091 Return the UTF-8 pointer "s" displaced by up to "off"
11092 characters, forward.
11093
11094 "off" must be non-negative.
11095
11096 "s" must be before or equal to "end".
11097
11098 When moving forward it will not move beyond "end".
11099
11100 Will not exceed this limit even if the string is not valid
11101 "UTF-8".
11102
11103 U8* utf8_hop_forward(const U8 *s, SSize_t off,
11104 const U8 *end)
11105
11106 utf8_hop_safe
11107 Return the UTF-8 pointer "s" displaced by up to "off"
11108 characters, either forward or backward.
11109
11110 When moving backward it will not move before "start".
11111
11112 When moving forward it will not move beyond "end".
11113
11114 Will not exceed those limits even if the string is not valid
11115 "UTF-8".
11116
11117 U8* utf8_hop_safe(const U8 *s, SSize_t off,
11118 const U8 *start, const U8 *end)
11119
11120 UTF8_IS_INVARIANT
11121 Evaluates to 1 if the byte "c" represents the same character
11122 when encoded in UTF-8 as when not; otherwise evaluates to 0.
11123 UTF-8 invariant characters can be copied as-is when converting
11124 to/from UTF-8, saving time.
11125
11126 In spite of the name, this macro gives the correct result if
11127 the input string from which "c" comes is not encoded in UTF-8.
11128
11129 See "UVCHR_IS_INVARIANT" for checking if a UV is invariant.
11130
11131 bool UTF8_IS_INVARIANT(char c)
11132
11133 UTF8_IS_NONCHAR
11134 Evaluates to non-zero if the first few bytes of the string
11135 starting at "s" and looking no further than "e - 1" are well-
11136 formed UTF-8 that represents one of the Unicode non-character
11137 code points; otherwise it evaluates to 0. If non-zero, the
11138 value gives how many bytes starting at "s" comprise the code
11139 point's representation.
11140
11141 bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
11142
11143 UTF8_IS_SUPER
11144 Recall that Perl recognizes an extension to UTF-8 that can
11145 encode code points larger than the ones defined by Unicode,
11146 which are 0..0x10FFFF.
11147
11148 This macro evaluates to non-zero if the first few bytes of the
11149 string starting at "s" and looking no further than "e - 1" are
11150 from this UTF-8 extension; otherwise it evaluates to 0. If
11151 non-zero, the value gives how many bytes starting at "s"
11152 comprise the code point's representation.
11153
11154 0 is returned if the bytes are not well-formed extended UTF-8,
11155 or if they represent a code point that cannot fit in a UV on
11156 the current platform. Hence this macro can give different
11157 results when run on a 64-bit word machine than on one with a
11158 32-bit word size.
11159
11160 Note that it is illegal to have code points that are larger
11161 than what can fit in an IV on the current machine.
11162
11163 bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
11164
11165 UTF8_IS_SURROGATE
11166 Evaluates to non-zero if the first few bytes of the string
11167 starting at "s" and looking no further than "e - 1" are well-
11168 formed UTF-8 that represents one of the Unicode surrogate code
11169 points; otherwise it evaluates to 0. If non-zero, the value
11170 gives how many bytes starting at "s" comprise the code point's
11171 representation.
11172
11173 bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
11174
11175 utf8_length
11176 Returns the number of characters in the sequence of
11177 UTF-8-encoded bytes starting at "s" and ending at the byte just
11178 before "e". If <s> and <e> point to the same place, it returns
11179 0 with no warning raised.
11180
11181 If "e < s" or if the scan would end up past "e", it raises a
11182 UTF8 warning and returns the number of valid characters.
11183
11184 STRLEN utf8_length(const U8* s, const U8 *e)
11185
11186 UTF8_MAXBYTES
11187 The maximum width of a single UTF-8 encoded character, in
11188 bytes.
11189
11190 NOTE: Strictly speaking Perl's UTF-8 should not be called UTF-8
11191 since UTF-8 is an encoding of Unicode, and Unicode's upper
11192 limit, 0x10FFFF, can be expressed with 4 bytes. However, Perl
11193 thinks of UTF-8 as a way to encode non-negative integers in a
11194 binary format, even those above Unicode.
11195
11196 UTF8_MAXBYTES_CASE
11197 The maximum number of UTF-8 bytes a single Unicode character
11198 can uppercase/lowercase/titlecase/fold into.
11199
11200 UTF8_SAFE_SKIP
11201 returns 0 if "s >= e"; otherwise returns the number of bytes in
11202 the UTF-8 encoded character whose first byte is pointed to by
11203 "s". But it never returns beyond "e". On DEBUGGING builds, it
11204 asserts that "s <= e".
11205
11206 STRLEN UTF8_SAFE_SKIP(char* s, char* e)
11207
11208 UTF8_SKIP
11209 This is a synonym for ""UTF8SKIP""
11210
11211 STRLEN UTF8_SKIP(char* s)
11212
11213 utf8_to_bytes
11214 NOTE: this function is experimental and may change or be
11215 removed without notice.
11216
11217 Converts a string "s" of length *lenp from UTF-8 into native
11218 byte encoding. Unlike "bytes_to_utf8", this over-writes the
11219 original string, and updates *lenp to contain the new length.
11220 Returns zero on failure (leaving "s" unchanged) setting *lenp
11221 to -1.
11222
11223 Upon successful return, the number of variants in the string
11224 can be computed by having saved the value of *lenp before the
11225 call, and subtracting the after-call value of *lenp from it.
11226
11227 If you need a copy of the string, see "bytes_from_utf8".
11228
11229 U8* utf8_to_bytes(U8 *s, STRLEN *lenp)
11230
11231 utf8_to_uvchr_buf
11232 Returns the native code point of the first character in the
11233 string "s" which is assumed to be in UTF-8 encoding; "send"
11234 points to 1 beyond the end of "s". *retlen will be set to the
11235 length, in bytes, of that character.
11236
11237 If "s" does not point to a well-formed UTF-8 character and UTF8
11238 warnings are enabled, zero is returned and *retlen is set (if
11239 "retlen" isn't "NULL") to -1. If those warnings are off, the
11240 computed value, if well-defined (or the Unicode REPLACEMENT
11241 CHARACTER if not), is silently returned, and *retlen is set (if
11242 "retlen" isn't "NULL") so that ("s" + *retlen) is the next
11243 possible position in "s" that could begin a non-malformed
11244 character. See "utf8n_to_uvchr" for details on when the
11245 REPLACEMENT CHARACTER is returned.
11246
11247 UV utf8_to_uvchr_buf(const U8 *s, const U8 *send,
11248 STRLEN *retlen)
11249
11250 UVCHR_IS_INVARIANT
11251 Evaluates to 1 if the representation of code point "cp" is the
11252 same whether or not it is encoded in UTF-8; otherwise evaluates
11253 to 0. UTF-8 invariant characters can be copied as-is when
11254 converting to/from UTF-8, saving time. "cp" is Unicode if
11255 above 255; otherwise is platform-native.
11256
11257 bool UVCHR_IS_INVARIANT(UV cp)
11258
11259 UVCHR_SKIP
11260 returns the number of bytes required to represent the code
11261 point "cp" when encoded as UTF-8. "cp" is a native (ASCII or
11262 EBCDIC) code point if less than 255; a Unicode code point
11263 otherwise.
11264
11265 STRLEN UVCHR_SKIP(UV cp)
11266
11267 uvchr_to_utf8
11268 Adds the UTF-8 representation of the native code point "uv" to
11269 the end of the string "d"; "d" should have at least
11270 "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
11271 available. The return value is the pointer to the byte after
11272 the end of the new character. In other words,
11273
11274 d = uvchr_to_utf8(d, uv);
11275
11276 is the recommended wide native character-aware way of saying
11277
11278 *(d++) = uv;
11279
11280 This function accepts any code point from 0.."IV_MAX" as input.
11281 "IV_MAX" is typically 0x7FFF_FFFF in a 32-bit word.
11282
11283 It is possible to forbid or warn on non-Unicode code points, or
11284 those that may be problematic by using "uvchr_to_utf8_flags".
11285
11286 U8* uvchr_to_utf8(U8 *d, UV uv)
11287
11288 uvchr_to_utf8_flags
11289 Adds the UTF-8 representation of the native code point "uv" to
11290 the end of the string "d"; "d" should have at least
11291 "UVCHR_SKIP(uv)+1" (up to "UTF8_MAXBYTES+1") free bytes
11292 available. The return value is the pointer to the byte after
11293 the end of the new character. In other words,
11294
11295 d = uvchr_to_utf8_flags(d, uv, flags);
11296
11297 or, in most cases,
11298
11299 d = uvchr_to_utf8_flags(d, uv, 0);
11300
11301 This is the Unicode-aware way of saying
11302
11303 *(d++) = uv;
11304
11305 If "flags" is 0, this function accepts any code point from
11306 0.."IV_MAX" as input. "IV_MAX" is typically 0x7FFF_FFFF in a
11307 32-bit word.
11308
11309 Specifying "flags" can further restrict what is allowed and not
11310 warned on, as follows:
11311
11312 If "uv" is a Unicode surrogate code point and
11313 "UNICODE_WARN_SURROGATE" is set, the function will raise a
11314 warning, provided UTF8 warnings are enabled. If instead
11315 "UNICODE_DISALLOW_SURROGATE" is set, the function will fail and
11316 return NULL. If both flags are set, the function will both
11317 warn and return NULL.
11318
11319 Similarly, the "UNICODE_WARN_NONCHAR" and
11320 "UNICODE_DISALLOW_NONCHAR" flags affect how the function
11321 handles a Unicode non-character.
11322
11323 And likewise, the "UNICODE_WARN_SUPER" and
11324 "UNICODE_DISALLOW_SUPER" flags affect the handling of code
11325 points that are above the Unicode maximum of 0x10FFFF.
11326 Languages other than Perl may not be able to accept files that
11327 contain these.
11328
11329 The flag "UNICODE_WARN_ILLEGAL_INTERCHANGE" selects all three
11330 of the above WARN flags; and
11331 "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE" selects all three
11332 DISALLOW flags. "UNICODE_DISALLOW_ILLEGAL_INTERCHANGE"
11333 restricts the allowed inputs to the strict UTF-8 traditionally
11334 defined by Unicode. Similarly,
11335 "UNICODE_WARN_ILLEGAL_C9_INTERCHANGE" and
11336 "UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE" are shortcuts to
11337 select the above-Unicode and surrogate flags, but not the non-
11338 character ones, as defined in Unicode Corrigendum #9
11339 <https://www.unicode.org/versions/corrigendum9.html>. See
11340 "Noncharacter code points" in perlunicode.
11341
11342 Extremely high code points were never specified in any
11343 standard, and require an extension to UTF-8 to express, which
11344 Perl does. It is likely that programs written in something
11345 other than Perl would not be able to read files that contain
11346 these; nor would Perl understand files written by something
11347 that uses a different extension. For these reasons, there is a
11348 separate set of flags that can warn and/or disallow these
11349 extremely high code points, even if other above-Unicode ones
11350 are accepted. They are the "UNICODE_WARN_PERL_EXTENDED" and
11351 "UNICODE_DISALLOW_PERL_EXTENDED" flags. For more information
11352 see ""UTF8_GOT_PERL_EXTENDED"". Of course
11353 "UNICODE_DISALLOW_SUPER" will treat all above-Unicode code
11354 points, including these, as malformations. (Note that the
11355 Unicode standard considers anything above 0x10FFFF to be
11356 illegal, but there are standards predating it that allow up to
11357 0x7FFF_FFFF (2**31 -1))
11358
11359 A somewhat misleadingly named synonym for
11360 "UNICODE_WARN_PERL_EXTENDED" is retained for backward
11361 compatibility: "UNICODE_WARN_ABOVE_31_BIT". Similarly,
11362 "UNICODE_DISALLOW_ABOVE_31_BIT" is usable instead of the more
11363 accurately named "UNICODE_DISALLOW_PERL_EXTENDED". The names
11364 are misleading because on EBCDIC platforms,these flags can
11365 apply to code points that actually do fit in 31 bits. The new
11366 names accurately describe the situation in all cases.
11367
11368 U8* uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
11369
11370 uvchr_to_utf8_flags_msgs
11371 NOTE: this function is experimental and may change or be
11372 removed without notice.
11373
11374 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED
11375 CIRCUMSTANCES.
11376
11377 Most code should use ""uvchr_to_utf8_flags"()" rather than call
11378 this directly.
11379
11380 This function is for code that wants any warning and/or error
11381 messages to be returned to the caller rather than be displayed.
11382 All messages that would have been displayed if all lexical
11383 warnings are enabled will be returned.
11384
11385 It is just like "uvchr_to_utf8_flags" but it takes an extra
11386 parameter placed after all the others, "msgs". If this
11387 parameter is 0, this function behaves identically to
11388 "uvchr_to_utf8_flags". Otherwise, "msgs" should be a pointer
11389 to an "HV *" variable, in which this function creates a new HV
11390 to contain any appropriate messages. The hash has three key-
11391 value pairs, as follows:
11392
11393 "text"
11394 The text of the message as a "SVpv".
11395
11396 "warn_categories"
11397 The warning category (or categories) packed into a "SVuv".
11398
11399 "flag"
11400 A single flag bit associated with this message, in a
11401 "SVuv". The bit corresponds to some bit in the *errors
11402 return value, such as "UNICODE_GOT_SURROGATE".
11403
11404 It's important to note that specifying this parameter as non-
11405 null will cause any warnings this function would otherwise
11406 generate to be suppressed, and instead be placed in *msgs. The
11407 caller can check the lexical warnings state (or not) when
11408 choosing what to do with the returned messages.
11409
11410 The caller, of course, is responsible for freeing any returned
11411 HV.
11412
11413 U8* uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags,
11414 HV ** msgs)
11415
11417 newXSproto
11418 Used by "xsubpp" to hook up XSUBs as Perl subs. Adds Perl
11419 prototypes to the subs.
11420
11421 XS_APIVERSION_BOOTCHECK
11422 Macro to verify that the perl api version an XS module has been
11423 compiled against matches the api version of the perl
11424 interpreter it's being loaded into.
11425
11426 XS_APIVERSION_BOOTCHECK;
11427
11428 XS_VERSION
11429 The version identifier for an XS module. This is usually
11430 handled automatically by "ExtUtils::MakeMaker". See
11431 "XS_VERSION_BOOTCHECK".
11432
11433 XS_VERSION_BOOTCHECK
11434 Macro to verify that a PM module's $VERSION variable matches
11435 the XS module's "XS_VERSION" variable. This is usually handled
11436 automatically by "xsubpp". See "The VERSIONCHECK: Keyword" in
11437 perlxs.
11438
11439 XS_VERSION_BOOTCHECK;
11440
11442 In all these calls, the "U32 wn" parameters are warning category
11443 constants. You can see the ones currently available in "Category
11444 Hierarchy" in warnings, just capitalize all letters in the names and
11445 prefix them by "WARN_". So, for example, the category "void" used in a
11446 perl program becomes "WARN_VOID" when used in XS code and passed to one
11447 of the calls below.
11448
11449 ckWARN Returns a boolean as to whether or not warnings are enabled for
11450 the warning category "w". If the category is by default
11451 enabled even if not within the scope of "use warnings", instead
11452 use the "ckWARN_d" macro.
11453
11454 bool ckWARN(U32 w)
11455
11456 ckWARN2 Like "ckWARN", but takes two warnings categories as input, and
11457 returns TRUE if either is enabled. If either category is by
11458 default enabled even if not within the scope of "use warnings",
11459 instead use the "ckWARN2_d" macro. The categories must be
11460 completely independent, one may not be subclassed from the
11461 other.
11462
11463 bool ckWARN2(U32 w1, U32 w2)
11464
11465 ckWARN3 Like "ckWARN2", but takes three warnings categories as input,
11466 and returns TRUE if any is enabled. If any of the categories
11467 is by default enabled even if not within the scope of
11468 "use warnings", instead use the "ckWARN3_d" macro. The
11469 categories must be completely independent, one may not be
11470 subclassed from any other.
11471
11472 bool ckWARN3(U32 w1, U32 w2, U32 w3)
11473
11474 ckWARN4 Like "ckWARN3", but takes four warnings categories as input,
11475 and returns TRUE if any is enabled. If any of the categories
11476 is by default enabled even if not within the scope of
11477 "use warnings", instead use the "ckWARN4_d" macro. The
11478 categories must be completely independent, one may not be
11479 subclassed from any other.
11480
11481 bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
11482
11483 ckWARN_d
11484 Like "ckWARN", but for use if and only if the warning category
11485 is by default enabled even if not within the scope of
11486 "use warnings".
11487
11488 bool ckWARN_d(U32 w)
11489
11490 ckWARN2_d
11491 Like "ckWARN2", but for use if and only if either warning
11492 category is by default enabled even if not within the scope of
11493 "use warnings".
11494
11495 bool ckWARN2_d(U32 w1, U32 w2)
11496
11497 ckWARN3_d
11498 Like "ckWARN3", but for use if and only if any of the warning
11499 categories is by default enabled even if not within the scope
11500 of "use warnings".
11501
11502 bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
11503
11504 ckWARN4_d
11505 Like "ckWARN4", but for use if and only if any of the warning
11506 categories is by default enabled even if not within the scope
11507 of "use warnings".
11508
11509 bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
11510
11511 CLEAR_ERRSV
11512 Clear the contents of $@, setting it to the empty string.
11513
11514 This replaces any read-only SV with a fresh SV and removes any
11515 magic.
11516
11517 void CLEAR_ERRSV()
11518
11519 croak This is an XS interface to Perl's "die" function.
11520
11521 Take a sprintf-style format pattern and argument list. These
11522 are used to generate a string message. If the message does not
11523 end with a newline, then it will be extended with some
11524 indication of the current location in the code, as described
11525 for "mess_sv".
11526
11527 The error message will be used as an exception, by default
11528 returning control to the nearest enclosing "eval", but subject
11529 to modification by a $SIG{__DIE__} handler. In any case, the
11530 "croak" function never returns normally.
11531
11532 For historical reasons, if "pat" is null then the contents of
11533 "ERRSV" ($@) will be used as an error message or object instead
11534 of building an error message from arguments. If you want to
11535 throw a non-string object, or build an error message in an SV
11536 yourself, it is preferable to use the "croak_sv" function,
11537 which does not involve clobbering "ERRSV".
11538
11539 void croak(const char* pat, ...)
11540
11541 croak_no_modify
11542 Exactly equivalent to "Perl_croak(aTHX_ "%s", PL_no_modify)",
11543 but generates terser object code than using "Perl_croak". Less
11544 code used on exception code paths reduces CPU cache pressure.
11545
11546 void croak_no_modify()
11547
11548 croak_sv
11549 This is an XS interface to Perl's "die" function.
11550
11551 "baseex" is the error message or object. If it is a reference,
11552 it will be used as-is. Otherwise it is used as a string, and
11553 if it does not end with a newline then it will be extended with
11554 some indication of the current location in the code, as
11555 described for "mess_sv".
11556
11557 The error message or object will be used as an exception, by
11558 default returning control to the nearest enclosing "eval", but
11559 subject to modification by a $SIG{__DIE__} handler. In any
11560 case, the "croak_sv" function never returns normally.
11561
11562 To die with a simple string message, the "croak" function may
11563 be more convenient.
11564
11565 void croak_sv(SV *baseex)
11566
11567 die Behaves the same as "croak", except for the return type. It
11568 should be used only where the "OP *" return type is required.
11569 The function never actually returns.
11570
11571 OP* die(const char* pat, ...)
11572
11573 die_sv Behaves the same as "croak_sv", except for the return type. It
11574 should be used only where the "OP *" return type is required.
11575 The function never actually returns.
11576
11577 OP* die_sv(SV *baseex)
11578
11579 ERRSV Returns the SV for $@, creating it if needed.
11580
11581 SV * ERRSV
11582
11583 my_setenv
11584 A wrapper for the C library setenv(3). Don't use the latter,
11585 as the perl version has desirable safeguards
11586
11587 void my_setenv(const char* nam, const char* val)
11588
11589 rsignal A wrapper for the C library signal(2). Don't use the latter,
11590 as the Perl version knows things that interact with the rest of
11591 the perl interpreter.
11592
11593 Sighandler_t rsignal(int i, Sighandler_t t)
11594
11595 SANE_ERRSV
11596 Clean up ERRSV so we can safely set it.
11597
11598 This replaces any read-only SV with a fresh writable copy and
11599 removes any magic.
11600
11601 void SANE_ERRSV()
11602
11603 vcroak This is an XS interface to Perl's "die" function.
11604
11605 "pat" and "args" are a sprintf-style format pattern and
11606 encapsulated argument list. These are used to generate a
11607 string message. If the message does not end with a newline,
11608 then it will be extended with some indication of the current
11609 location in the code, as described for "mess_sv".
11610
11611 The error message will be used as an exception, by default
11612 returning control to the nearest enclosing "eval", but subject
11613 to modification by a $SIG{__DIE__} handler. In any case, the
11614 "croak" function never returns normally.
11615
11616 For historical reasons, if "pat" is null then the contents of
11617 "ERRSV" ($@) will be used as an error message or object instead
11618 of building an error message from arguments. If you want to
11619 throw a non-string object, or build an error message in an SV
11620 yourself, it is preferable to use the "croak_sv" function,
11621 which does not involve clobbering "ERRSV".
11622
11623 void vcroak(const char* pat, va_list* args)
11624
11625 vwarn This is an XS interface to Perl's "warn" function.
11626
11627 "pat" and "args" are a sprintf-style format pattern and
11628 encapsulated argument list. These are used to generate a
11629 string message. If the message does not end with a newline,
11630 then it will be extended with some indication of the current
11631 location in the code, as described for "mess_sv".
11632
11633 The error message or object will by default be written to
11634 standard error, but this is subject to modification by a
11635 $SIG{__WARN__} handler.
11636
11637 Unlike with "vcroak", "pat" is not permitted to be null.
11638
11639 void vwarn(const char* pat, va_list* args)
11640
11641 warn This is an XS interface to Perl's "warn" function.
11642
11643 Take a sprintf-style format pattern and argument list. These
11644 are used to generate a string message. If the message does not
11645 end with a newline, then it will be extended with some
11646 indication of the current location in the code, as described
11647 for "mess_sv".
11648
11649 The error message or object will by default be written to
11650 standard error, but this is subject to modification by a
11651 $SIG{__WARN__} handler.
11652
11653 Unlike with "croak", "pat" is not permitted to be null.
11654
11655 void warn(const char* pat, ...)
11656
11657 warn_sv This is an XS interface to Perl's "warn" function.
11658
11659 "baseex" is the error message or object. If it is a reference,
11660 it will be used as-is. Otherwise it is used as a string, and
11661 if it does not end with a newline then it will be extended with
11662 some indication of the current location in the code, as
11663 described for "mess_sv".
11664
11665 The error message or object will by default be written to
11666 standard error, but this is subject to modification by a
11667 $SIG{__WARN__} handler.
11668
11669 To warn with a simple string message, the "warn" function may
11670 be more convenient.
11671
11672 void warn_sv(SV *baseex)
11673
11675 The following functions have been flagged as part of the public API,
11676 but are currently undocumented. Use them at your own risk, as the
11677 interfaces are subject to change. Functions that are not listed in
11678 this document are not intended for public use, and should NOT be used
11679 under any circumstances.
11680
11681 If you feel you need to use one of these functions, first send email to
11682 perl5-porters@perl.org <mailto:perl5-porters@perl.org>. It may be that
11683 there is a good reason for the function not being documented, and it
11684 should be removed from this list; or it may just be that no one has
11685 gotten around to documenting it. In the latter case, you will be asked
11686 to submit a patch to document the function. Once your patch is
11687 accepted, it will indicate that the interface is stable (unless it is
11688 explicitly marked otherwise) and usable by you.
11689
11690 CvDEPTH
11691 CvGV
11692 GetVars
11693 Gv_AMupdate
11694 PerlIO_close
11695 PerlIO_context_layers
11696 PerlIO_error
11697 PerlIO_fill
11698 PerlIO_flush
11699 PerlIO_get_bufsiz
11700 PerlIO_get_ptr
11701 PerlIO_read
11702 PerlIO_seek
11703 PerlIO_set_cnt
11704 PerlIO_setlinebuf
11705 PerlIO_stdout
11706 PerlIO_unread
11707 SvAMAGIC_off
11708 SvAMAGIC_on
11709 amagic_call
11710 amagic_deref_call
11711 any_dup
11712 atfork_lock
11713 atfork_unlock
11714 av_arylen_p
11715 av_iter_p
11716 block_gimme
11717 call_atexit
11718 call_list
11719 calloc
11720 cast_i32
11721 cast_iv
11722 cast_ulong
11723 cast_uv
11724 ck_warner
11725 ck_warner_d
11726 ckwarn
11727 ckwarn_d
11728 clear_defarray
11729 clone_params_del
11730 clone_params_new
11731 croak_nocontext
11732 csighandler
11733 csighandler1
11734 csighandler3
11735 cx_dump
11736 cx_dup
11737 cxinc
11738 deb
11739 deb_nocontext
11740 debop
11741 debprofdump
11742 debstack
11743 debstackptrs
11744 delimcpy
11745 despatch_signals
11746 die_nocontext
11747 dirp_dup
11748 do_aspawn
11749 do_close
11750 do_gv_dump
11751 do_gvgv_dump
11752 do_hv_dump
11753 do_join
11754 do_magic_dump
11755 do_op_dump
11756 do_open
11757 do_openn
11758 do_pmop_dump
11759 do_spawn
11760 do_spawn_nowait
11761 do_sprintf
11762 do_sv_dump
11763 doing_taint
11764 doref
11765 dounwind
11766 dowantarray
11767 dump_eval
11768 dump_form
11769 dump_indent
11770 dump_mstats
11771 dump_sub
11772 dump_vindent
11773 filter_del
11774 filter_read
11775 foldEQ_latin1
11776 form_nocontext
11777 fp_dup
11778 free_global_struct
11779 free_tmps
11780 get_context
11781 get_mstats
11782 get_op_descs
11783 get_op_names
11784 get_ppaddr
11785 get_vtbl
11786 gp_dup
11787 gp_free
11788 gp_ref
11789 gv_AVadd
11790 gv_HVadd
11791 gv_IOadd
11792 gv_SVadd
11793 gv_add_by_type
11794 gv_autoload4
11795 gv_autoload_pv
11796 gv_autoload_pvn
11797 gv_autoload_sv
11798 gv_check
11799 gv_dump
11800 gv_efullname3
11801 gv_efullname4
11802 gv_fetchfile
11803 gv_fetchfile_flags
11804 gv_fetchpv
11805 gv_fetchpvn_flags
11806 gv_fetchsv
11807 gv_fullname3
11808 gv_fullname4
11809 gv_handler
11810 gv_name_set
11811 he_dup
11812 hek_dup
11813 hv_common
11814 hv_common_key_len
11815 hv_delayfree_ent
11816 hv_eiter_p
11817 hv_eiter_set
11818 hv_free_ent
11819 hv_ksplit
11820 hv_name_set
11821 hv_placeholders_get
11822 hv_placeholders_set
11823 hv_rand_set
11824 hv_riter_p
11825 hv_riter_set
11826 ibcmp_utf8
11827 init_global_struct
11828 init_stacks
11829 init_tm
11830 is_lvalue_sub
11831 leave_scope
11832 load_module_nocontext
11833 magic_dump
11834 markstack_grow
11835 mess_nocontext
11836 mfree
11837 mg_dup
11838 mg_size
11839 mini_mktime
11840 moreswitches
11841 mro_get_from_name
11842 mro_set_mro
11843 mro_set_private_data
11844 my_atof
11845 my_chsize
11846 my_cxt_index
11847 my_cxt_init
11848 my_dirfd
11849 my_failure_exit
11850 my_fflush_all
11851 my_fork
11852 my_lstat
11853 my_pclose
11854 my_popen
11855 my_popen_list
11856 my_socketpair
11857 my_stat
11858 my_strftime
11859 newANONATTRSUB
11860 newANONHASH
11861 newANONLIST
11862 newANONSUB
11863 newATTRSUB
11864 newAVREF
11865 newCVREF
11866 newFORM
11867 newGVREF
11868 newGVgen
11869 newGVgen_flags
11870 newHVREF
11871 newHVhv
11872 newIO
11873 newMYSUB
11874 newPROG
11875 newRV
11876 newSUB
11877 newSVREF
11878 newSVpvf_nocontext
11879 newSVsv_flags
11880 new_stackinfo
11881 op_refcnt_lock
11882 op_refcnt_unlock
11883 parser_dup
11884 perl_alloc_using
11885 perl_clone_using
11886 perly_sighandler
11887 pmop_dump
11888 pop_scope
11889 pregcomp
11890 pregexec
11891 pregfree
11892 pregfree2
11893 ptr_table_fetch
11894 ptr_table_free
11895 ptr_table_new
11896 ptr_table_split
11897 ptr_table_store
11898 push_scope
11899 re_compile
11900 re_dup_guts
11901 reentrant_free
11902 reentrant_init
11903 reentrant_retry
11904 reentrant_size
11905 ref
11906 reg_named_buff_all
11907 reg_named_buff_exists
11908 reg_named_buff_fetch
11909 reg_named_buff_firstkey
11910 reg_named_buff_nextkey
11911 reg_named_buff_scalar
11912 regdump
11913 regdupe_internal
11914 regexec_flags
11915 regfree_internal
11916 reginitcolors
11917 regnext
11918 repeatcpy
11919 rsignal_state
11920 runops_debug
11921 runops_standard
11922 rvpv_dup
11923 safesyscalloc
11924 safesysfree
11925 safesysmalloc
11926 safesysrealloc
11927 save_I16
11928 save_I32
11929 save_I8
11930 save_adelete
11931 save_aelem
11932 save_aelem_flags
11933 save_alloc
11934 save_ary
11935 save_bool
11936 save_clearsv
11937 save_delete
11938 save_destructor
11939 save_destructor_x
11940 save_freeop
11941 save_freepv
11942 save_freesv
11943 save_generic_pvref
11944 save_generic_svref
11945 save_hdelete
11946 save_helem
11947 save_helem_flags
11948 save_hints
11949 save_hptr
11950 save_int
11951 save_item
11952 save_iv
11953 save_mortalizesv
11954 save_op
11955 save_padsv_and_mortalize
11956 save_pptr
11957 save_pushi32ptr
11958 save_pushptr
11959 save_pushptrptr
11960 save_re_context
11961 save_set_svflags
11962 save_shared_pvref
11963 save_sptr
11964 save_svref
11965 save_vptr
11966 savestack_grow
11967 savestack_grow_cnt
11968 scan_num
11969 scan_vstring
11970 seed
11971 set_context
11972 share_hek
11973 si_dup
11974 ss_dup
11975 stack_grow
11976 start_subparse
11977 str_to_version
11978 sv_2iv
11979 sv_2pv
11980 sv_2pvbyte_flags
11981 sv_2pvutf8_flags
11982 sv_2uv
11983 sv_catpvf_mg_nocontext
11984 sv_catpvf_nocontext
11985 sv_dup
11986 sv_dup_inc
11987 sv_peek
11988 sv_setpvf_mg_nocontext
11989 sv_setpvf_nocontext
11990 sys_init
11991 sys_init3
11992 sys_intern_clear
11993 sys_intern_dup
11994 sys_intern_init
11995 sys_term
11996 taint_env
11997 taint_proper
11998 unlnk
11999 unsharepvn
12000 vdeb
12001 vform
12002 vload_module
12003 vnewSVpvf
12004 vwarner
12005 warn_nocontext
12006 warner
12007 warner_nocontext
12008 whichsig
12009 whichsig_pv
12010 whichsig_pvn
12011 whichsig_sv
12012
12014 Until May 1997, this document was maintained by Jeff Okamoto
12015 <okamoto@corp.hp.com>. It is now maintained as part of Perl itself.
12016
12017 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
12018 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
12019 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
12020 Stephen McCamant, and Gurusamy Sarathy.
12021
12022 API Listing originally by Dean Roehrich <roehrich@cray.com>.
12023
12024 Updated to be autogenerated from comments in the source by Benjamin
12025 Stuhl.
12026
12028 config.h perlapio perlcall perlclib perlfilter perlguts perlintern
12029 perlmroapi perlxs perlxstut warnings
12030
12031
12032
12033perl v5.32.1 2021-03-31 PERLAPI(1)