Debian Codegraph @

upstream/debian-unstable/man1/perlapi.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "PERLAPI 1"
58 .TH PERLAPI 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 perlapi \- autogenerated documentation for the perl public API
65 .SH DESCRIPTION
66 .IX Xref "Perl API API api"
67 .IX Header "DESCRIPTION"
68 This file contains most of the documentation of the perl public API, as
69 generated by \fIembed.pl\fR. Specifically, it is a listing of functions,
70 macros, flags, and variables that may be used by extension writers. Besides
71 perlintern and \fIconfig.h\fR, some items are listed here as being actually
72 documented in another pod.
73 .PP
74 At the end is a list of functions which have yet
75 to be documented. Patches welcome! The interfaces of these are subject to
76 change without notice.
77 .PP
78 Some of the functions documented here are consolidated so that a single entry
79 serves for multiple functions which all do basically the same thing, but have
80 some slight differences. For example, one form might process magic, while
81 another doesn't. The name of each variation is listed at the top of the
82 single entry. But if all have the same signature (arguments and return type)
83 except for their names, only the usage for the base form is shown. If any
84 one of the forms has a different signature (such as returning \f(CW\*(C`const\*(C'\fR or
85 not) every function's signature is explicitly displayed.
86 .PP
87 Anything not listed here or in the other mentioned pods is not part of the
88 public API, and should not be used by extension writers at all. For these
89 reasons, blindly using functions listed in \fIproto.h\fR is to be avoided when
90 writing extensions.
91 .PP
92 In Perl, unlike C, a string of characters may generally contain embedded
93 \&\f(CW\*(C`NUL\*(C'\fR characters. Sometimes in the documentation a Perl string is referred
94 to as a "buffer" to distinguish it from a C string, but sometimes they are
95 both just referred to as strings.
96 .PP
97 Note that all Perl API global variables must be referenced with the \f(CW\*(C`PL_\*(C'\fR
98 prefix. Again, those not listed here are not to be used by extension writers,
99 and may be changed or removed without notice; same with macros.
100 Some macros are provided for compatibility with the older,
101 unadorned names, but this support may be disabled in a future release.
102 .PP
103 Perl was originally written to handle US-ASCII only (that is characters
104 whose ordinal numbers are in the range 0 \- 127).
105 And documentation and comments may still use the term ASCII, when
106 sometimes in fact the entire range from 0 \- 255 is meant.
107 .PP
108 The non-ASCII characters below 256 can have various meanings, depending on
109 various things. (See, most notably, perllocale.) But usually the whole
110 range can be referred to as ISO\-8859\-1. Often, the term "Latin\-1" (or
111 "Latin1") is used as an equivalent for ISO\-8859\-1. But some people treat
112 "Latin1" as referring just to the characters in the range 128 through 255, or
113 sometimes from 160 through 255.
114 This documentation uses "Latin1" and "Latin\-1" to refer to all 256 characters.
115 .PP
116 Note that Perl can be compiled and run under either ASCII or EBCDIC (See
117 perlebcdic). Most of the documentation (and even comments in the code)
118 ignore the EBCDIC possibility.
119 For almost all purposes the differences are transparent.
120 As an example, under EBCDIC,
121 instead of UTF\-8, UTF-EBCDIC is used to encode Unicode strings, and so
122 whenever this documentation refers to \f(CW\*(C`utf8\*(C'\fR
123 (and variants of that name, including in function names),
124 it also (essentially transparently) means \f(CW\*(C`UTF\-EBCDIC\*(C'\fR.
125 But the ordinals of characters differ between ASCII, EBCDIC, and
126 the UTF\- encodings, and a string encoded in UTF-EBCDIC may occupy a different
127 number of bytes than in UTF\-8.
128 .PP
129 The organization of this document is tentative and subject to change.
130 Suggestions and patches welcome
131 perl5\[email protected] <mailto:[email protected]>.
132 .PP
133 The sections in this document currently are
134 .IP """AV Handling""" 4
135 .IX Item """AV Handling"""
136 .PD 0
137 .IP """Callback Functions""" 4
138 .IX Item """Callback Functions"""
139 .IP """Casting""" 4
140 .IX Item """Casting"""
141 .IP """Character case changing""" 4
142 .IX Item """Character case changing"""
143 .IP """Character classification""" 4
144 .IX Item """Character classification"""
145 .IP """Compiler and Preprocessor information""" 4
146 .IX Item """Compiler and Preprocessor information"""
147 .IP """Compiler directives""" 4
148 .IX Item """Compiler directives"""
149 .IP """Compile-time scope hooks""" 4
150 .IX Item """Compile-time scope hooks"""
151 .IP """Concurrency""" 4
152 .IX Item """Concurrency"""
153 .IP """COPs and Hint Hashes""" 4
154 .IX Item """COPs and Hint Hashes"""
155 .IP """Custom Operators""" 4
156 .IX Item """Custom Operators"""
157 .IP """CV Handling""" 4
158 .IX Item """CV Handling"""
159 .IP """Debugging""" 4
160 .IX Item """Debugging"""
161 .IP """Display functions""" 4
162 .IX Item """Display functions"""
163 .IP """Embedding, Threads, and Interpreter Cloning""" 4
164 .IX Item """Embedding, Threads, and Interpreter Cloning"""
165 .IP """Errno""" 4
166 .IX Item """Errno"""
167 .IP """Exception Handling (simple) Macros""" 4
168 .IX Item """Exception Handling (simple) Macros"""
169 .IP """Filesystem configuration values""" 4
170 .IX Item """Filesystem configuration values"""
171 .IP """Floating point""" 4
172 .IX Item """Floating point"""
173 .IP """General Configuration""" 4
174 .IX Item """General Configuration"""
175 .IP """Global Variables""" 4
176 .IX Item """Global Variables"""
177 .IP """GV Handling and Stashes""" 4
178 .IX Item """GV Handling and Stashes"""
179 .IP """Hook manipulation""" 4
180 .IX Item """Hook manipulation"""
181 .IP """HV Handling""" 4
182 .IX Item """HV Handling"""
183 .IP """Input/Output""" 4
184 .IX Item """Input/Output"""
185 .IP """Integer""" 4
186 .IX Item """Integer"""
187 .IP """I/O Formats""" 4
188 .IX Item """I/O Formats"""
189 .IP """Lexer interface""" 4
190 .IX Item """Lexer interface"""
191 .IP """Locales""" 4
192 .IX Item """Locales"""
193 .IP """Magic""" 4
194 .IX Item """Magic"""
195 .IP """Memory Management""" 4
196 .IX Item """Memory Management"""
197 .IP """MRO""" 4
198 .IX Item """MRO"""
199 .IP """Multicall Functions""" 4
200 .IX Item """Multicall Functions"""
201 .IP """Numeric Functions""" 4
202 .IX Item """Numeric Functions"""
203 .IP """Optrees""" 4
204 .IX Item """Optrees"""
205 .IP """Pack and Unpack""" 4
206 .IX Item """Pack and Unpack"""
207 .IP """Pad Data Structures""" 4
208 .IX Item """Pad Data Structures"""
209 .IP """Password and Group access""" 4
210 .IX Item """Password and Group access"""
211 .IP """Paths to system commands""" 4
212 .IX Item """Paths to system commands"""
213 .IP """Prototype information""" 4
214 .IX Item """Prototype information"""
215 .IP """Reference-counted stack manipulation""" 4
216 .IX Item """Reference-counted stack manipulation"""
217 .IP """REGEXP Functions""" 4
218 .IX Item """REGEXP Functions"""
219 .IP """Reports and Formats""" 4
220 .IX Item """Reports and Formats"""
221 .IP """Signals""" 4
222 .IX Item """Signals"""
223 .IP """Site configuration""" 4
224 .IX Item """Site configuration"""
225 .IP """Sockets configuration values""" 4
226 .IX Item """Sockets configuration values"""
227 .IP """Source Filters""" 4
228 .IX Item """Source Filters"""
229 .IP """Stack Manipulation Macros""" 4
230 .IX Item """Stack Manipulation Macros"""
231 .IP """String Handling""" 4
232 .IX Item """String Handling"""
233 .IP """SV Flags""" 4
234 .IX Item """SV Flags"""
235 .IP """SV Handling""" 4
236 .IX Item """SV Handling"""
237 .IP """Tainting""" 4
238 .IX Item """Tainting"""
239 .IP """Time""" 4
240 .IX Item """Time"""
241 .IP """Typedef names""" 4
242 .IX Item """Typedef names"""
243 .IP """Unicode Support""" 4
244 .IX Item """Unicode Support"""
245 .IP """Utility Functions""" 4
246 .IX Item """Utility Functions"""
247 .IP """Versioning""" 4
248 .IX Item """Versioning"""
249 .IP """Warning and Dieing""" 4
250 .IX Item """Warning and Dieing"""
251 .IP """XS""" 4
252 .IX Item """XS"""
253 .IP """Undocumented elements""" 4
254 .IX Item """Undocumented elements"""
255 .PD
256 .PP
257 The listing below is alphabetical, case insensitive.
258 .SH "AV Handling"
259 .IX Header "AV Handling"
260 .ie n .IP """AV""" 4
261 .el .IP \f(CWAV\fR 4
262 .IX Item "AV"
263 Described in perlguts.
264 .ie n .IP """AvALLOC""" 4
265 .el .IP \f(CWAvALLOC\fR 4
266 .IX Item "AvALLOC"
267 Described in perlguts.
268 .RS 4
269 .Sp
270 .Vb 1
271 \& AvALLOC(AV* av)
272 .Ve
273 .RE
274 .RS 4
275 .RE
276 .ie n .IP """AvARRAY""" 4
277 .el .IP \f(CWAvARRAY\fR 4
278 .IX Xref "AvARRAY"
279 .IX Item "AvARRAY"
280 Returns a pointer to the AV's internal SV* array.
281 .Sp
282 This is useful for doing pointer arithmetic on the array.
283 If all you need is to look up an array element, then prefer \f(CW\*(C`av_fetch\*(C'\fR.
284 .RS 4
285 .Sp
286 .Vb 1
287 \& SV** AvARRAY(AV* av)
288 .Ve
289 .RE
290 .RS 4
291 .RE
292 .ie n .IP """av_clear""" 4
293 .el .IP \f(CWav_clear\fR 4
294 .IX Xref "av_clear"
295 .IX Item "av_clear"
296 Frees all the elements of an array, leaving it empty.
297 The XS equivalent of \f(CW\*(C`@array = ()\*(C'\fR. See also "av_undef".
298 .Sp
299 Note that it is possible that the actions of a destructor called directly
300 or indirectly by freeing an element of the array could cause the reference
301 count of the array itself to be reduced (e.g. by deleting an entry in the
302 symbol table). So it is a possibility that the AV could have been freed
303 (or even reallocated) on return from the call unless you hold a reference
304 to it.
305 .RS 4
306 .Sp
307 .Vb 1
308 \& void av_clear(AV *av)
309 .Ve
310 .RE
311 .RS 4
312 .RE
313 .ie n .IP """av_count""" 4
314 .el .IP \f(CWav_count\fR 4
315 .IX Xref "av_count"
316 .IX Item "av_count"
317 Returns the number of elements in the array \f(CW\*(C`av\*(C'\fR. This is the true length of
318 the array, including any undefined elements. It is always the same as
319 \&\f(CW\*(C`av_top_index(av)\ +\ 1\*(C'\fR.
320 .RS 4
321 .Sp
322 .Vb 1
323 \& Size_t av_count(AV *av)
324 .Ve
325 .RE
326 .RS 4
327 .RE
328 .ie n .IP """av_create_and_push""" 4
329 .el .IP \f(CWav_create_and_push\fR 4
330 .IX Xref "av_create_and_push"
331 .IX Item "av_create_and_push"
332 Push an SV onto the end of the array, creating the array if necessary.
333 A small internal helper function to remove a commonly duplicated idiom.
334 .Sp
335 NOTE: \f(CW\*(C`av_create_and_push\*(C'\fR must be explicitly called as
336 \&\f(CW\*(C`Perl_av_create_and_push\*(C'\fR
337 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
338 .RS 4
339 .Sp
340 .Vb 2
341 \& void Perl_av_create_and_push(pTHX_ AV ** const avp,
342 \& SV * const val)
343 .Ve
344 .RE
345 .RS 4
346 .RE
347 .ie n .IP """av_create_and_unshift_one""" 4
348 .el .IP \f(CWav_create_and_unshift_one\fR 4
349 .IX Xref "av_create_and_unshift_one"
350 .IX Item "av_create_and_unshift_one"
351 Unshifts an SV onto the beginning of the array, creating the array if
352 necessary.
353 A small internal helper function to remove a commonly duplicated idiom.
354 .Sp
355 NOTE: \f(CW\*(C`av_create_and_unshift_one\*(C'\fR must be explicitly called as
356 \&\f(CW\*(C`Perl_av_create_and_unshift_one\*(C'\fR
357 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
358 .RS 4
359 .Sp
360 .Vb 2
361 \& SV ** Perl_av_create_and_unshift_one(pTHX_ AV ** const avp,
362 \& SV * const val)
363 .Ve
364 .RE
365 .RS 4
366 .RE
367 .ie n .IP """av_delete""" 4
368 .el .IP \f(CWav_delete\fR 4
369 .IX Xref "av_delete"
370 .IX Item "av_delete"
371 Deletes the element indexed by \f(CW\*(C`key\*(C'\fR from the array, makes the element
372 mortal, and returns it. If \f(CW\*(C`flags\*(C'\fR equals \f(CW\*(C`G_DISCARD\*(C'\fR, the element is
373 freed and NULL is returned. NULL is also returned if \f(CW\*(C`key\*(C'\fR is out of
374 range.
375 .Sp
376 Perl equivalent: \f(CW\*(C`splice(@myarray,\ $key,\ 1,\ undef)\*(C'\fR (with the
377 \&\f(CW\*(C`splice\*(C'\fR in void context if \f(CW\*(C`G_DISCARD\*(C'\fR is present).
378 .RS 4
379 .Sp
380 .Vb 1
381 \& SV * av_delete(AV *av, SSize_t key, I32 flags)
382 .Ve
383 .RE
384 .RS 4
385 .RE
386 .ie n .IP """av_exists""" 4
387 .el .IP \f(CWav_exists\fR 4
388 .IX Xref "av_exists"
389 .IX Item "av_exists"
390 Returns true if the element indexed by \f(CW\*(C`key\*(C'\fR has been initialized.
391 .Sp
392 This relies on the fact that uninitialized array elements are set to
393 \&\f(CW\*(C`NULL\*(C'\fR.
394 .Sp
395 Perl equivalent: \f(CWexists($myarray[$key])\fR.
396 .RS 4
397 .Sp
398 .Vb 1
399 \& bool av_exists(AV *av, SSize_t key)
400 .Ve
401 .RE
402 .RS 4
403 .RE
404 .ie n .IP """av_extend""" 4
405 .el .IP \f(CWav_extend\fR 4
406 .IX Xref "av_extend"
407 .IX Item "av_extend"
408 Pre-extend an array so that it is capable of storing values at indexes
409 \&\f(CW\*(C`0..key\*(C'\fR. Thus \f(CW\*(C`av_extend(av,99)\*(C'\fR guarantees that the array can store 100
410 elements, i.e. that \f(CW\*(C`av_store(av, 0, sv)\*(C'\fR through \f(CW\*(C`av_store(av, 99, sv)\*(C'\fR
411 on a plain array will work without any further memory allocation.
412 .Sp
413 If the av argument is a tied array then will call the \f(CW\*(C`EXTEND\*(C'\fR tied
414 array method with an argument of \f(CW\*(C`(key+1)\*(C'\fR.
415 .RS 4
416 .Sp
417 .Vb 1
418 \& void av_extend(AV *av, SSize_t key)
419 .Ve
420 .RE
421 .RS 4
422 .RE
423 .ie n .IP """av_fetch""" 4
424 .el .IP \f(CWav_fetch\fR 4
425 .IX Xref "av_fetch"
426 .IX Item "av_fetch"
427 Returns the SV at the specified index in the array. The \f(CW\*(C`key\*(C'\fR is the
428 index. If \f(CW\*(C`lval\*(C'\fR is true, you are guaranteed to get a real SV back (in case
429 it wasn't real before), which you can then modify. Check that the return
430 value is non-NULL before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR.
431 .Sp
432 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for
433 more information on how to use this function on tied arrays.
434 .Sp
435 The rough perl equivalent is \f(CW$myarray[$key]\fR.
436 .RS 4
437 .Sp
438 .Vb 1
439 \& SV ** av_fetch(AV *av, SSize_t key, I32 lval)
440 .Ve
441 .RE
442 .RS 4
443 .RE
444 .ie n .IP """AvFILL""" 4
445 .el .IP \f(CWAvFILL\fR 4
446 .IX Xref "AvFILL"
447 .IX Item "AvFILL"
448 Same as \f(CW"av_top_index"\fR or \f(CW"av_tindex"\fR.
449 .RS 4
450 .Sp
451 .Vb 1
452 \& SSize_t AvFILL(AV* av)
453 .Ve
454 .RE
455 .RS 4
456 .RE
457 .ie n .IP """av_fill""" 4
458 .el .IP \f(CWav_fill\fR 4
459 .IX Xref "av_fill"
460 .IX Item "av_fill"
461 Set the highest index in the array to the given number, equivalent to
462 Perl's \f(CW\*(C`$#array\ =\ $fill;\*(C'\fR.
463 .Sp
464 The number of elements in the array will be \f(CW\*(C`fill\ +\ 1\*(C'\fR after
465 \&\f(CWav_fill()\fR returns. If the array was previously shorter, then the
466 additional elements appended are set to NULL. If the array
467 was longer, then the excess elements are freed. \f(CW\*(C`av_fill(av,\ \-1)\*(C'\fR is
468 the same as \f(CWav_clear(av)\fR.
469 .RS 4
470 .Sp
471 .Vb 1
472 \& void av_fill(AV *av, SSize_t fill)
473 .Ve
474 .RE
475 .RS 4
476 .RE
477 .ie n .IP """av_len""" 4
478 .el .IP \f(CWav_len\fR 4
479 .IX Xref "av_len"
480 .IX Item "av_len"
481 Same as "av_top_index". Note that, unlike what the name implies, it returns
482 the maximum index in the array. This is unlike "sv_len", which returns what
483 you would expect.
484 .Sp
485 \&\fBTo get the true number of elements in the array, instead use \fR\f(CB"av_count"\fR.
486 .RS 4
487 .Sp
488 .Vb 1
489 \& SSize_t av_len(AV *av)
490 .Ve
491 .RE
492 .RS 4
493 .RE
494 .ie n .IP """av_make""" 4
495 .el .IP \f(CWav_make\fR 4
496 .IX Xref "av_make"
497 .IX Item "av_make"
498 Creates a new AV and populates it with a list (\f(CW**strp\fR, length \f(CW\*(C`size\*(C'\fR) of
499 SVs. A copy is made of each SV, so their refcounts are not changed. The new
500 AV will have a reference count of 1.
501 .Sp
502 Perl equivalent: \f(CW\*(C`my @new_array = ($scalar1, $scalar2, $scalar3...);\*(C'\fR
503 .RS 4
504 .Sp
505 .Vb 1
506 \& AV * av_make(SSize_t size, SV **strp)
507 .Ve
508 .RE
509 .RS 4
510 .RE
511 .ie n .IP """av_pop""" 4
512 .el .IP \f(CWav_pop\fR 4
513 .IX Xref "av_pop"
514 .IX Item "av_pop"
515 Removes one SV from the end of the array, reducing its size by one and
516 returning the SV (transferring control of one reference count) to the
517 caller. Returns \f(CW&PL_sv_undef\fR if the array is empty.
518 .Sp
519 Perl equivalent: \f(CW\*(C`pop(@myarray);\*(C'\fR
520 .RS 4
521 .Sp
522 .Vb 1
523 \& SV * av_pop(AV *av)
524 .Ve
525 .RE
526 .RS 4
527 .RE
528 .ie n .IP """av_push""" 4
529 .el .IP \f(CWav_push\fR 4
530 .IX Xref "av_push"
531 .IX Item "av_push"
532 Pushes an SV (transferring control of one reference count) onto the end of the
533 array. The array will grow automatically to accommodate the addition.
534 .Sp
535 Perl equivalent: \f(CW\*(C`push @myarray, $val;\*(C'\fR.
536 .RS 4
537 .Sp
538 .Vb 1
539 \& void av_push(AV *av, SV *val)
540 .Ve
541 .RE
542 .RS 4
543 .RE
544 .ie n .IP """av_push_simple""" 4
545 .el .IP \f(CWav_push_simple\fR 4
546 .IX Xref "av_push_simple"
547 .IX Item "av_push_simple"
548 This is a cut-down version of av_push that assumes that the array is very
549 straightforward \- no magic, not readonly, and AvREAL \- and that \f(CW\*(C`key\*(C'\fR is
550 not less than \-1. This function MUST NOT be used in situations where any
551 of those assumptions may not hold.
552 .Sp
553 Pushes an SV (transferring control of one reference count) onto the end of the
554 array. The array will grow automatically to accommodate the addition.
555 .Sp
556 Perl equivalent: \f(CW\*(C`push @myarray, $val;\*(C'\fR.
557 .RS 4
558 .Sp
559 .Vb 1
560 \& void av_push_simple(AV *av, SV *val)
561 .Ve
562 .RE
563 .RS 4
564 .RE
565 .ie n .IP """av_shift""" 4
566 .el .IP \f(CWav_shift\fR 4
567 .IX Xref "av_shift"
568 .IX Item "av_shift"
569 Removes one SV from the start of the array, reducing its size by one and
570 returning the SV (transferring control of one reference count) to the
571 caller. Returns \f(CW&PL_sv_undef\fR if the array is empty.
572 .Sp
573 Perl equivalent: \f(CW\*(C`shift(@myarray);\*(C'\fR
574 .RS 4
575 .Sp
576 .Vb 1
577 \& SV * av_shift(AV *av)
578 .Ve
579 .RE
580 .RS 4
581 .RE
582 .ie n .IP """av_store""" 4
583 .el .IP \f(CWav_store\fR 4
584 .IX Xref "av_store"
585 .IX Item "av_store"
586 Stores an SV in an array. The array index is specified as \f(CW\*(C`key\*(C'\fR. The
587 return value will be \f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not
588 need to be actually stored within the array (as in the case of tied
589 arrays). Otherwise, it can be dereferenced
590 to get the \f(CW\*(C`SV*\*(C'\fR that was stored
591 there (= \f(CW\*(C`val\*(C'\fR)).
592 .Sp
593 Note that the caller is responsible for suitably incrementing the reference
594 count of \f(CW\*(C`val\*(C'\fR before the call, and decrementing it if the function
595 returned \f(CW\*(C`NULL\*(C'\fR.
596 .Sp
597 Approximate Perl equivalent: \f(CW\*(C`splice(@myarray, $key, 1, $val)\*(C'\fR.
598 .Sp
599 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for
600 more information on how to use this function on tied arrays.
601 .RS 4
602 .Sp
603 .Vb 1
604 \& SV ** av_store(AV *av, SSize_t key, SV *val)
605 .Ve
606 .RE
607 .RS 4
608 .RE
609 .ie n .IP """av_tindex""" 4
610 .el .IP \f(CWav_tindex\fR 4
611 .IX Item "av_tindex"
612 .PD 0
613 .ie n .IP """av_top_index""" 4
614 .el .IP \f(CWav_top_index\fR 4
615 .IX Xref "av_tindex av_top_index"
616 .IX Item "av_top_index"
617 .PD
618 These behave identically.
619 If the array \f(CW\*(C`av\*(C'\fR is empty, these return \-1; otherwise they return the maximum
620 value of the indices of all the array elements which are currently defined in
621 \&\f(CW\*(C`av\*(C'\fR.
622 .Sp
623 They process 'get' magic.
624 .Sp
625 The Perl equivalent for these is \f(CW$#av\fR.
626 .Sp
627 Use \f(CW"av_count"\fR to get the number of elements in an array.
628 .RS 4
629 .Sp
630 .Vb 1
631 \& SSize_t av_tindex(AV *av)
632 .Ve
633 .RE
634 .RS 4
635 .RE
636 .ie n .IP """av_undef""" 4
637 .el .IP \f(CWav_undef\fR 4
638 .IX Xref "av_undef"
639 .IX Item "av_undef"
640 Undefines the array. The XS equivalent of \f(CWundef(@array)\fR.
641 .Sp
642 As well as freeing all the elements of the array (like \f(CWav_clear()\fR), this
643 also frees the memory used by the av to store its list of scalars.
644 .Sp
645 See "av_clear" for a note about the array possibly being invalid on
646 return.
647 .RS 4
648 .Sp
649 .Vb 1
650 \& void av_undef(AV *av)
651 .Ve
652 .RE
653 .RS 4
654 .RE
655 .ie n .IP """av_unshift""" 4
656 .el .IP \f(CWav_unshift\fR 4
657 .IX Xref "av_unshift"
658 .IX Item "av_unshift"
659 Unshift the given number of \f(CW\*(C`undef\*(C'\fR values onto the beginning of the
660 array. The array will grow automatically to accommodate the addition.
661 .Sp
662 Perl equivalent: \f(CW\*(C`unshift\ @myarray,\ ((undef)\ x\ $num);\*(C'\fR
663 .RS 4
664 .Sp
665 .Vb 1
666 \& void av_unshift(AV *av, SSize_t num)
667 .Ve
668 .RE
669 .RS 4
670 .RE
671 .ie n .IP """get_av""" 4
672 .el .IP \f(CWget_av\fR 4
673 .IX Xref "get_av"
674 .IX Item "get_av"
675 Returns the AV of the specified Perl global or package array with the given
676 name (so it won't work on lexical variables). \f(CW\*(C`flags\*(C'\fR are passed
677 to \f(CW\*(C`gv_fetchpv\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
678 Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero
679 (ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is
680 returned.
681 .Sp
682 Perl equivalent: \f(CW\*(C`@{"$name"}\*(C'\fR.
683 .Sp
684 NOTE: the \f(CWperl_get_av()\fR form is \fBdeprecated\fR.
685 .RS 4
686 .Sp
687 .Vb 1
688 \& AV * get_av(const char *name, I32 flags)
689 .Ve
690 .RE
691 .RS 4
692 .RE
693 .ie n .IP """newAV""" 4
694 .el .IP \f(CWnewAV\fR 4
695 .IX Item "newAV"
696 .PD 0
697 .ie n .IP """newAV_mortal""" 4
698 .el .IP \f(CWnewAV_mortal\fR 4
699 .IX Item "newAV_mortal"
700 .ie n .IP """newAV_alloc_x""" 4
701 .el .IP \f(CWnewAV_alloc_x\fR 4
702 .IX Item "newAV_alloc_x"
703 .ie n .IP """newAV_alloc_xz""" 4
704 .el .IP \f(CWnewAV_alloc_xz\fR 4
705 .IX Xref "newAV newAV_mortal newAV_alloc_x newAV_alloc_xz"
706 .IX Item "newAV_alloc_xz"
707 .PD
708 These all create a new AV, setting the reference count to 1. If you also know
709 the initial elements of the array with, see "\f(CW\*(C`av_make\*(C'\fR".
710 .Sp
711 As background, an array consists of three things:
712 .RS 4
713 .IP 1. 4
714 A data structure containing information about the array as a whole, such as its
715 size and reference count.
716 .IP 2. 4
717 A C language array of pointers to the individual elements. These are treated
718 as pointers to SVs, so all must be castable to SV*.
719 .IP 3. 4
720 The individual elements themselves. These could be, for instance, SVs and/or
721 AVs and/or HVs, etc.
722 .RE
723 .RS 4
724 .Sp
725 An empty array need only have the first data structure, and all these functions
726 create that. They differ in what else they do, as follows:
727 .ie n .IP """newAV"" form" 4
728 .el .IP "\f(CWnewAV\fR form" 4
729 .IX Item "newAV form"
730 This does nothing beyond creating the whole-array data structure.
731 The Perl equivalent is approximately \f(CW\*(C`my\ @array;\*(C'\fR
732 .Sp
733 This is useful when the minimum size of the array could be zero (perhaps there
734 are likely code paths that will entirely skip using it).
735 .Sp
736 If the array does get used, the pointers data structure will need to be
737 allocated at that time. This will end up being done by "av_extend">,
738 either explicitly:
739 .Sp
740 .Vb 1
741 \& av_extend(av, len);
742 .Ve
743 .Sp
744 or implicitly when the first element is stored:
745 .Sp
746 .Vb 1
747 \& (void)av_store(av, 0, sv);
748 .Ve
749 .Sp
750 Unused array elements are typically initialized by \f(CW\*(C`av_extend\*(C'\fR.
751 .ie n .IP """newAV_mortal"" form" 4
752 .el .IP "\f(CWnewAV_mortal\fR form" 4
753 .IX Item "newAV_mortal form"
754 This also creates the whole-array data structure, but also mortalises it.
755 (That is to say, a reference to the AV is added to the \f(CW\*(C`temps\*(C'\fR stack.)
756 .ie n .IP """newAV_alloc_x"" form" 4
757 .el .IP "\f(CWnewAV_alloc_x\fR form" 4
758 .IX Item "newAV_alloc_x form"
759 This effectively does a \f(CW\*(C`newAV\*(C'\fR followed by also allocating (uninitialized)
760 space for the pointers array. This is used when you know ahead of time the
761 likely minimum size of the array. It is more efficient to do this than doing a
762 plain \f(CW\*(C`newAV\*(C'\fR followed by an \f(CW\*(C`av_extend\*(C'\fR.
763 .Sp
764 Of course the array can be extended later should it become necessary.
765 .Sp
766 \&\f(CW\*(C`size\*(C'\fR must be at least 1.
767 .ie n .IP """newAV_alloc_xz"" form" 4
768 .el .IP "\f(CWnewAV_alloc_xz\fR form" 4
769 .IX Item "newAV_alloc_xz form"
770 This is \f(CW\*(C`newAV_alloc_x\*(C'\fR, but initializes each pointer in it to NULL. This
771 gives added safety to guard against them being read before being set.
772 .Sp
773 \&\f(CW\*(C`size\*(C'\fR must be at least 1.
774 .RE
775 .RS 4
776 .Sp
777 The following examples all result in an array that can fit four elements
778 (indexes 0 .. 3):
779 .Sp
780 .Vb 2
781 \& AV *av = newAV();
782 \& av_extend(av, 3);
783 \&
784 \& AV *av = newAV_alloc_x(4);
785 \&
786 \& AV *av = newAV_alloc_xz(4);
787 .Ve
788 .Sp
789 In contrast, the following examples allocate an array that is only guaranteed
790 to fit one element without extending:
791 .Sp
792 .Vb 2
793 \& AV *av = newAV_alloc_x(1);
794 \& AV *av = newAV_alloc_xz(1);
795 .Ve
796 .Sp
797 .Vb 4
798 \& AV * newAV ()
799 \& AV * newAV_mortal ()
800 \& AV * newAV_alloc_x (SSize_t size)
801 \& AV * newAV_alloc_xz(SSize_t size)
802 .Ve
803 .RE
804 .RS 4
805 .RE
806 .ie n .IP """newAVav""" 4
807 .el .IP \f(CWnewAVav\fR 4
808 .IX Xref "newAVav"
809 .IX Item "newAVav"
810 Creates a new AV and populates it with values copied from an existing AV. The
811 new AV will have a reference count of 1, and will contain newly created SVs
812 copied from the original SV. The original source will remain unchanged.
813 .Sp
814 Perl equivalent: \f(CW\*(C`my @new_array = @existing_array;\*(C'\fR
815 .RS 4
816 .Sp
817 .Vb 1
818 \& AV * newAVav(AV *oav)
819 .Ve
820 .RE
821 .RS 4
822 .RE
823 .ie n .IP """newAVhv""" 4
824 .el .IP \f(CWnewAVhv\fR 4
825 .IX Xref "newAVhv"
826 .IX Item "newAVhv"
827 Creates a new AV and populates it with keys and values copied from an existing
828 HV. The new AV will have a reference count of 1, and will contain newly
829 created SVs copied from the original HV. The original source will remain
830 unchanged.
831 .Sp
832 Perl equivalent: \f(CW\*(C`my @new_array = %existing_hash;\*(C'\fR
833 .RS 4
834 .Sp
835 .Vb 1
836 \& AV * newAVhv(HV *ohv)
837 .Ve
838 .RE
839 .RS 4
840 .RE
841 .ie n .IP """Nullav""" 4
842 .el .IP \f(CWNullav\fR 4
843 .IX Xref "Nullav"
844 .IX Item "Nullav"
845 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullav\*(C'\fR
846 from a future release of Perl. Do not use it for
847 new code; remove it from existing code.
848 .Sp
849 Null AV pointer.
850 .Sp
851 (deprecated \- use \f(CW\*(C`(AV *)NULL\*(C'\fR instead)
852 .SH "Callback Functions"
853 .IX Xref "G_METHOD G_METHOD_NAMED G_RETHROW G_USEHINTS SAVEf_KEEPOLDELEM SAVEf_SETMAGIC"
854 .IX Header "Callback Functions"
855 .ie n .IP """call_argv""" 4
856 .el .IP \f(CWcall_argv\fR 4
857 .IX Xref "call_argv"
858 .IX Item "call_argv"
859 Performs a callback to the specified named and package-scoped Perl subroutine
860 with \f(CW\*(C`argv\*(C'\fR (a \f(CW\*(C`NULL\*(C'\fR\-terminated array of strings) as arguments. See
861 perlcall.
862 .Sp
863 Approximate Perl equivalent: \f(CW\*(C`&{"$sub_name"}(@$argv)\*(C'\fR.
864 .Sp
865 NOTE: the \f(CWperl_call_argv()\fR form is \fBdeprecated\fR.
866 .RS 4
867 .Sp
868 .Vb 1
869 \& SSize_t call_argv(const char *sub_name, I32 flags, char **argv)
870 .Ve
871 .RE
872 .RS 4
873 .RE
874 .ie n .IP """call_method""" 4
875 .el .IP \f(CWcall_method\fR 4
876 .IX Xref "call_method"
877 .IX Item "call_method"
878 Performs a callback to the specified Perl method. The blessed object must
879 be on the stack. See perlcall.
880 .Sp
881 NOTE: the \f(CWperl_call_method()\fR form is \fBdeprecated\fR.
882 .RS 4
883 .Sp
884 .Vb 1
885 \& SSize_t call_method(const char *methname, I32 flags)
886 .Ve
887 .RE
888 .RS 4
889 .RE
890 .ie n .IP """call_pv""" 4
891 .el .IP \f(CWcall_pv\fR 4
892 .IX Xref "call_pv"
893 .IX Item "call_pv"
894 Performs a callback to the specified Perl sub. See perlcall.
895 .Sp
896 NOTE: the \f(CWperl_call_pv()\fR form is \fBdeprecated\fR.
897 .RS 4
898 .Sp
899 .Vb 1
900 \& SSize_t call_pv(const char *sub_name, I32 flags)
901 .Ve
902 .RE
903 .RS 4
904 .RE
905 .ie n .IP """call_sv""" 4
906 .el .IP \f(CWcall_sv\fR 4
907 .IX Xref "call_sv"
908 .IX Item "call_sv"
909 Performs a callback to the Perl sub specified by the SV.
910 .Sp
911 If neither the \f(CW\*(C`G_METHOD\*(C'\fR nor \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, the
912 SV may be any of a CV, a GV, a reference to a CV, a reference to a GV
913 or \f(CWSvPV(sv)\fR will be used as the name of the sub to call.
914 .Sp
915 If the \f(CW\*(C`G_METHOD\*(C'\fR flag is supplied, the SV may be a reference to a CV or
916 \&\f(CWSvPV(sv)\fR will be used as the name of the method to call.
917 .Sp
918 If the \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, \f(CWSvPV(sv)\fR will be used as
919 the name of the method to call.
920 .Sp
921 Some other values are treated specially for internal use and should
922 not be depended on.
923 .Sp
924 See perlcall.
925 .Sp
926 NOTE: the \f(CWperl_call_sv()\fR form is \fBdeprecated\fR.
927 .RS 4
928 .Sp
929 .Vb 1
930 \& SSize_t call_sv(SV *sv, I32 flags)
931 .Ve
932 .RE
933 .RS 4
934 .RE
935 .ie n .IP """DESTRUCTORFUNC_NOCONTEXT_t""" 4
936 .el .IP \f(CWDESTRUCTORFUNC_NOCONTEXT_t\fR 4
937 .IX Item "DESTRUCTORFUNC_NOCONTEXT_t"
938 Described in perlguts.
939 .ie n .IP """DESTRUCTORFUNC_t""" 4
940 .el .IP \f(CWDESTRUCTORFUNC_t\fR 4
941 .IX Item "DESTRUCTORFUNC_t"
942 Described in perlguts.
943 .ie n .IP """ENTER""" 4
944 .el .IP \f(CWENTER\fR 4
945 .IX Xref "ENTER"
946 .IX Item "ENTER"
947 Opening bracket on a callback. See \f(CW"LEAVE"\fR and perlcall.
948 .RS 4
949 .Sp
950 .Vb 1
951 \& ENTER;
952 .Ve
953 .RE
954 .RS 4
955 .RE
956 .ie n .IP """ENTER_with_name""" 4
957 .el .IP \f(CWENTER_with_name\fR 4
958 .IX Xref "ENTER_with_name"
959 .IX Item "ENTER_with_name"
960 Same as \f(CW"ENTER"\fR, but when debugging is enabled it also associates the
961 given literal string with the new scope.
962 .RS 4
963 .Sp
964 .Vb 1
965 \& ENTER_with_name("name");
966 .Ve
967 .RE
968 .RS 4
969 .RE
970 .ie n .IP """eval_pv""" 4
971 .el .IP \f(CWeval_pv\fR 4
972 .IX Xref "eval_pv"
973 .IX Item "eval_pv"
974 Tells Perl to \f(CW\*(C`eval\*(C'\fR the given string in scalar context and return an SV* result.
975 .Sp
976 NOTE: the \f(CWperl_eval_pv()\fR form is \fBdeprecated\fR.
977 .RS 4
978 .Sp
979 .Vb 1
980 \& SV * eval_pv(const char *p, I32 croak_on_error)
981 .Ve
982 .RE
983 .RS 4
984 .RE
985 .ie n .IP """eval_sv""" 4
986 .el .IP \f(CWeval_sv\fR 4
987 .IX Xref "eval_sv"
988 .IX Item "eval_sv"
989 Tells Perl to \f(CW\*(C`eval\*(C'\fR the string in the SV. It supports the same flags
990 as \f(CW\*(C`call_sv\*(C'\fR, with the obvious exception of \f(CW\*(C`G_EVAL\*(C'\fR. See perlcall.
991 .Sp
992 The \f(CW\*(C`G_RETHROW\*(C'\fR flag can be used if you only need \fBeval_sv()\fR to
993 execute code specified by a string, but not catch any errors.
994 .Sp
995 By default the code is compiled and executed with the default hints,
996 such as strict and features. Set \f(CW\*(C`G_USEHINTS\*(C'\fR in flags to use the
997 current hints from \f(CW\*(C`PL_curcop\*(C'\fR.
998 .Sp
999 NOTE: the \f(CWperl_eval_sv()\fR form is \fBdeprecated\fR.
1000 .RS 4
1001 .Sp
1002 .Vb 1
1003 \& SSize_t eval_sv(SV *sv, I32 flags)
1004 .Ve
1005 .RE
1006 .RS 4
1007 .RE
1008 .ie n .IP """FREETMPS""" 4
1009 .el .IP \f(CWFREETMPS\fR 4
1010 .IX Xref "FREETMPS"
1011 .IX Item "FREETMPS"
1012 Closing bracket for temporaries on a callback. See \f(CW"SAVETMPS"\fR and
1013 perlcall.
1014 .RS 4
1015 .Sp
1016 .Vb 1
1017 \& FREETMPS;
1018 .Ve
1019 .RE
1020 .RS 4
1021 .RE
1022 .ie n .IP """G_DISCARD""" 4
1023 .el .IP \f(CWG_DISCARD\fR 4
1024 .IX Item "G_DISCARD"
1025 Described in perlcall.
1026 .ie n .IP """G_EVAL""" 4
1027 .el .IP \f(CWG_EVAL\fR 4
1028 .IX Item "G_EVAL"
1029 Described in perlcall.
1030 .ie n .IP """GIMME""" 4
1031 .el .IP \f(CWGIMME\fR 4
1032 .IX Xref "GIMME"
1033 .IX Item "GIMME"
1034 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`GIMME\*(C'\fR
1035 from a future release of Perl. Do not use it for
1036 new code; remove it from existing code.
1037 .Sp
1038 A backward-compatible version of \f(CW\*(C`GIMME_V\*(C'\fR which can only return
1039 \&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_LIST\*(C'\fR; in a void context, it returns \f(CW\*(C`G_SCALAR\*(C'\fR.
1040 Deprecated. Use \f(CW\*(C`GIMME_V\*(C'\fR instead.
1041 .RS 4
1042 .Sp
1043 .Vb 1
1044 \& U32 GIMME
1045 .Ve
1046 .RE
1047 .RS 4
1048 .RE
1049 .ie n .IP """GIMME_V""" 4
1050 .el .IP \f(CWGIMME_V\fR 4
1051 .IX Xref "GIMME_V"
1052 .IX Item "GIMME_V"
1053 The XSUB-writer's equivalent to Perl's \f(CW\*(C`wantarray\*(C'\fR. Returns \f(CW\*(C`G_VOID\*(C'\fR,
1054 \&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_LIST\*(C'\fR for void, scalar or list context,
1055 respectively. See perlcall for a usage example.
1056 .RS 4
1057 .Sp
1058 .Vb 1
1059 \& U32 GIMME_V
1060 .Ve
1061 .RE
1062 .RS 4
1063 .RE
1064 .ie n .IP """G_KEEPERR""" 4
1065 .el .IP \f(CWG_KEEPERR\fR 4
1066 .IX Item "G_KEEPERR"
1067 Described in perlcall.
1068 .ie n .IP """G_LIST""" 4
1069 .el .IP \f(CWG_LIST\fR 4
1070 .IX Item "G_LIST"
1071 Described in perlcall.
1072 .ie n .IP """G_NOARGS""" 4
1073 .el .IP \f(CWG_NOARGS\fR 4
1074 .IX Item "G_NOARGS"
1075 Described in perlcall.
1076 .ie n .IP """G_SCALAR""" 4
1077 .el .IP \f(CWG_SCALAR\fR 4
1078 .IX Item "G_SCALAR"
1079 Described in perlcall.
1080 .ie n .IP """G_VOID""" 4
1081 .el .IP \f(CWG_VOID\fR 4
1082 .IX Item "G_VOID"
1083 Described in perlcall.
1084 .ie n .IP """is_lvalue_sub""" 4
1085 .el .IP \f(CWis_lvalue_sub\fR 4
1086 .IX Xref "is_lvalue_sub"
1087 .IX Item "is_lvalue_sub"
1088 Returns non-zero if the sub calling this function is being called in an lvalue
1089 context. Returns 0 otherwise.
1090 .RS 4
1091 .Sp
1092 .Vb 1
1093 \& I32 is_lvalue_sub()
1094 .Ve
1095 .RE
1096 .RS 4
1097 .RE
1098 .ie n .IP """LEAVE""" 4
1099 .el .IP \f(CWLEAVE\fR 4
1100 .IX Xref "LEAVE"
1101 .IX Item "LEAVE"
1102 Closing bracket on a callback. See \f(CW"ENTER"\fR and perlcall.
1103 .RS 4
1104 .Sp
1105 .Vb 1
1106 \& LEAVE;
1107 .Ve
1108 .RE
1109 .RS 4
1110 .RE
1111 .ie n .IP """LEAVE_with_name""" 4
1112 .el .IP \f(CWLEAVE_with_name\fR 4
1113 .IX Xref "LEAVE_with_name"
1114 .IX Item "LEAVE_with_name"
1115 Same as \f(CW"LEAVE"\fR, but when debugging is enabled it first checks that the
1116 scope has the given name. \f(CW\*(C`name\*(C'\fR must be a literal string.
1117 .RS 4
1118 .Sp
1119 .Vb 1
1120 \& LEAVE_with_name("name");
1121 .Ve
1122 .RE
1123 .RS 4
1124 .RE
1125 .ie n .IP """MORTALDESTRUCTOR_SV""" 4
1126 .el .IP \f(CWMORTALDESTRUCTOR_SV\fR 4
1127 .IX Item "MORTALDESTRUCTOR_SV"
1128 Described in perlguts.
1129 .RS 4
1130 .Sp
1131 .Vb 1
1132 \& MORTALDESTRUCTOR_SV(SV *coderef, SV *args)
1133 .Ve
1134 .RE
1135 .RS 4
1136 .RE
1137 .ie n .IP """mortal_destructor_sv""" 4
1138 .el .IP \f(CWmortal_destructor_sv\fR 4
1139 .IX Xref "mortal_destructor_sv"
1140 .IX Item "mortal_destructor_sv"
1141 This function arranges for either a Perl code reference, or a C function
1142 reference to be called at the \fBend of the current statement\fR.
1143 .Sp
1144 The \f(CW\*(C`coderef\*(C'\fR argument determines the type of function that will be
1145 called. If it is \f(CWSvROK()\fR it is assumed to be a reference to a CV and
1146 will arrange for the coderef to be called. If it is not \fBSvROK()\fR then it
1147 is assumed to be a \f(CWSvIV()\fR which is \f(CWSvIOK()\fR whose value is a pointer
1148 to a C function of type \f(CW\*(C`DESTRUCTORFUNC_t\*(C'\fR created using \f(CWPTR2INT()\fR.
1149 Either way the \f(CW\*(C`args\*(C'\fR parameter will be provided to the callback as a
1150 parameter, although the rules for doing so differ between the Perl and
1151 C mode. Normally this function is only used directly for the Perl case
1152 and the wrapper \f(CWmortal_destructor_x()\fR is used for the C function case.
1153 .Sp
1154 When operating in Perl callback mode the \f(CW\*(C`args\*(C'\fR parameter may be NULL
1155 in which case the code reference is called with no arguments, otherwise
1156 if it is an AV (SvTYPE(args) == SVt_PVAV) then the contents of the AV
1157 will be used as the arguments to the code reference, and if it is any
1158 other type then the \f(CW\*(C`args\*(C'\fR SV will be provided as a single argument to
1159 the code reference.
1160 .Sp
1161 When operating in a C callback mode the \f(CW\*(C`args\*(C'\fR parameter will be passed
1162 directly to the C function as a \f(CW\*(C`void *\*(C'\fR pointer. No additional
1163 processing of the argument will be peformed, and it is the callers
1164 responsibility to free the \f(CW\*(C`args\*(C'\fR parameter if necessary.
1165 .Sp
1166 Be aware that there is a signficant difference in timing between the
1167 \&\fIend of the current statement\fR and the \fIend of the current pseudo
1168 block\fR. If you are looking for a mechanism to trigger a function at the
1169 end of the \fBcurrent pseudo block\fR you should look at
1170 "\f(CW\*(C`SAVEDESTRUCTOR_X\*(C'\fR" in perlapi instead of this function.
1171 .RS 4
1172 .Sp
1173 .Vb 1
1174 \& void mortal_destructor_sv(SV *coderef, SV *args)
1175 .Ve
1176 .RE
1177 .RS 4
1178 .RE
1179 .ie n .IP """MORTALSVFUNC_X""" 4
1180 .el .IP \f(CWMORTALSVFUNC_X\fR 4
1181 .IX Item "MORTALSVFUNC_X"
1182 Described in perlguts.
1183 .RS 4
1184 .Sp
1185 .Vb 1
1186 \& MORTALSVFUNC_X(SVFUNC_t f, SV *sv)
1187 .Ve
1188 .RE
1189 .RS 4
1190 .RE
1191 .ie n .IP """PL_errgv""" 4
1192 .el .IP \f(CWPL_errgv\fR 4
1193 .IX Item "PL_errgv"
1194 Described in perlcall.
1195 .ie n .IP """save_aelem""" 4
1196 .el .IP \f(CWsave_aelem\fR 4
1197 .IX Item "save_aelem"
1198 .PD 0
1199 .ie n .IP """save_aelem_flags""" 4
1200 .el .IP \f(CWsave_aelem_flags\fR 4
1201 .IX Xref "save_aelem save_aelem_flags"
1202 .IX Item "save_aelem_flags"
1203 .PD
1204 These each arrange for the value of the array element \f(CW\*(C`av[idx]\*(C'\fR to be restored
1205 at the end of the enclosing \fIpseudo-block\fR.
1206 .Sp
1207 In \f(CW\*(C`save_aelem\*(C'\fR, the SV at C**sptr> will be replaced by a new \f(CW\*(C`undef\*(C'\fR
1208 scalar. That scalar will inherit any magic from the original \f(CW**sptr\fR,
1209 and any 'set' magic will be processed.
1210 .Sp
1211 In \f(CW\*(C`save_aelem_flags\*(C'\fR, \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR being set in \f(CW\*(C`flags\*(C'\fR causes
1212 the function to forgo all that: the scalar at \f(CW**sptr\fR is untouched.
1213 If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a
1214 new \f(CW\*(C`undef\*(C'\fR scalar. That scalar will inherit any magic from the original
1215 \&\f(CW**sptr\fR. Any 'set' magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR
1216 is set in in \f(CW\*(C`flags\*(C'\fR.
1217 .RS 4
1218 .Sp
1219 .Vb 3
1220 \& void save_aelem (AV *av, SSize_t idx, SV **sptr)
1221 \& void save_aelem_flags(AV *av, SSize_t idx, SV **sptr,
1222 \& const U32 flags)
1223 .Ve
1224 .RE
1225 .RS 4
1226 .RE
1227 .ie n .IP """save_aptr""" 4
1228 .el .IP \f(CWsave_aptr\fR 4
1229 .IX Item "save_aptr"
1230 Described in perlguts.
1231 .RS 4
1232 .Sp
1233 .Vb 1
1234 \& void save_aptr(AV **aptr)
1235 .Ve
1236 .RE
1237 .RS 4
1238 .RE
1239 .ie n .IP """save_ary""" 4
1240 .el .IP \f(CWsave_ary\fR 4
1241 .IX Item "save_ary"
1242 Described in perlguts.
1243 .RS 4
1244 .Sp
1245 .Vb 1
1246 \& AV * save_ary(GV *gv)
1247 .Ve
1248 .RE
1249 .RS 4
1250 .RE
1251 .ie n .IP """SAVEBOOL""" 4
1252 .el .IP \f(CWSAVEBOOL\fR 4
1253 .IX Item "SAVEBOOL"
1254 Described in perlguts.
1255 .RS 4
1256 .Sp
1257 .Vb 1
1258 \& SAVEBOOL(bool i)
1259 .Ve
1260 .RE
1261 .RS 4
1262 .RE
1263 .ie n .IP """SAVEDELETE""" 4
1264 .el .IP \f(CWSAVEDELETE\fR 4
1265 .IX Item "SAVEDELETE"
1266 Described in perlguts.
1267 .RS 4
1268 .Sp
1269 .Vb 1
1270 \& SAVEDELETE(HV * hv, char * key, I32 length)
1271 .Ve
1272 .RE
1273 .RS 4
1274 .RE
1275 .ie n .IP """SAVEDESTRUCTOR""" 4
1276 .el .IP \f(CWSAVEDESTRUCTOR\fR 4
1277 .IX Item "SAVEDESTRUCTOR"
1278 Described in perlguts.
1279 .RS 4
1280 .Sp
1281 .Vb 1
1282 \& SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)
1283 .Ve
1284 .RE
1285 .RS 4
1286 .RE
1287 .ie n .IP """SAVEDESTRUCTOR_X""" 4
1288 .el .IP \f(CWSAVEDESTRUCTOR_X\fR 4
1289 .IX Item "SAVEDESTRUCTOR_X"
1290 Described in perlguts.
1291 .RS 4
1292 .Sp
1293 .Vb 1
1294 \& SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)
1295 .Ve
1296 .RE
1297 .RS 4
1298 .RE
1299 .ie n .IP """SAVEFREEOP""" 4
1300 .el .IP \f(CWSAVEFREEOP\fR 4
1301 .IX Item "SAVEFREEOP"
1302 Described in perlguts.
1303 .RS 4
1304 .Sp
1305 .Vb 1
1306 \& SAVEFREEOP(OP *op)
1307 .Ve
1308 .RE
1309 .RS 4
1310 .RE
1311 .ie n .IP """SAVEFREEPV""" 4
1312 .el .IP \f(CWSAVEFREEPV\fR 4
1313 .IX Item "SAVEFREEPV"
1314 Described in perlguts.
1315 .RS 4
1316 .Sp
1317 .Vb 1
1318 \& SAVEFREEPV(char *pv)
1319 .Ve
1320 .RE
1321 .RS 4
1322 .RE
1323 .ie n .IP """SAVEFREERCPV""" 4
1324 .el .IP \f(CWSAVEFREERCPV\fR 4
1325 .IX Item "SAVEFREERCPV"
1326 Described in perlguts.
1327 .RS 4
1328 .Sp
1329 .Vb 1
1330 \& SAVEFREERCPV(char *pv)
1331 .Ve
1332 .RE
1333 .RS 4
1334 .RE
1335 .ie n .IP """SAVEFREESV""" 4
1336 .el .IP \f(CWSAVEFREESV\fR 4
1337 .IX Item "SAVEFREESV"
1338 Described in perlguts.
1339 .RS 4
1340 .Sp
1341 .Vb 1
1342 \& SAVEFREESV(SV* sv)
1343 .Ve
1344 .RE
1345 .RS 4
1346 .RE
1347 .ie n .IP """SAVEGENERICSV""" 4
1348 .el .IP \f(CWSAVEGENERICSV\fR 4
1349 .IX Item "SAVEGENERICSV"
1350 Described in perlguts.
1351 .RS 4
1352 .Sp
1353 .Vb 1
1354 \& SAVEGENERICSV(char **psv)
1355 .Ve
1356 .RE
1357 .RS 4
1358 .RE
1359 .ie n .IP """save_hash""" 4
1360 .el .IP \f(CWsave_hash\fR 4
1361 .IX Item "save_hash"
1362 Described in perlguts.
1363 .RS 4
1364 .Sp
1365 .Vb 1
1366 \& HV * save_hash(GV *gv)
1367 .Ve
1368 .RE
1369 .RS 4
1370 .RE
1371 .ie n .IP """save_helem""" 4
1372 .el .IP \f(CWsave_helem\fR 4
1373 .IX Item "save_helem"
1374 .PD 0
1375 .ie n .IP """save_helem_flags""" 4
1376 .el .IP \f(CWsave_helem_flags\fR 4
1377 .IX Xref "save_helem save_helem_flags"
1378 .IX Item "save_helem_flags"
1379 .PD
1380 These each arrange for the value of the hash element (in Perlish terms)
1381 \&\f(CW\*(C`$hv{key}]\*(C'\fR to be restored at the end of the enclosing \fIpseudo-block\fR.
1382 .Sp
1383 In \f(CW\*(C`save_helem\*(C'\fR, the SV at C**sptr> will be replaced by a new \f(CW\*(C`undef\*(C'\fR
1384 scalar. That scalar will inherit any magic from the original \f(CW**sptr\fR,
1385 and any 'set' magic will be processed.
1386 .Sp
1387 In \f(CW\*(C`save_helem_flags\*(C'\fR, \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR being set in \f(CW\*(C`flags\*(C'\fR causes
1388 the function to forgo all that: the scalar at \f(CW**sptr\fR is untouched.
1389 If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a
1390 new \f(CW\*(C`undef\*(C'\fR scalar. That scalar will inherit any magic from the original
1391 \&\f(CW**sptr\fR. Any 'set' magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR
1392 is set in in \f(CW\*(C`flags\*(C'\fR.
1393 .RS 4
1394 .Sp
1395 .Vb 3
1396 \& void save_helem (HV *hv, SV *key, SV **sptr)
1397 \& void save_helem_flags(HV *hv, SV *key, SV **sptr,
1398 \& const U32 flags)
1399 .Ve
1400 .RE
1401 .RS 4
1402 .RE
1403 .ie n .IP """save_hptr""" 4
1404 .el .IP \f(CWsave_hptr\fR 4
1405 .IX Item "save_hptr"
1406 Described in perlguts.
1407 .RS 4
1408 .Sp
1409 .Vb 1
1410 \& void save_hptr(HV **hptr)
1411 .Ve
1412 .RE
1413 .RS 4
1414 .RE
1415 .ie n .IP """SAVEINT""" 4
1416 .el .IP \f(CWSAVEINT\fR 4
1417 .IX Item "SAVEINT"
1418 Described in perlguts.
1419 .RS 4
1420 .Sp
1421 .Vb 1
1422 \& SAVEINT(int i)
1423 .Ve
1424 .RE
1425 .RS 4
1426 .RE
1427 .ie n .IP """save_item""" 4
1428 .el .IP \f(CWsave_item\fR 4
1429 .IX Item "save_item"
1430 Described in perlguts.
1431 .RS 4
1432 .Sp
1433 .Vb 1
1434 \& void save_item(SV *item)
1435 .Ve
1436 .RE
1437 .RS 4
1438 .RE
1439 .ie n .IP """SAVEIV""" 4
1440 .el .IP \f(CWSAVEIV\fR 4
1441 .IX Item "SAVEIV"
1442 Described in perlguts.
1443 .RS 4
1444 .Sp
1445 .Vb 1
1446 \& SAVEIV(IV i)
1447 .Ve
1448 .RE
1449 .RS 4
1450 .RE
1451 .ie n .IP """SAVEI8""" 4
1452 .el .IP \f(CWSAVEI8\fR 4
1453 .IX Item "SAVEI8"
1454 Described in perlguts.
1455 .RS 4
1456 .Sp
1457 .Vb 1
1458 \& SAVEI8(I8 i)
1459 .Ve
1460 .RE
1461 .RS 4
1462 .RE
1463 .ie n .IP """SAVEI16""" 4
1464 .el .IP \f(CWSAVEI16\fR 4
1465 .IX Item "SAVEI16"
1466 Described in perlguts.
1467 .RS 4
1468 .Sp
1469 .Vb 1
1470 \& SAVEI16(I16 i)
1471 .Ve
1472 .RE
1473 .RS 4
1474 .RE
1475 .ie n .IP """SAVEI32""" 4
1476 .el .IP \f(CWSAVEI32\fR 4
1477 .IX Item "SAVEI32"
1478 Described in perlguts.
1479 .RS 4
1480 .Sp
1481 .Vb 1
1482 \& SAVEI32(I32 i)
1483 .Ve
1484 .RE
1485 .RS 4
1486 .RE
1487 .ie n .IP """SAVELONG""" 4
1488 .el .IP \f(CWSAVELONG\fR 4
1489 .IX Item "SAVELONG"
1490 Described in perlguts.
1491 .RS 4
1492 .Sp
1493 .Vb 1
1494 \& SAVELONG(long i)
1495 .Ve
1496 .RE
1497 .RS 4
1498 .RE
1499 .ie n .IP """SAVEMORTALIZESV""" 4
1500 .el .IP \f(CWSAVEMORTALIZESV\fR 4
1501 .IX Item "SAVEMORTALIZESV"
1502 Described in perlguts.
1503 .RS 4
1504 .Sp
1505 .Vb 1
1506 \& SAVEMORTALIZESV(SV* sv)
1507 .Ve
1508 .RE
1509 .RS 4
1510 .RE
1511 .ie n .IP """SAVEPPTR""" 4
1512 .el .IP \f(CWSAVEPPTR\fR 4
1513 .IX Item "SAVEPPTR"
1514 Described in perlguts.
1515 .RS 4
1516 .Sp
1517 .Vb 1
1518 \& SAVEPPTR(char * p)
1519 .Ve
1520 .RE
1521 .RS 4
1522 .RE
1523 .ie n .IP """SAVERCPV""" 4
1524 .el .IP \f(CWSAVERCPV\fR 4
1525 .IX Item "SAVERCPV"
1526 Described in perlguts.
1527 .RS 4
1528 .Sp
1529 .Vb 1
1530 \& SAVERCPV(char *pv)
1531 .Ve
1532 .RE
1533 .RS 4
1534 .RE
1535 .ie n .IP """save_scalar""" 4
1536 .el .IP \f(CWsave_scalar\fR 4
1537 .IX Item "save_scalar"
1538 Described in perlguts.
1539 .RS 4
1540 .Sp
1541 .Vb 1
1542 \& SV * save_scalar(GV *gv)
1543 .Ve
1544 .RE
1545 .RS 4
1546 .RE
1547 .ie n .IP """SAVESPTR""" 4
1548 .el .IP \f(CWSAVESPTR\fR 4
1549 .IX Item "SAVESPTR"
1550 Described in perlguts.
1551 .RS 4
1552 .Sp
1553 .Vb 1
1554 \& SAVESPTR(SV * s)
1555 .Ve
1556 .RE
1557 .RS 4
1558 .RE
1559 .ie n .IP """SAVESTACK_POS""" 4
1560 .el .IP \f(CWSAVESTACK_POS\fR 4
1561 .IX Item "SAVESTACK_POS"
1562 Described in perlguts.
1563 .RS 4
1564 .Sp
1565 .Vb 1
1566 \& SAVESTACK_POS()
1567 .Ve
1568 .RE
1569 .RS 4
1570 .RE
1571 .ie n .IP """SAVESTRLEN""" 4
1572 .el .IP \f(CWSAVESTRLEN\fR 4
1573 .IX Item "SAVESTRLEN"
1574 Described in perlguts.
1575 .RS 4
1576 .Sp
1577 .Vb 1
1578 \& SAVESTRLEN(STRLEN i)
1579 .Ve
1580 .RE
1581 .RS 4
1582 .RE
1583 .ie n .IP """save_svref""" 4
1584 .el .IP \f(CWsave_svref\fR 4
1585 .IX Item "save_svref"
1586 Described in perlguts.
1587 .RS 4
1588 .Sp
1589 .Vb 1
1590 \& SV * save_svref(SV **sptr)
1591 .Ve
1592 .RE
1593 .RS 4
1594 .RE
1595 .ie n .IP """SAVETMPS""" 4
1596 .el .IP \f(CWSAVETMPS\fR 4
1597 .IX Xref "SAVETMPS"
1598 .IX Item "SAVETMPS"
1599 Opening bracket for temporaries on a callback. See \f(CW"FREETMPS"\fR and
1600 perlcall.
1601 .RS 4
1602 .Sp
1603 .Vb 1
1604 \& SAVETMPS;
1605 .Ve
1606 .RE
1607 .RS 4
1608 .RE
1609 .SH Casting
1610 .IX Header "Casting"
1611 .ie n .IP """Atof""" 4
1612 .el .IP \f(CWAtof\fR 4
1613 .IX Xref "Atof"
1614 .IX Item "Atof"
1615 This is a synonym for "\f(CW\*(C`my_atof\*(C'\fR".
1616 .RS 4
1617 .Sp
1618 .Vb 1
1619 \& NV Atof(NN const char * const s)
1620 .Ve
1621 .RE
1622 .RS 4
1623 .RE
1624 .ie n .IP """cBOOL""" 4
1625 .el .IP \f(CWcBOOL\fR 4
1626 .IX Xref "cBOOL"
1627 .IX Item "cBOOL"
1628 Cast-to-bool. When Perl was able to be compiled on pre\-C99 compilers, a
1629 \&\f(CW\*(C`(bool)\*(C'\fR cast didn't necessarily do the right thing, so this macro was
1630 created (and made somewhat complicated to work around bugs in old
1631 compilers). Now, many years later, and C99 is used, this is no longer
1632 required, but is kept for backwards compatibility.
1633 .RS 4
1634 .Sp
1635 .Vb 1
1636 \& bool cBOOL(bool expr)
1637 .Ve
1638 .RE
1639 .RS 4
1640 .RE
1641 .ie n .IP """INT2PTR""" 4
1642 .el .IP \f(CWINT2PTR\fR 4
1643 .IX Item "INT2PTR"
1644 Described in perlguts.
1645 .RS 4
1646 .Sp
1647 .Vb 1
1648 \& type INT2PTR(type, int value)
1649 .Ve
1650 .RE
1651 .RS 4
1652 .RE
1653 .ie n .IP """I_V""" 4
1654 .el .IP \f(CWI_V\fR 4
1655 .IX Xref "I_V"
1656 .IX Item "I_V"
1657 Cast an NV to IV while avoiding undefined C behavior
1658 .RS 4
1659 .Sp
1660 .Vb 1
1661 \& IV I_V(NV what)
1662 .Ve
1663 .RE
1664 .RS 4
1665 .RE
1666 .ie n .IP """I_32""" 4
1667 .el .IP \f(CWI_32\fR 4
1668 .IX Xref "I_32"
1669 .IX Item "I_32"
1670 Cast an NV to I32 while avoiding undefined C behavior
1671 .RS 4
1672 .Sp
1673 .Vb 1
1674 \& I32 I_32(NV what)
1675 .Ve
1676 .RE
1677 .RS 4
1678 .RE
1679 .ie n .IP """PTR2IV""" 4
1680 .el .IP \f(CWPTR2IV\fR 4
1681 .IX Item "PTR2IV"
1682 Described in perlguts.
1683 .RS 4
1684 .Sp
1685 .Vb 1
1686 \& IV PTR2IV(void * ptr)
1687 .Ve
1688 .RE
1689 .RS 4
1690 .RE
1691 .ie n .IP """PTR2nat""" 4
1692 .el .IP \f(CWPTR2nat\fR 4
1693 .IX Item "PTR2nat"
1694 Described in perlguts.
1695 .RS 4
1696 .Sp
1697 .Vb 1
1698 \& IV PTR2nat(void *)
1699 .Ve
1700 .RE
1701 .RS 4
1702 .RE
1703 .ie n .IP """PTR2NV""" 4
1704 .el .IP \f(CWPTR2NV\fR 4
1705 .IX Item "PTR2NV"
1706 Described in perlguts.
1707 .RS 4
1708 .Sp
1709 .Vb 1
1710 \& NV PTR2NV(void * ptr)
1711 .Ve
1712 .RE
1713 .RS 4
1714 .RE
1715 .ie n .IP """PTR2ul""" 4
1716 .el .IP \f(CWPTR2ul\fR 4
1717 .IX Item "PTR2ul"
1718 Described in perlguts.
1719 .RS 4
1720 .Sp
1721 .Vb 1
1722 \& unsigned long PTR2ul(void *)
1723 .Ve
1724 .RE
1725 .RS 4
1726 .RE
1727 .ie n .IP """PTR2UV""" 4
1728 .el .IP \f(CWPTR2UV\fR 4
1729 .IX Item "PTR2UV"
1730 Described in perlguts.
1731 .RS 4
1732 .Sp
1733 .Vb 1
1734 \& UV PTR2UV(void * ptr)
1735 .Ve
1736 .RE
1737 .RS 4
1738 .RE
1739 .ie n .IP """PTRV""" 4
1740 .el .IP \f(CWPTRV\fR 4
1741 .IX Item "PTRV"
1742 Described in perlguts.
1743 .ie n .IP """U_V""" 4
1744 .el .IP \f(CWU_V\fR 4
1745 .IX Xref "U_V"
1746 .IX Item "U_V"
1747 Cast an NV to UV while avoiding undefined C behavior
1748 .RS 4
1749 .Sp
1750 .Vb 1
1751 \& UV U_V(NV what)
1752 .Ve
1753 .RE
1754 .RS 4
1755 .RE
1756 .ie n .IP """U_32""" 4
1757 .el .IP \f(CWU_32\fR 4
1758 .IX Xref "U_32"
1759 .IX Item "U_32"
1760 Cast an NV to U32 while avoiding undefined C behavior
1761 .RS 4
1762 .Sp
1763 .Vb 1
1764 \& U32 U_32(NV what)
1765 .Ve
1766 .RE
1767 .RS 4
1768 .RE
1769 .SH "Character case changing"
1770 .IX Header "Character case changing"
1771 Perl uses "full" Unicode case mappings. This means that converting a single
1772 character to another case may result in a sequence of more than one character.
1773 For example, the uppercase of \f(CW\*(C`ß\*(C'\fR (LATIN SMALL LETTER SHARP S) is the two
1774 character sequence \f(CW\*(C`SS\*(C'\fR. This presents some complications The lowercase of
1775 all characters in the range 0..255 is a single character, and thus
1776 \&\f(CW"toLOWER_L1"\fR is furnished. But, \f(CW\*(C`toUPPER_L1\*(C'\fR can't exist, as it couldn't
1777 return a valid result for all legal inputs. Instead \f(CW"toUPPER_uvchr"\fR has
1778 an API that does allow every possible legal result to be returned.) Likewise
1779 no other function that is crippled by not being able to give the correct
1780 results for the full range of possible inputs has been implemented here.
1781 .ie n .IP """toFOLD""" 4
1782 .el .IP \f(CWtoFOLD\fR 4
1783 .IX Item "toFOLD"
1784 .PD 0
1785 .ie n .IP """toFOLD_A""" 4
1786 .el .IP \f(CWtoFOLD_A\fR 4
1787 .IX Item "toFOLD_A"
1788 .ie n .IP """toFOLD_utf8""" 4
1789 .el .IP \f(CWtoFOLD_utf8\fR 4
1790 .IX Item "toFOLD_utf8"
1791 .ie n .IP """toFOLD_utf8_safe""" 4
1792 .el .IP \f(CWtoFOLD_utf8_safe\fR 4
1793 .IX Item "toFOLD_utf8_safe"
1794 .ie n .IP """toFOLD_uvchr""" 4
1795 .el .IP \f(CWtoFOLD_uvchr\fR 4
1796 .IX Xref "toFOLD toFOLD_A toFOLD_utf8 toFOLD_utf8_safe toFOLD_uvchr"
1797 .IX Item "toFOLD_uvchr"
1798 .PD
1799 These all return the foldcase of a character. "foldcase" is an internal case
1800 for \f(CW\*(C`/i\*(C'\fR pattern matching. If the foldcase of character A and the foldcase of
1801 character B are the same, they match caselessly; otherwise they don't.
1802 .Sp
1803 The differences in the forms are what domain they operate on, and whether the
1804 input is specified as a code point (those forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a
1805 UTF\-8 string (the others). In the latter case, the code point to use is the
1806 first one in the buffer of UTF\-8 encoded code points, delineated by the
1807 arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
1808 .Sp
1809 \&\f(CW\*(C`toFOLD\*(C'\fR and \f(CW\*(C`toFOLD_A\*(C'\fR are synonyms of each other. They return the
1810 foldcase of any ASCII-range code point. In this range, the foldcase is
1811 identical to the lowercase. All other inputs are returned unchanged. Since
1812 these are macros, the input type may be any integral one, and the output will
1813 occupy the same number of bits as the input.
1814 .Sp
1815 There is no \f(CW\*(C`toFOLD_L1\*(C'\fR nor \f(CW\*(C`toFOLD_LATIN1\*(C'\fR as the foldcase of some code
1816 points in the 0..255 range is above that range or consists of multiple
1817 characters. Instead use \f(CW\*(C`toFOLD_uvchr\*(C'\fR.
1818 .Sp
1819 \&\f(CW\*(C`toFOLD_uvchr\*(C'\fR returns the foldcase of any Unicode code point. The return
1820 value is identical to that of \f(CW\*(C`toFOLD_A\*(C'\fR for input code points in the ASCII
1821 range. The foldcase of the vast majority of Unicode code points is the same
1822 as the code point itself. For these, and for code points above the legal
1823 Unicode maximum, this returns the input code point unchanged. It additionally
1824 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
1825 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
1826 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
1827 .Sp
1828 NOTE: the foldcase of a code point may be more than one code point. The
1829 return value of this function is only the first of these. The entire foldcase
1830 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
1831 point, you can do something like this:
1832 .Sp
1833 .Vb 3
1834 \& uc = toFOLD_uvchr(cp, s, &len);
1835 \& if (len > UTF8SKIP(s)) { is multiple code points }
1836 \& else { is a single code point }
1837 .Ve
1838 .Sp
1839 \&\f(CW\*(C`toFOLD_utf8\*(C'\fR and \f(CW\*(C`toFOLD_utf8_safe\*(C'\fR are synonyms of each other. The only
1840 difference between these and \f(CW\*(C`toFOLD_uvchr\*(C'\fR is that the source for these is
1841 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
1842 starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR
1843 buffer may certainly contain more than one code point; but only the first one
1844 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
1845 malformed in some way, the program may croak, or the function may return the
1846 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
1847 change in future releases.
1848 .RS 4
1849 .Sp
1850 .Vb 5
1851 \& UV toFOLD (UV cp)
1852 \& UV toFOLD_A (UV cp)
1853 \& UV toFOLD_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1854 \& UV toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1855 \& UV toFOLD_uvchr (UV cp, U8* s, STRLEN* lenp)
1856 .Ve
1857 .RE
1858 .RS 4
1859 .RE
1860 .ie n .IP """toLOWER""" 4
1861 .el .IP \f(CWtoLOWER\fR 4
1862 .IX Item "toLOWER"
1863 .PD 0
1864 .ie n .IP """toLOWER_A""" 4
1865 .el .IP \f(CWtoLOWER_A\fR 4
1866 .IX Item "toLOWER_A"
1867 .ie n .IP """toLOWER_LATIN1""" 4
1868 .el .IP \f(CWtoLOWER_LATIN1\fR 4
1869 .IX Item "toLOWER_LATIN1"
1870 .ie n .IP """toLOWER_LC""" 4
1871 .el .IP \f(CWtoLOWER_LC\fR 4
1872 .IX Item "toLOWER_LC"
1873 .ie n .IP """toLOWER_L1""" 4
1874 .el .IP \f(CWtoLOWER_L1\fR 4
1875 .IX Item "toLOWER_L1"
1876 .ie n .IP """toLOWER_utf8""" 4
1877 .el .IP \f(CWtoLOWER_utf8\fR 4
1878 .IX Item "toLOWER_utf8"
1879 .ie n .IP """toLOWER_utf8_safe""" 4
1880 .el .IP \f(CWtoLOWER_utf8_safe\fR 4
1881 .IX Item "toLOWER_utf8_safe"
1882 .ie n .IP """toLOWER_uvchr""" 4
1883 .el .IP \f(CWtoLOWER_uvchr\fR 4
1884 .IX Xref "toLOWER toLOWER_A toLOWER_LATIN1 toLOWER_LC toLOWER_L1 toLOWER_utf8 toLOWER_utf8_safe toLOWER_uvchr"
1885 .IX Item "toLOWER_uvchr"
1886 .PD
1887 These all return the lowercase of a character. The differences are what domain
1888 they operate on, and whether the input is specified as a code point (those
1889 forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter
1890 case, the code point to use is the first one in the buffer of UTF\-8 encoded
1891 code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
1892 .Sp
1893 \&\f(CW\*(C`toLOWER\*(C'\fR and \f(CW\*(C`toLOWER_A\*(C'\fR are synonyms of each other. They return the
1894 lowercase of any uppercase ASCII-range code point. All other inputs are
1895 returned unchanged. Since these are macros, the input type may be any integral
1896 one, and the output will occupy the same number of bits as the input.
1897 .Sp
1898 \&\f(CW\*(C`toLOWER_L1\*(C'\fR and \f(CW\*(C`toLOWER_LATIN1\*(C'\fR are synonyms of each other. They behave
1899 identically as \f(CW\*(C`toLOWER\*(C'\fR for ASCII-range input. But additionally will return
1900 the lowercase of any uppercase code point in the entire 0..255 range, assuming
1901 a Latin\-1 encoding (or the EBCDIC equivalent on such platforms).
1902 .Sp
1903 \&\f(CW\*(C`toLOWER_LC\*(C'\fR returns the lowercase of the input code point according to the
1904 rules of the current POSIX locale. Input code points outside the range 0..255
1905 are returned unchanged.
1906 .Sp
1907 \&\f(CW\*(C`toLOWER_uvchr\*(C'\fR returns the lowercase of any Unicode code point. The return
1908 value is identical to that of \f(CW\*(C`toLOWER_L1\*(C'\fR for input code points in the 0..255
1909 range. The lowercase of the vast majority of Unicode code points is the same
1910 as the code point itself. For these, and for code points above the legal
1911 Unicode maximum, this returns the input code point unchanged. It additionally
1912 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
1913 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
1914 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
1915 .Sp
1916 NOTE: the lowercase of a code point may be more than one code point. The
1917 return value of this function is only the first of these. The entire lowercase
1918 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
1919 point, you can do something like this:
1920 .Sp
1921 .Vb 3
1922 \& uc = toLOWER_uvchr(cp, s, &len);
1923 \& if (len > UTF8SKIP(s)) { is multiple code points }
1924 \& else { is a single code point }
1925 .Ve
1926 .Sp
1927 \&\f(CW\*(C`toLOWER_utf8\*(C'\fR and \f(CW\*(C`toLOWER_utf8_safe\*(C'\fR are synonyms of each other. The only
1928 difference between these and \f(CW\*(C`toLOWER_uvchr\*(C'\fR is that the source for these is
1929 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
1930 starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR
1931 buffer may certainly contain more than one code point; but only the first one
1932 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
1933 malformed in some way, the program may croak, or the function may return the
1934 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
1935 change in future releases.
1936 .RS 4
1937 .Sp
1938 .Vb 8
1939 \& UV toLOWER (UV cp)
1940 \& UV toLOWER_A (UV cp)
1941 \& UV toLOWER_LATIN1 (UV cp)
1942 \& UV toLOWER_LC (UV cp)
1943 \& UV toLOWER_L1 (UV cp)
1944 \& UV toLOWER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1945 \& UV toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1946 \& UV toLOWER_uvchr (UV cp, U8* s, STRLEN* lenp)
1947 .Ve
1948 .RE
1949 .RS 4
1950 .RE
1951 .ie n .IP """toTITLE""" 4
1952 .el .IP \f(CWtoTITLE\fR 4
1953 .IX Item "toTITLE"
1954 .PD 0
1955 .ie n .IP """toTITLE_A""" 4
1956 .el .IP \f(CWtoTITLE_A\fR 4
1957 .IX Item "toTITLE_A"
1958 .ie n .IP """toTITLE_utf8""" 4
1959 .el .IP \f(CWtoTITLE_utf8\fR 4
1960 .IX Item "toTITLE_utf8"
1961 .ie n .IP """toTITLE_utf8_safe""" 4
1962 .el .IP \f(CWtoTITLE_utf8_safe\fR 4
1963 .IX Item "toTITLE_utf8_safe"
1964 .ie n .IP """toTITLE_uvchr""" 4
1965 .el .IP \f(CWtoTITLE_uvchr\fR 4
1966 .IX Xref "toTITLE toTITLE_A toTITLE_utf8 toTITLE_utf8_safe toTITLE_uvchr"
1967 .IX Item "toTITLE_uvchr"
1968 .PD
1969 These all return the titlecase of a character. The differences are what domain
1970 they operate on, and whether the input is specified as a code point (those
1971 forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter
1972 case, the code point to use is the first one in the buffer of UTF\-8 encoded
1973 code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
1974 .Sp
1975 \&\f(CW\*(C`toTITLE\*(C'\fR and \f(CW\*(C`toTITLE_A\*(C'\fR are synonyms of each other. They return the
1976 titlecase of any lowercase ASCII-range code point. In this range, the
1977 titlecase is identical to the uppercase. All other inputs are returned
1978 unchanged. Since these are macros, the input type may be any integral one, and
1979 the output will occupy the same number of bits as the input.
1980 .Sp
1981 There is no \f(CW\*(C`toTITLE_L1\*(C'\fR nor \f(CW\*(C`toTITLE_LATIN1\*(C'\fR as the titlecase of some code
1982 points in the 0..255 range is above that range or consists of multiple
1983 characters. Instead use \f(CW\*(C`toTITLE_uvchr\*(C'\fR.
1984 .Sp
1985 \&\f(CW\*(C`toTITLE_uvchr\*(C'\fR returns the titlecase of any Unicode code point. The return
1986 value is identical to that of \f(CW\*(C`toTITLE_A\*(C'\fR for input code points in the ASCII
1987 range. The titlecase of the vast majority of Unicode code points is the same
1988 as the code point itself. For these, and for code points above the legal
1989 Unicode maximum, this returns the input code point unchanged. It additionally
1990 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
1991 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
1992 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
1993 .Sp
1994 NOTE: the titlecase of a code point may be more than one code point. The
1995 return value of this function is only the first of these. The entire titlecase
1996 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
1997 point, you can do something like this:
1998 .Sp
1999 .Vb 3
2000 \& uc = toTITLE_uvchr(cp, s, &len);
2001 \& if (len > UTF8SKIP(s)) { is multiple code points }
2002 \& else { is a single code point }
2003 .Ve
2004 .Sp
2005 \&\f(CW\*(C`toTITLE_utf8\*(C'\fR and \f(CW\*(C`toTITLE_utf8_safe\*(C'\fR are synonyms of each other. The only
2006 difference between these and \f(CW\*(C`toTITLE_uvchr\*(C'\fR is that the source for these is
2007 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
2008 starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR
2009 buffer may certainly contain more than one code point; but only the first one
2010 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
2011 malformed in some way, the program may croak, or the function may return the
2012 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
2013 change in future releases.
2014 .RS 4
2015 .Sp
2016 .Vb 5
2017 \& UV toTITLE (UV cp)
2018 \& UV toTITLE_A (UV cp)
2019 \& UV toTITLE_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
2020 \& UV toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
2021 \& UV toTITLE_uvchr (UV cp, U8* s, STRLEN* lenp)
2022 .Ve
2023 .RE
2024 .RS 4
2025 .RE
2026 .ie n .IP """toUPPER""" 4
2027 .el .IP \f(CWtoUPPER\fR 4
2028 .IX Item "toUPPER"
2029 .PD 0
2030 .ie n .IP """toUPPER_A""" 4
2031 .el .IP \f(CWtoUPPER_A\fR 4
2032 .IX Item "toUPPER_A"
2033 .ie n .IP """toUPPER_utf8""" 4
2034 .el .IP \f(CWtoUPPER_utf8\fR 4
2035 .IX Item "toUPPER_utf8"
2036 .ie n .IP """toUPPER_utf8_safe""" 4
2037 .el .IP \f(CWtoUPPER_utf8_safe\fR 4
2038 .IX Item "toUPPER_utf8_safe"
2039 .ie n .IP """toUPPER_uvchr""" 4
2040 .el .IP \f(CWtoUPPER_uvchr\fR 4
2041 .IX Xref "toUPPER toUPPER_A toUPPER_utf8 toUPPER_utf8_safe toUPPER_uvchr"
2042 .IX Item "toUPPER_uvchr"
2043 .PD
2044 These all return the uppercase of a character. The differences are what domain
2045 they operate on, and whether the input is specified as a code point (those
2046 forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter
2047 case, the code point to use is the first one in the buffer of UTF\-8 encoded
2048 code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
2049 .Sp
2050 \&\f(CW\*(C`toUPPER\*(C'\fR and \f(CW\*(C`toUPPER_A\*(C'\fR are synonyms of each other. They return the
2051 uppercase of any lowercase ASCII-range code point. All other inputs are
2052 returned unchanged. Since these are macros, the input type may be any integral
2053 one, and the output will occupy the same number of bits as the input.
2054 .Sp
2055 There is no \f(CW\*(C`toUPPER_L1\*(C'\fR nor \f(CW\*(C`toUPPER_LATIN1\*(C'\fR as the uppercase of some code
2056 points in the 0..255 range is above that range or consists of multiple
2057 characters. Instead use \f(CW\*(C`toUPPER_uvchr\*(C'\fR.
2058 .Sp
2059 \&\f(CW\*(C`toUPPER_uvchr\*(C'\fR returns the uppercase of any Unicode code point. The return
2060 value is identical to that of \f(CW\*(C`toUPPER_A\*(C'\fR for input code points in the ASCII
2061 range. The uppercase of the vast majority of Unicode code points is the same
2062 as the code point itself. For these, and for code points above the legal
2063 Unicode maximum, this returns the input code point unchanged. It additionally
2064 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
2065 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
2066 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
2067 .Sp
2068 NOTE: the uppercase of a code point may be more than one code point. The
2069 return value of this function is only the first of these. The entire uppercase
2070 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
2071 point, you can do something like this:
2072 .Sp
2073 .Vb 3
2074 \& uc = toUPPER_uvchr(cp, s, &len);
2075 \& if (len > UTF8SKIP(s)) { is multiple code points }
2076 \& else { is a single code point }
2077 .Ve
2078 .Sp
2079 \&\f(CW\*(C`toUPPER_utf8\*(C'\fR and \f(CW\*(C`toUPPER_utf8_safe\*(C'\fR are synonyms of each other. The only
2080 difference between these and \f(CW\*(C`toUPPER_uvchr\*(C'\fR is that the source for these is
2081 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
2082 starting at \f(CW\*(C`p\*(C'\fR, with \f(CW\*(C`e\*(C'\fR pointing to one byte beyond its end. The \f(CW\*(C`p\*(C'\fR
2083 buffer may certainly contain more than one code point; but only the first one
2084 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
2085 malformed in some way, the program may croak, or the function may return the
2086 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
2087 change in future releases.
2088 .RS 4
2089 .Sp
2090 .Vb 5
2091 \& UV toUPPER (UV cp)
2092 \& UV toUPPER_A (UV cp)
2093 \& UV toUPPER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
2094 \& UV toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
2095 \& UV toUPPER_uvchr (UV cp, U8* s, STRLEN* lenp)
2096 .Ve
2097 .RE
2098 .RS 4
2099 .RE
2100 .SH "Character classification"
2101 .IX Header "Character classification"
2102 This section is about functions (really macros) that classify characters
2103 into types, such as punctuation versus alphabetic, etc. Most of these are
2104 analogous to regular expression character classes. (See
2105 "POSIX Character Classes" in perlrecharclass.) There are several variants for
2106 each class. (Not all macros have all variants; each item below lists the
2107 ones valid for it.) None are affected by \f(CW\*(C`use bytes\*(C'\fR, and only the ones
2108 with \f(CW\*(C`LC\*(C'\fR in the name are affected by the current locale.
2109 .PP
2110 The base function, e.g., \f(CWisALPHA()\fR, takes any signed or unsigned value,
2111 treating it as a code point, and returns a boolean as to whether or not the
2112 character represented by it is (or on non-ASCII platforms, corresponds to) an
2113 ASCII character in the named class based on platform, Unicode, and Perl rules.
2114 If the input is a number that doesn't fit in an octet, FALSE is returned.
2115 .PP
2116 Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_A\*(C'\fR (e.g., \f(CWisALPHA_A()\fR) is identical to the base function
2117 with no suffix \f(CW"_A"\fR. This variant is used to emphasize by its name that
2118 only ASCII-range characters can return TRUE.
2119 .PP
2120 Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR imposes the Latin\-1 (or EBCDIC equivalent) character set
2121 onto the platform. That is, the code points that are ASCII are unaffected,
2122 since ASCII is a subset of Latin\-1. But the non-ASCII code points are treated
2123 as if they are Latin\-1 characters. For example, \f(CWisWORDCHAR_L1()\fR will return
2124 true when called with the code point 0xDF, which is a word character in both
2125 ASCII and EBCDIC (though it represents different characters in each).
2126 If the input is a number that doesn't fit in an octet, FALSE is returned.
2127 (Perl's documentation uses a colloquial definition of Latin\-1, to include all
2128 code points below 256.)
2129 .PP
2130 Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_uvchr\*(C'\fR is exactly like the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR variant, for
2131 inputs below 256, but if the code point is larger than 255, Unicode rules are
2132 used to determine if it is in the character class. For example,
2133 \&\f(CWisWORDCHAR_uvchr(0x100)\fR returns TRUE, since 0x100 is LATIN CAPITAL LETTER A
2134 WITH MACRON in Unicode, and is a word character.
2135 .PP
2136 Variants \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_utf8\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_utf8_safe\*(C'\fR are like \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_uvchr\*(C'\fR,
2137 but are used for UTF\-8 encoded strings. The two forms are different names for
2138 the same thing. Each call to one of these classifies the first character of
2139 the string starting at \f(CW\*(C`p\*(C'\fR. The second parameter, \f(CW\*(C`e\*(C'\fR, points to anywhere in
2140 the string beyond the first character, up to one byte past the end of the
2141 entire string. Although both variants are identical, the suffix \f(CW\*(C`_safe\*(C'\fR in
2142 one name emphasizes that it will not attempt to read beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR,
2143 provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this is asserted for in
2144 \&\f(CW\*(C`\-DDEBUGGING\*(C'\fR builds). If the UTF\-8 for the input character is malformed in
2145 some way, the program may croak, or the function may return FALSE, at the
2146 discretion of the implementation, and subject to change in future releases.
2147 .PP
2148 Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC\*(C'\fR is like the \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_A\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR variants,
2149 but the result is based on the current locale, which is what \f(CW\*(C`LC\*(C'\fR in the name
2150 stands for. If Perl can determine that the current locale is a UTF\-8 locale,
2151 it uses the published Unicode rules; otherwise, it uses the C library function
2152 that gives the named classification. For example, \f(CWisDIGIT_LC()\fR when not in
2153 a UTF\-8 locale returns the result of calling \f(CWisdigit()\fR. FALSE is always
2154 returned if the input won't fit into an octet. On some platforms where the C
2155 library function is known to be defective, Perl changes its result to follow
2156 the POSIX standard's rules.
2157 .PP
2158 Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_uvchr\*(C'\fR acts exactly like \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC\*(C'\fR for inputs less
2159 than 256, but for larger ones it returns the Unicode classification of the code
2160 point.
2161 .PP
2162 Variants \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_utf8\*(C'\fR and \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_utf8_safe\*(C'\fR are like
2163 \&\f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_LC_uvchr\*(C'\fR, but are used for UTF\-8 encoded strings. The two forms
2164 are different names for the same thing. Each call to one of these classifies
2165 the first character of the string starting at \f(CW\*(C`p\*(C'\fR. The second parameter,
2166 \&\f(CW\*(C`e\*(C'\fR, points to anywhere in the string beyond the first character, up to one
2167 byte past the end of the entire string. Although both variants are identical,
2168 the suffix \f(CW\*(C`_safe\*(C'\fR in one name emphasizes that it will not attempt to read
2169 beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR, provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this
2170 is asserted for in \f(CW\*(C`\-DDEBUGGING\*(C'\fR builds). If the UTF\-8 for the input
2171 character is malformed in some way, the program may croak, or the function may
2172 return FALSE, at the discretion of the implementation, and subject to change in
2173 future releases.
2174 .ie n .IP """isALNUM""" 4
2175 .el .IP \f(CWisALNUM\fR 4
2176 .IX Item "isALNUM"
2177 .PD 0
2178 .ie n .IP """isALNUM_A""" 4
2179 .el .IP \f(CWisALNUM_A\fR 4
2180 .IX Item "isALNUM_A"
2181 .ie n .IP """isALNUM_LC""" 4
2182 .el .IP \f(CWisALNUM_LC\fR 4
2183 .IX Item "isALNUM_LC"
2184 .ie n .IP """isALNUM_LC_uvchr""" 4
2185 .el .IP \f(CWisALNUM_LC_uvchr\fR 4
2186 .IX Xref "isALNUM isALNUM_A isALNUM_LC isALNUM_LC_uvchr"
2187 .IX Item "isALNUM_LC_uvchr"
2188 .PD
2189 These are each a synonym for their respectively named "\f(CW\*(C`isWORDCHAR\*(C'\fR"
2190 variant.
2191 .Sp
2192 They are provided for backward compatibility, even though a word character
2193 includes more than the standard C language meaning of alphanumeric.
2194 To get the C language definition, use the corresponding "\f(CW\*(C`isALPHANUMERIC\*(C'\fR"
2195 variant.
2196 .RS 4
2197 .Sp
2198 .Vb 1
2199 \& bool isALNUM(UV ch)
2200 .Ve
2201 .RE
2202 .RS 4
2203 .RE
2204 .ie n .IP """isALNUMC""" 4
2205 .el .IP \f(CWisALNUMC\fR 4
2206 .IX Item "isALNUMC"
2207 .PD 0
2208 .ie n .IP """isALNUMC_A""" 4
2209 .el .IP \f(CWisALNUMC_A\fR 4
2210 .IX Item "isALNUMC_A"
2211 .ie n .IP """isALNUMC_LC""" 4
2212 .el .IP \f(CWisALNUMC_LC\fR 4
2213 .IX Item "isALNUMC_LC"
2214 .ie n .IP """isALNUMC_LC_uvchr""" 4
2215 .el .IP \f(CWisALNUMC_LC_uvchr\fR 4
2216 .IX Item "isALNUMC_LC_uvchr"
2217 .ie n .IP """isALNUMC_L1""" 4
2218 .el .IP \f(CWisALNUMC_L1\fR 4
2219 .IX Xref "isALNUMC isALNUMC_A isALNUMC_LC isALNUMC_LC_uvchr isALNUMC_L1"
2220 .IX Item "isALNUMC_L1"
2221 .PD
2222 These are discouraged, backward compatibility macros for "\f(CW\*(C`isALPHANUMERIC\*(C'\fR".
2223 That is, each returns a boolean indicating whether the specified character is
2224 one of \f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR.
2225 .Sp
2226 The \f(CW\*(C`C\*(C'\fR suffix in the names was meant to indicate that they correspond to the
2227 C language \f(CWisalnum(3)\fR.
2228 .RS 4
2229 .Sp
2230 .Vb 1
2231 \& bool isALNUMC(UV ch)
2232 .Ve
2233 .RE
2234 .RS 4
2235 .RE
2236 .ie n .IP """isALPHA""" 4
2237 .el .IP \f(CWisALPHA\fR 4
2238 .IX Item "isALPHA"
2239 .PD 0
2240 .ie n .IP """isALPHA_A""" 4
2241 .el .IP \f(CWisALPHA_A\fR 4
2242 .IX Item "isALPHA_A"
2243 .ie n .IP """isALPHA_LC""" 4
2244 .el .IP \f(CWisALPHA_LC\fR 4
2245 .IX Item "isALPHA_LC"
2246 .ie n .IP """isALPHA_LC_utf8_safe""" 4
2247 .el .IP \f(CWisALPHA_LC_utf8_safe\fR 4
2248 .IX Item "isALPHA_LC_utf8_safe"
2249 .ie n .IP """isALPHA_LC_uvchr""" 4
2250 .el .IP \f(CWisALPHA_LC_uvchr\fR 4
2251 .IX Item "isALPHA_LC_uvchr"
2252 .ie n .IP """isALPHA_L1""" 4
2253 .el .IP \f(CWisALPHA_L1\fR 4
2254 .IX Item "isALPHA_L1"
2255 .ie n .IP """isALPHA_utf8""" 4
2256 .el .IP \f(CWisALPHA_utf8\fR 4
2257 .IX Item "isALPHA_utf8"
2258 .ie n .IP """isALPHA_utf8_safe""" 4
2259 .el .IP \f(CWisALPHA_utf8_safe\fR 4
2260 .IX Item "isALPHA_utf8_safe"
2261 .ie n .IP """isALPHA_uvchr""" 4
2262 .el .IP \f(CWisALPHA_uvchr\fR 4
2263 .IX Xref "isALPHA isALPHA_A isALPHA_LC isALPHA_LC_utf8_safe isALPHA_LC_uvchr isALPHA_L1 isALPHA_utf8 isALPHA_utf8_safe isALPHA_uvchr"
2264 .IX Item "isALPHA_uvchr"
2265 .PD
2266 Returns a boolean indicating whether the specified input is one of \f(CW\*(C`[A\-Za\-z]\*(C'\fR,
2267 analogous to \f(CW\*(C`m/[[:alpha:]]/\*(C'\fR.
2268 See the top of this section for an explanation of
2269 the variants.
2270 .RS 4
2271 .Sp
2272 .Vb 9
2273 \& bool isALPHA (UV ch)
2274 \& bool isALPHA_A (UV ch)
2275 \& bool isALPHA_LC (UV ch)
2276 \& bool isALPHA_LC_utf8_safe(U8 * s, U8 *end)
2277 \& bool isALPHA_LC_uvchr (UV ch)
2278 \& bool isALPHA_L1 (UV ch)
2279 \& bool isALPHA_utf8 (U8 * s, U8 * end)
2280 \& bool isALPHA_utf8_safe (U8 * s, U8 * end)
2281 \& bool isALPHA_uvchr (UV ch)
2282 .Ve
2283 .RE
2284 .RS 4
2285 .RE
2286 .ie n .IP """isALPHANUMERIC""" 4
2287 .el .IP \f(CWisALPHANUMERIC\fR 4
2288 .IX Item "isALPHANUMERIC"
2289 .PD 0
2290 .ie n .IP """isALPHANUMERIC_A""" 4
2291 .el .IP \f(CWisALPHANUMERIC_A\fR 4
2292 .IX Item "isALPHANUMERIC_A"
2293 .ie n .IP """isALPHANUMERIC_LC""" 4
2294 .el .IP \f(CWisALPHANUMERIC_LC\fR 4
2295 .IX Item "isALPHANUMERIC_LC"
2296 .ie n .IP """isALPHANUMERIC_LC_utf8_safe""" 4
2297 .el .IP \f(CWisALPHANUMERIC_LC_utf8_safe\fR 4
2298 .IX Item "isALPHANUMERIC_LC_utf8_safe"
2299 .ie n .IP """isALPHANUMERIC_LC_uvchr""" 4
2300 .el .IP \f(CWisALPHANUMERIC_LC_uvchr\fR 4
2301 .IX Item "isALPHANUMERIC_LC_uvchr"
2302 .ie n .IP """isALPHANUMERIC_L1""" 4
2303 .el .IP \f(CWisALPHANUMERIC_L1\fR 4
2304 .IX Item "isALPHANUMERIC_L1"
2305 .ie n .IP """isALPHANUMERIC_utf8""" 4
2306 .el .IP \f(CWisALPHANUMERIC_utf8\fR 4
2307 .IX Item "isALPHANUMERIC_utf8"
2308 .ie n .IP """isALPHANUMERIC_utf8_safe""" 4
2309 .el .IP \f(CWisALPHANUMERIC_utf8_safe\fR 4
2310 .IX Item "isALPHANUMERIC_utf8_safe"
2311 .ie n .IP """isALPHANUMERIC_uvchr""" 4
2312 .el .IP \f(CWisALPHANUMERIC_uvchr\fR 4
2313 .IX Xref "isALPHANUMERIC isALPHANUMERIC_A isALPHANUMERIC_LC isALPHANUMERIC_LC_utf8_safe isALPHANUMERIC_LC_uvchr isALPHANUMERIC_L1 isALPHANUMERIC_utf8 isALPHANUMERIC_utf8_safe isALPHANUMERIC_uvchr"
2314 .IX Item "isALPHANUMERIC_uvchr"
2315 .PD
2316 Returns a boolean indicating whether the specified character is one of
2317 \&\f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR.
2318 See the top of this section for an explanation of
2319 the variants.
2320 .RS 4
2321 .Sp
2322 .Vb 9
2323 \& bool isALPHANUMERIC (UV ch)
2324 \& bool isALPHANUMERIC_A (UV ch)
2325 \& bool isALPHANUMERIC_LC (UV ch)
2326 \& bool isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
2327 \& bool isALPHANUMERIC_LC_uvchr (UV ch)
2328 \& bool isALPHANUMERIC_L1 (UV ch)
2329 \& bool isALPHANUMERIC_utf8 (U8 * s, U8 * end)
2330 \& bool isALPHANUMERIC_utf8_safe (U8 * s, U8 * end)
2331 \& bool isALPHANUMERIC_uvchr (UV ch)
2332 .Ve
2333 .RE
2334 .RS 4
2335 .RE
2336 .ie n .IP """isASCII""" 4
2337 .el .IP \f(CWisASCII\fR 4
2338 .IX Item "isASCII"
2339 .PD 0
2340 .ie n .IP """isASCII_A""" 4
2341 .el .IP \f(CWisASCII_A\fR 4
2342 .IX Item "isASCII_A"
2343 .ie n .IP """isASCII_LC""" 4
2344 .el .IP \f(CWisASCII_LC\fR 4
2345 .IX Item "isASCII_LC"
2346 .ie n .IP """isASCII_LC_utf8_safe""" 4
2347 .el .IP \f(CWisASCII_LC_utf8_safe\fR 4
2348 .IX Item "isASCII_LC_utf8_safe"
2349 .ie n .IP """isASCII_LC_uvchr""" 4
2350 .el .IP \f(CWisASCII_LC_uvchr\fR 4
2351 .IX Item "isASCII_LC_uvchr"
2352 .ie n .IP """isASCII_L1""" 4
2353 .el .IP \f(CWisASCII_L1\fR 4
2354 .IX Item "isASCII_L1"
2355 .ie n .IP """isASCII_utf8""" 4
2356 .el .IP \f(CWisASCII_utf8\fR 4
2357 .IX Item "isASCII_utf8"
2358 .ie n .IP """isASCII_utf8_safe""" 4
2359 .el .IP \f(CWisASCII_utf8_safe\fR 4
2360 .IX Item "isASCII_utf8_safe"
2361 .ie n .IP """isASCII_uvchr""" 4
2362 .el .IP \f(CWisASCII_uvchr\fR 4
2363 .IX Xref "isASCII isASCII_A isASCII_LC isASCII_LC_utf8_safe isASCII_LC_uvchr isASCII_L1 isASCII_utf8 isASCII_utf8_safe isASCII_uvchr"
2364 .IX Item "isASCII_uvchr"
2365 .PD
2366 Returns a boolean indicating whether the specified character is one of the 128
2367 characters in the ASCII character set, analogous to \f(CW\*(C`m/[[:ascii:]]/\*(C'\fR.
2368 On non-ASCII platforms, it returns TRUE iff this
2369 character corresponds to an ASCII character. Variants \f(CWisASCII_A()\fR and
2370 \&\f(CWisASCII_L1()\fR are identical to \f(CWisASCII()\fR.
2371 See the top of this section for an explanation of
2372 the variants.
2373 Note, however, that some platforms do not have the C library routine
2374 \&\f(CWisascii()\fR. In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are the
2375 same as the corresponding ones without.
2376 .Sp
2377 Also note, that because all ASCII characters are UTF\-8 invariant (meaning they
2378 have the exact same representation (always a single byte) whether encoded in
2379 UTF\-8 or not), \f(CW\*(C`isASCII\*(C'\fR will give the correct results when called with any
2380 byte in any string encoded or not in UTF\-8. And similarly \f(CW\*(C`isASCII_utf8\*(C'\fR and
2381 \&\f(CW\*(C`isASCII_utf8_safe\*(C'\fR will work properly on any string encoded or not in UTF\-8.
2382 .RS 4
2383 .Sp
2384 .Vb 9
2385 \& bool isASCII (UV ch)
2386 \& bool isASCII_A (UV ch)
2387 \& bool isASCII_LC (UV ch)
2388 \& bool isASCII_LC_utf8_safe(U8 * s, U8 *end)
2389 \& bool isASCII_LC_uvchr (UV ch)
2390 \& bool isASCII_L1 (UV ch)
2391 \& bool isASCII_utf8 (U8 * s, U8 * end)
2392 \& bool isASCII_utf8_safe (U8 * s, U8 * end)
2393 \& bool isASCII_uvchr (UV ch)
2394 .Ve
2395 .RE
2396 .RS 4
2397 .RE
2398 .ie n .IP """isBLANK""" 4
2399 .el .IP \f(CWisBLANK\fR 4
2400 .IX Item "isBLANK"
2401 .PD 0
2402 .ie n .IP """isBLANK_A""" 4
2403 .el .IP \f(CWisBLANK_A\fR 4
2404 .IX Item "isBLANK_A"
2405 .ie n .IP """isBLANK_LC""" 4
2406 .el .IP \f(CWisBLANK_LC\fR 4
2407 .IX Item "isBLANK_LC"
2408 .ie n .IP """isBLANK_LC_utf8_safe""" 4
2409 .el .IP \f(CWisBLANK_LC_utf8_safe\fR 4
2410 .IX Item "isBLANK_LC_utf8_safe"
2411 .ie n .IP """isBLANK_LC_uvchr""" 4
2412 .el .IP \f(CWisBLANK_LC_uvchr\fR 4
2413 .IX Item "isBLANK_LC_uvchr"
2414 .ie n .IP """isBLANK_L1""" 4
2415 .el .IP \f(CWisBLANK_L1\fR 4
2416 .IX Item "isBLANK_L1"
2417 .ie n .IP """isBLANK_utf8""" 4
2418 .el .IP \f(CWisBLANK_utf8\fR 4
2419 .IX Item "isBLANK_utf8"
2420 .ie n .IP """isBLANK_utf8_safe""" 4
2421 .el .IP \f(CWisBLANK_utf8_safe\fR 4
2422 .IX Item "isBLANK_utf8_safe"
2423 .ie n .IP """isBLANK_uvchr""" 4
2424 .el .IP \f(CWisBLANK_uvchr\fR 4
2425 .IX Xref "isBLANK isBLANK_A isBLANK_LC isBLANK_LC_utf8_safe isBLANK_LC_uvchr isBLANK_L1 isBLANK_utf8 isBLANK_utf8_safe isBLANK_uvchr"
2426 .IX Item "isBLANK_uvchr"
2427 .PD
2428 Returns a boolean indicating whether the specified character is a
2429 character considered to be a blank, analogous to \f(CW\*(C`m/[[:blank:]]/\*(C'\fR.
2430 See the top of this section for an explanation of
2431 the variants.
2432 Note,
2433 however, that some platforms do not have the C library routine
2434 \&\f(CWisblank()\fR. In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are
2435 the same as the corresponding ones without.
2436 .RS 4
2437 .Sp
2438 .Vb 9
2439 \& bool isBLANK (UV ch)
2440 \& bool isBLANK_A (UV ch)
2441 \& bool isBLANK_LC (UV ch)
2442 \& bool isBLANK_LC_utf8_safe(U8 * s, U8 *end)
2443 \& bool isBLANK_LC_uvchr (UV ch)
2444 \& bool isBLANK_L1 (UV ch)
2445 \& bool isBLANK_utf8 (U8 * s, U8 * end)
2446 \& bool isBLANK_utf8_safe (U8 * s, U8 * end)
2447 \& bool isBLANK_uvchr (UV ch)
2448 .Ve
2449 .RE
2450 .RS 4
2451 .RE
2452 .ie n .IP """isCNTRL""" 4
2453 .el .IP \f(CWisCNTRL\fR 4
2454 .IX Item "isCNTRL"
2455 .PD 0
2456 .ie n .IP """isCNTRL_A""" 4
2457 .el .IP \f(CWisCNTRL_A\fR 4
2458 .IX Item "isCNTRL_A"
2459 .ie n .IP """isCNTRL_LC""" 4
2460 .el .IP \f(CWisCNTRL_LC\fR 4
2461 .IX Item "isCNTRL_LC"
2462 .ie n .IP """isCNTRL_LC_utf8_safe""" 4
2463 .el .IP \f(CWisCNTRL_LC_utf8_safe\fR 4
2464 .IX Item "isCNTRL_LC_utf8_safe"
2465 .ie n .IP """isCNTRL_LC_uvchr""" 4
2466 .el .IP \f(CWisCNTRL_LC_uvchr\fR 4
2467 .IX Item "isCNTRL_LC_uvchr"
2468 .ie n .IP """isCNTRL_L1""" 4
2469 .el .IP \f(CWisCNTRL_L1\fR 4
2470 .IX Item "isCNTRL_L1"
2471 .ie n .IP """isCNTRL_utf8""" 4
2472 .el .IP \f(CWisCNTRL_utf8\fR 4
2473 .IX Item "isCNTRL_utf8"
2474 .ie n .IP """isCNTRL_utf8_safe""" 4
2475 .el .IP \f(CWisCNTRL_utf8_safe\fR 4
2476 .IX Item "isCNTRL_utf8_safe"
2477 .ie n .IP """isCNTRL_uvchr""" 4
2478 .el .IP \f(CWisCNTRL_uvchr\fR 4
2479 .IX Xref "isCNTRL isCNTRL_A isCNTRL_LC isCNTRL_LC_utf8_safe isCNTRL_LC_uvchr isCNTRL_L1 isCNTRL_utf8 isCNTRL_utf8_safe isCNTRL_uvchr"
2480 .IX Item "isCNTRL_uvchr"
2481 .PD
2482 Returns a boolean indicating whether the specified character is a
2483 control character, analogous to \f(CW\*(C`m/[[:cntrl:]]/\*(C'\fR.
2484 See the top of this section for an explanation of
2485 the variants.
2486 On EBCDIC platforms, you almost always want to use the \f(CW\*(C`isCNTRL_L1\*(C'\fR variant.
2487 .RS 4
2488 .Sp
2489 .Vb 9
2490 \& bool isCNTRL (UV ch)
2491 \& bool isCNTRL_A (UV ch)
2492 \& bool isCNTRL_LC (UV ch)
2493 \& bool isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
2494 \& bool isCNTRL_LC_uvchr (UV ch)
2495 \& bool isCNTRL_L1 (UV ch)
2496 \& bool isCNTRL_utf8 (U8 * s, U8 * end)
2497 \& bool isCNTRL_utf8_safe (U8 * s, U8 * end)
2498 \& bool isCNTRL_uvchr (UV ch)
2499 .Ve
2500 .RE
2501 .RS 4
2502 .RE
2503 .ie n .IP """isDIGIT""" 4
2504 .el .IP \f(CWisDIGIT\fR 4
2505 .IX Item "isDIGIT"
2506 .PD 0
2507 .ie n .IP """isDIGIT_A""" 4
2508 .el .IP \f(CWisDIGIT_A\fR 4
2509 .IX Item "isDIGIT_A"
2510 .ie n .IP """isDIGIT_LC""" 4
2511 .el .IP \f(CWisDIGIT_LC\fR 4
2512 .IX Item "isDIGIT_LC"
2513 .ie n .IP """isDIGIT_LC_utf8_safe""" 4
2514 .el .IP \f(CWisDIGIT_LC_utf8_safe\fR 4
2515 .IX Item "isDIGIT_LC_utf8_safe"
2516 .ie n .IP """isDIGIT_LC_uvchr""" 4
2517 .el .IP \f(CWisDIGIT_LC_uvchr\fR 4
2518 .IX Item "isDIGIT_LC_uvchr"
2519 .ie n .IP """isDIGIT_L1""" 4
2520 .el .IP \f(CWisDIGIT_L1\fR 4
2521 .IX Item "isDIGIT_L1"
2522 .ie n .IP """isDIGIT_utf8""" 4
2523 .el .IP \f(CWisDIGIT_utf8\fR 4
2524 .IX Item "isDIGIT_utf8"
2525 .ie n .IP """isDIGIT_utf8_safe""" 4
2526 .el .IP \f(CWisDIGIT_utf8_safe\fR 4
2527 .IX Item "isDIGIT_utf8_safe"
2528 .ie n .IP """isDIGIT_uvchr""" 4
2529 .el .IP \f(CWisDIGIT_uvchr\fR 4
2530 .IX Xref "isDIGIT isDIGIT_A isDIGIT_LC isDIGIT_LC_utf8_safe isDIGIT_LC_uvchr isDIGIT_L1 isDIGIT_utf8 isDIGIT_utf8_safe isDIGIT_uvchr"
2531 .IX Item "isDIGIT_uvchr"
2532 .PD
2533 Returns a boolean indicating whether the specified character is a
2534 digit, analogous to \f(CW\*(C`m/[[:digit:]]/\*(C'\fR.
2535 Variants \f(CW\*(C`isDIGIT_A\*(C'\fR and \f(CW\*(C`isDIGIT_L1\*(C'\fR are identical to \f(CW\*(C`isDIGIT\*(C'\fR.
2536 See the top of this section for an explanation of
2537 the variants.
2538 .RS 4
2539 .Sp
2540 .Vb 9
2541 \& bool isDIGIT (UV ch)
2542 \& bool isDIGIT_A (UV ch)
2543 \& bool isDIGIT_LC (UV ch)
2544 \& bool isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
2545 \& bool isDIGIT_LC_uvchr (UV ch)
2546 \& bool isDIGIT_L1 (UV ch)
2547 \& bool isDIGIT_utf8 (U8 * s, U8 * end)
2548 \& bool isDIGIT_utf8_safe (U8 * s, U8 * end)
2549 \& bool isDIGIT_uvchr (UV ch)
2550 .Ve
2551 .RE
2552 .RS 4
2553 .RE
2554 .ie n .IP """isGRAPH""" 4
2555 .el .IP \f(CWisGRAPH\fR 4
2556 .IX Item "isGRAPH"
2557 .PD 0
2558 .ie n .IP """isGRAPH_A""" 4
2559 .el .IP \f(CWisGRAPH_A\fR 4
2560 .IX Item "isGRAPH_A"
2561 .ie n .IP """isGRAPH_LC""" 4
2562 .el .IP \f(CWisGRAPH_LC\fR 4
2563 .IX Item "isGRAPH_LC"
2564 .ie n .IP """isGRAPH_LC_utf8_safe""" 4
2565 .el .IP \f(CWisGRAPH_LC_utf8_safe\fR 4
2566 .IX Item "isGRAPH_LC_utf8_safe"
2567 .ie n .IP """isGRAPH_LC_uvchr""" 4
2568 .el .IP \f(CWisGRAPH_LC_uvchr\fR 4
2569 .IX Item "isGRAPH_LC_uvchr"
2570 .ie n .IP """isGRAPH_L1""" 4
2571 .el .IP \f(CWisGRAPH_L1\fR 4
2572 .IX Item "isGRAPH_L1"
2573 .ie n .IP """isGRAPH_utf8""" 4
2574 .el .IP \f(CWisGRAPH_utf8\fR 4
2575 .IX Item "isGRAPH_utf8"
2576 .ie n .IP """isGRAPH_utf8_safe""" 4
2577 .el .IP \f(CWisGRAPH_utf8_safe\fR 4
2578 .IX Item "isGRAPH_utf8_safe"
2579 .ie n .IP """isGRAPH_uvchr""" 4
2580 .el .IP \f(CWisGRAPH_uvchr\fR 4
2581 .IX Xref "isGRAPH isGRAPH_A isGRAPH_LC isGRAPH_LC_utf8_safe isGRAPH_LC_uvchr isGRAPH_L1 isGRAPH_utf8 isGRAPH_utf8_safe isGRAPH_uvchr"
2582 .IX Item "isGRAPH_uvchr"
2583 .PD
2584 Returns a boolean indicating whether the specified character is a
2585 graphic character, analogous to \f(CW\*(C`m/[[:graph:]]/\*(C'\fR.
2586 See the top of this section for an explanation of
2587 the variants.
2588 .RS 4
2589 .Sp
2590 .Vb 9
2591 \& bool isGRAPH (UV ch)
2592 \& bool isGRAPH_A (UV ch)
2593 \& bool isGRAPH_LC (UV ch)
2594 \& bool isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
2595 \& bool isGRAPH_LC_uvchr (UV ch)
2596 \& bool isGRAPH_L1 (UV ch)
2597 \& bool isGRAPH_utf8 (U8 * s, U8 * end)
2598 \& bool isGRAPH_utf8_safe (U8 * s, U8 * end)
2599 \& bool isGRAPH_uvchr (UV ch)
2600 .Ve
2601 .RE
2602 .RS 4
2603 .RE
2604 .ie n .IP """isIDCONT""" 4
2605 .el .IP \f(CWisIDCONT\fR 4
2606 .IX Item "isIDCONT"
2607 .PD 0
2608 .ie n .IP """isIDCONT_A""" 4
2609 .el .IP \f(CWisIDCONT_A\fR 4
2610 .IX Item "isIDCONT_A"
2611 .ie n .IP """isIDCONT_LC""" 4
2612 .el .IP \f(CWisIDCONT_LC\fR 4
2613 .IX Item "isIDCONT_LC"
2614 .ie n .IP """isIDCONT_LC_utf8_safe""" 4
2615 .el .IP \f(CWisIDCONT_LC_utf8_safe\fR 4
2616 .IX Item "isIDCONT_LC_utf8_safe"
2617 .ie n .IP """isIDCONT_LC_uvchr""" 4
2618 .el .IP \f(CWisIDCONT_LC_uvchr\fR 4
2619 .IX Item "isIDCONT_LC_uvchr"
2620 .ie n .IP """isIDCONT_L1""" 4
2621 .el .IP \f(CWisIDCONT_L1\fR 4
2622 .IX Item "isIDCONT_L1"
2623 .ie n .IP """isIDCONT_utf8""" 4
2624 .el .IP \f(CWisIDCONT_utf8\fR 4
2625 .IX Item "isIDCONT_utf8"
2626 .ie n .IP """isIDCONT_utf8_safe""" 4
2627 .el .IP \f(CWisIDCONT_utf8_safe\fR 4
2628 .IX Item "isIDCONT_utf8_safe"
2629 .ie n .IP """isIDCONT_uvchr""" 4
2630 .el .IP \f(CWisIDCONT_uvchr\fR 4
2631 .IX Xref "isIDCONT isIDCONT_A isIDCONT_LC isIDCONT_LC_utf8_safe isIDCONT_LC_uvchr isIDCONT_L1 isIDCONT_utf8 isIDCONT_utf8_safe isIDCONT_uvchr"
2632 .IX Item "isIDCONT_uvchr"
2633 .PD
2634 Returns a boolean indicating whether the specified character can be the
2635 second or succeeding character of an identifier. This is very close to, but
2636 not quite the same as the official Unicode property \f(CW\*(C`XID_Continue\*(C'\fR. The
2637 difference is that this returns true only if the input character also matches
2638 "isWORDCHAR". See the top of this section for
2639 an explanation of the variants.
2640 .RS 4
2641 .Sp
2642 .Vb 9
2643 \& bool isIDCONT (UV ch)
2644 \& bool isIDCONT_A (UV ch)
2645 \& bool isIDCONT_LC (UV ch)
2646 \& bool isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
2647 \& bool isIDCONT_LC_uvchr (UV ch)
2648 \& bool isIDCONT_L1 (UV ch)
2649 \& bool isIDCONT_utf8 (U8 * s, U8 * end)
2650 \& bool isIDCONT_utf8_safe (U8 * s, U8 * end)
2651 \& bool isIDCONT_uvchr (UV ch)
2652 .Ve
2653 .RE
2654 .RS 4
2655 .RE
2656 .ie n .IP """isIDFIRST""" 4
2657 .el .IP \f(CWisIDFIRST\fR 4
2658 .IX Item "isIDFIRST"
2659 .PD 0
2660 .ie n .IP """isIDFIRST_A""" 4
2661 .el .IP \f(CWisIDFIRST_A\fR 4
2662 .IX Item "isIDFIRST_A"
2663 .ie n .IP """isIDFIRST_LC""" 4
2664 .el .IP \f(CWisIDFIRST_LC\fR 4
2665 .IX Item "isIDFIRST_LC"
2666 .ie n .IP """isIDFIRST_LC_utf8_safe""" 4
2667 .el .IP \f(CWisIDFIRST_LC_utf8_safe\fR 4
2668 .IX Item "isIDFIRST_LC_utf8_safe"
2669 .ie n .IP """isIDFIRST_LC_uvchr""" 4
2670 .el .IP \f(CWisIDFIRST_LC_uvchr\fR 4
2671 .IX Item "isIDFIRST_LC_uvchr"
2672 .ie n .IP """isIDFIRST_L1""" 4
2673 .el .IP \f(CWisIDFIRST_L1\fR 4
2674 .IX Item "isIDFIRST_L1"
2675 .ie n .IP """isIDFIRST_utf8""" 4
2676 .el .IP \f(CWisIDFIRST_utf8\fR 4
2677 .IX Item "isIDFIRST_utf8"
2678 .ie n .IP """isIDFIRST_utf8_safe""" 4
2679 .el .IP \f(CWisIDFIRST_utf8_safe\fR 4
2680 .IX Item "isIDFIRST_utf8_safe"
2681 .ie n .IP """isIDFIRST_uvchr""" 4
2682 .el .IP \f(CWisIDFIRST_uvchr\fR 4
2683 .IX Xref "isIDFIRST isIDFIRST_A isIDFIRST_LC isIDFIRST_LC_utf8_safe isIDFIRST_LC_uvchr isIDFIRST_L1 isIDFIRST_utf8 isIDFIRST_utf8_safe isIDFIRST_uvchr"
2684 .IX Item "isIDFIRST_uvchr"
2685 .PD
2686 Returns a boolean indicating whether the specified character can be the first
2687 character of an identifier. This is very close to, but not quite the same as
2688 the official Unicode property \f(CW\*(C`XID_Start\*(C'\fR. The difference is that this
2689 returns true only if the input character also matches "isWORDCHAR".
2690 See the top of this section for an explanation of
2691 the variants.
2692 .RS 4
2693 .Sp
2694 .Vb 9
2695 \& bool isIDFIRST (UV ch)
2696 \& bool isIDFIRST_A (UV ch)
2697 \& bool isIDFIRST_LC (UV ch)
2698 \& bool isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
2699 \& bool isIDFIRST_LC_uvchr (UV ch)
2700 \& bool isIDFIRST_L1 (UV ch)
2701 \& bool isIDFIRST_utf8 (U8 * s, U8 * end)
2702 \& bool isIDFIRST_utf8_safe (U8 * s, U8 * end)
2703 \& bool isIDFIRST_uvchr (UV ch)
2704 .Ve
2705 .RE
2706 .RS 4
2707 .RE
2708 .ie n .IP """isLOWER""" 4
2709 .el .IP \f(CWisLOWER\fR 4
2710 .IX Item "isLOWER"
2711 .PD 0
2712 .ie n .IP """isLOWER_A""" 4
2713 .el .IP \f(CWisLOWER_A\fR 4
2714 .IX Item "isLOWER_A"
2715 .ie n .IP """isLOWER_LC""" 4
2716 .el .IP \f(CWisLOWER_LC\fR 4
2717 .IX Item "isLOWER_LC"
2718 .ie n .IP """isLOWER_LC_utf8_safe""" 4
2719 .el .IP \f(CWisLOWER_LC_utf8_safe\fR 4
2720 .IX Item "isLOWER_LC_utf8_safe"
2721 .ie n .IP """isLOWER_LC_uvchr""" 4
2722 .el .IP \f(CWisLOWER_LC_uvchr\fR 4
2723 .IX Item "isLOWER_LC_uvchr"
2724 .ie n .IP """isLOWER_L1""" 4
2725 .el .IP \f(CWisLOWER_L1\fR 4
2726 .IX Item "isLOWER_L1"
2727 .ie n .IP """isLOWER_utf8""" 4
2728 .el .IP \f(CWisLOWER_utf8\fR 4
2729 .IX Item "isLOWER_utf8"
2730 .ie n .IP """isLOWER_utf8_safe""" 4
2731 .el .IP \f(CWisLOWER_utf8_safe\fR 4
2732 .IX Item "isLOWER_utf8_safe"
2733 .ie n .IP """isLOWER_uvchr""" 4
2734 .el .IP \f(CWisLOWER_uvchr\fR 4
2735 .IX Xref "isLOWER isLOWER_A isLOWER_LC isLOWER_LC_utf8_safe isLOWER_LC_uvchr isLOWER_L1 isLOWER_utf8 isLOWER_utf8_safe isLOWER_uvchr"
2736 .IX Item "isLOWER_uvchr"
2737 .PD
2738 Returns a boolean indicating whether the specified character is a
2739 lowercase character, analogous to \f(CW\*(C`m/[[:lower:]]/\*(C'\fR.
2740 See the top of this section for an explanation of
2741 the variants
2742 .RS 4
2743 .Sp
2744 .Vb 9
2745 \& bool isLOWER (UV ch)
2746 \& bool isLOWER_A (UV ch)
2747 \& bool isLOWER_LC (UV ch)
2748 \& bool isLOWER_LC_utf8_safe(U8 * s, U8 *end)
2749 \& bool isLOWER_LC_uvchr (UV ch)
2750 \& bool isLOWER_L1 (UV ch)
2751 \& bool isLOWER_utf8 (U8 * s, U8 * end)
2752 \& bool isLOWER_utf8_safe (U8 * s, U8 * end)
2753 \& bool isLOWER_uvchr (UV ch)
2754 .Ve
2755 .RE
2756 .RS 4
2757 .RE
2758 .ie n .IP """isOCTAL""" 4
2759 .el .IP \f(CWisOCTAL\fR 4
2760 .IX Item "isOCTAL"
2761 .PD 0
2762 .ie n .IP """isOCTAL_A""" 4
2763 .el .IP \f(CWisOCTAL_A\fR 4
2764 .IX Item "isOCTAL_A"
2765 .ie n .IP """isOCTAL_L1""" 4
2766 .el .IP \f(CWisOCTAL_L1\fR 4
2767 .IX Xref "isOCTAL isOCTAL_A isOCTAL_L1"
2768 .IX Item "isOCTAL_L1"
2769 .PD
2770 Returns a boolean indicating whether the specified character is an
2771 octal digit, [0\-7].
2772 The only two variants are \f(CW\*(C`isOCTAL_A\*(C'\fR and \f(CW\*(C`isOCTAL_L1\*(C'\fR; each is identical to
2773 \&\f(CW\*(C`isOCTAL\*(C'\fR.
2774 .RS 4
2775 .Sp
2776 .Vb 1
2777 \& bool isOCTAL(UV ch)
2778 .Ve
2779 .RE
2780 .RS 4
2781 .RE
2782 .ie n .IP """isPRINT""" 4
2783 .el .IP \f(CWisPRINT\fR 4
2784 .IX Item "isPRINT"
2785 .PD 0
2786 .ie n .IP """isPRINT_A""" 4
2787 .el .IP \f(CWisPRINT_A\fR 4
2788 .IX Item "isPRINT_A"
2789 .ie n .IP """isPRINT_LC""" 4
2790 .el .IP \f(CWisPRINT_LC\fR 4
2791 .IX Item "isPRINT_LC"
2792 .ie n .IP """isPRINT_LC_utf8_safe""" 4
2793 .el .IP \f(CWisPRINT_LC_utf8_safe\fR 4
2794 .IX Item "isPRINT_LC_utf8_safe"
2795 .ie n .IP """isPRINT_LC_uvchr""" 4
2796 .el .IP \f(CWisPRINT_LC_uvchr\fR 4
2797 .IX Item "isPRINT_LC_uvchr"
2798 .ie n .IP """isPRINT_L1""" 4
2799 .el .IP \f(CWisPRINT_L1\fR 4
2800 .IX Item "isPRINT_L1"
2801 .ie n .IP """isPRINT_utf8""" 4
2802 .el .IP \f(CWisPRINT_utf8\fR 4
2803 .IX Item "isPRINT_utf8"
2804 .ie n .IP """isPRINT_utf8_safe""" 4
2805 .el .IP \f(CWisPRINT_utf8_safe\fR 4
2806 .IX Item "isPRINT_utf8_safe"
2807 .ie n .IP """isPRINT_uvchr""" 4
2808 .el .IP \f(CWisPRINT_uvchr\fR 4
2809 .IX Xref "isPRINT isPRINT_A isPRINT_LC isPRINT_LC_utf8_safe isPRINT_LC_uvchr isPRINT_L1 isPRINT_utf8 isPRINT_utf8_safe isPRINT_uvchr"
2810 .IX Item "isPRINT_uvchr"
2811 .PD
2812 Returns a boolean indicating whether the specified character is a
2813 printable character, analogous to \f(CW\*(C`m/[[:print:]]/\*(C'\fR.
2814 See the top of this section for an explanation of
2815 the variants.
2816 .RS 4
2817 .Sp
2818 .Vb 9
2819 \& bool isPRINT (UV ch)
2820 \& bool isPRINT_A (UV ch)
2821 \& bool isPRINT_LC (UV ch)
2822 \& bool isPRINT_LC_utf8_safe(U8 * s, U8 *end)
2823 \& bool isPRINT_LC_uvchr (UV ch)
2824 \& bool isPRINT_L1 (UV ch)
2825 \& bool isPRINT_utf8 (U8 * s, U8 * end)
2826 \& bool isPRINT_utf8_safe (U8 * s, U8 * end)
2827 \& bool isPRINT_uvchr (UV ch)
2828 .Ve
2829 .RE
2830 .RS 4
2831 .RE
2832 .ie n .IP """isPSXSPC""" 4
2833 .el .IP \f(CWisPSXSPC\fR 4
2834 .IX Item "isPSXSPC"
2835 .PD 0
2836 .ie n .IP """isPSXSPC_A""" 4
2837 .el .IP \f(CWisPSXSPC_A\fR 4
2838 .IX Item "isPSXSPC_A"
2839 .ie n .IP """isPSXSPC_LC""" 4
2840 .el .IP \f(CWisPSXSPC_LC\fR 4
2841 .IX Item "isPSXSPC_LC"
2842 .ie n .IP """isPSXSPC_LC_utf8_safe""" 4
2843 .el .IP \f(CWisPSXSPC_LC_utf8_safe\fR 4
2844 .IX Item "isPSXSPC_LC_utf8_safe"
2845 .ie n .IP """isPSXSPC_LC_uvchr""" 4
2846 .el .IP \f(CWisPSXSPC_LC_uvchr\fR 4
2847 .IX Item "isPSXSPC_LC_uvchr"
2848 .ie n .IP """isPSXSPC_L1""" 4
2849 .el .IP \f(CWisPSXSPC_L1\fR 4
2850 .IX Item "isPSXSPC_L1"
2851 .ie n .IP """isPSXSPC_utf8""" 4
2852 .el .IP \f(CWisPSXSPC_utf8\fR 4
2853 .IX Item "isPSXSPC_utf8"
2854 .ie n .IP """isPSXSPC_utf8_safe""" 4
2855 .el .IP \f(CWisPSXSPC_utf8_safe\fR 4
2856 .IX Item "isPSXSPC_utf8_safe"
2857 .ie n .IP """isPSXSPC_uvchr""" 4
2858 .el .IP \f(CWisPSXSPC_uvchr\fR 4
2859 .IX Xref "isPSXSPC isPSXSPC_A isPSXSPC_LC isPSXSPC_LC_utf8_safe isPSXSPC_LC_uvchr isPSXSPC_L1 isPSXSPC_utf8 isPSXSPC_utf8_safe isPSXSPC_uvchr"
2860 .IX Item "isPSXSPC_uvchr"
2861 .PD
2862 (short for Posix Space)
2863 Starting in 5.18, this is identical in all its forms to the
2864 corresponding \f(CWisSPACE()\fR macros.
2865 The locale forms of this macro are identical to their corresponding
2866 \&\f(CWisSPACE()\fR forms in all Perl releases. In releases prior to 5.18, the
2867 non-locale forms differ from their \f(CWisSPACE()\fR forms only in that the
2868 \&\f(CWisSPACE()\fR forms don't match a Vertical Tab, and the \f(CWisPSXSPC()\fR forms do.
2869 Otherwise they are identical. Thus this macro is analogous to what
2870 \&\f(CW\*(C`m/[[:space:]]/\*(C'\fR matches in a regular expression.
2871 See the top of this section for an explanation of
2872 the variants.
2873 .RS 4
2874 .Sp
2875 .Vb 9
2876 \& bool isPSXSPC (UV ch)
2877 \& bool isPSXSPC_A (UV ch)
2878 \& bool isPSXSPC_LC (UV ch)
2879 \& bool isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
2880 \& bool isPSXSPC_LC_uvchr (UV ch)
2881 \& bool isPSXSPC_L1 (UV ch)
2882 \& bool isPSXSPC_utf8 (U8 * s, U8 * end)
2883 \& bool isPSXSPC_utf8_safe (U8 * s, U8 * end)
2884 \& bool isPSXSPC_uvchr (UV ch)
2885 .Ve
2886 .RE
2887 .RS 4
2888 .RE
2889 .ie n .IP """isPUNCT""" 4
2890 .el .IP \f(CWisPUNCT\fR 4
2891 .IX Item "isPUNCT"
2892 .PD 0
2893 .ie n .IP """isPUNCT_A""" 4
2894 .el .IP \f(CWisPUNCT_A\fR 4
2895 .IX Item "isPUNCT_A"
2896 .ie n .IP """isPUNCT_LC""" 4
2897 .el .IP \f(CWisPUNCT_LC\fR 4
2898 .IX Item "isPUNCT_LC"
2899 .ie n .IP """isPUNCT_LC_utf8_safe""" 4
2900 .el .IP \f(CWisPUNCT_LC_utf8_safe\fR 4
2901 .IX Item "isPUNCT_LC_utf8_safe"
2902 .ie n .IP """isPUNCT_LC_uvchr""" 4
2903 .el .IP \f(CWisPUNCT_LC_uvchr\fR 4
2904 .IX Item "isPUNCT_LC_uvchr"
2905 .ie n .IP """isPUNCT_L1""" 4
2906 .el .IP \f(CWisPUNCT_L1\fR 4
2907 .IX Item "isPUNCT_L1"
2908 .ie n .IP """isPUNCT_utf8""" 4
2909 .el .IP \f(CWisPUNCT_utf8\fR 4
2910 .IX Item "isPUNCT_utf8"
2911 .ie n .IP """isPUNCT_utf8_safe""" 4
2912 .el .IP \f(CWisPUNCT_utf8_safe\fR 4
2913 .IX Item "isPUNCT_utf8_safe"
2914 .ie n .IP """isPUNCT_uvchr""" 4
2915 .el .IP \f(CWisPUNCT_uvchr\fR 4
2916 .IX Xref "isPUNCT isPUNCT_A isPUNCT_LC isPUNCT_LC_utf8_safe isPUNCT_LC_uvchr isPUNCT_L1 isPUNCT_utf8 isPUNCT_utf8_safe isPUNCT_uvchr"
2917 .IX Item "isPUNCT_uvchr"
2918 .PD
2919 Returns a boolean indicating whether the specified character is a
2920 punctuation character, analogous to \f(CW\*(C`m/[[:punct:]]/\*(C'\fR.
2921 Note that the definition of what is punctuation isn't as
2922 straightforward as one might desire. See "POSIX Character
2923 Classes" in perlrecharclass for details.
2924 See the top of this section for an explanation of
2925 the variants.
2926 .RS 4
2927 .Sp
2928 .Vb 9
2929 \& bool isPUNCT (UV ch)
2930 \& bool isPUNCT_A (UV ch)
2931 \& bool isPUNCT_LC (UV ch)
2932 \& bool isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
2933 \& bool isPUNCT_LC_uvchr (UV ch)
2934 \& bool isPUNCT_L1 (UV ch)
2935 \& bool isPUNCT_utf8 (U8 * s, U8 * end)
2936 \& bool isPUNCT_utf8_safe (U8 * s, U8 * end)
2937 \& bool isPUNCT_uvchr (UV ch)
2938 .Ve
2939 .RE
2940 .RS 4
2941 .RE
2942 .ie n .IP """isSPACE""" 4
2943 .el .IP \f(CWisSPACE\fR 4
2944 .IX Item "isSPACE"
2945 .PD 0
2946 .ie n .IP """isSPACE_A""" 4
2947 .el .IP \f(CWisSPACE_A\fR 4
2948 .IX Item "isSPACE_A"
2949 .ie n .IP """isSPACE_LC""" 4
2950 .el .IP \f(CWisSPACE_LC\fR 4
2951 .IX Item "isSPACE_LC"
2952 .ie n .IP """isSPACE_LC_utf8_safe""" 4
2953 .el .IP \f(CWisSPACE_LC_utf8_safe\fR 4
2954 .IX Item "isSPACE_LC_utf8_safe"
2955 .ie n .IP """isSPACE_LC_uvchr""" 4
2956 .el .IP \f(CWisSPACE_LC_uvchr\fR 4
2957 .IX Item "isSPACE_LC_uvchr"
2958 .ie n .IP """isSPACE_L1""" 4
2959 .el .IP \f(CWisSPACE_L1\fR 4
2960 .IX Item "isSPACE_L1"
2961 .ie n .IP """isSPACE_utf8""" 4
2962 .el .IP \f(CWisSPACE_utf8\fR 4
2963 .IX Item "isSPACE_utf8"
2964 .ie n .IP """isSPACE_utf8_safe""" 4
2965 .el .IP \f(CWisSPACE_utf8_safe\fR 4
2966 .IX Item "isSPACE_utf8_safe"
2967 .ie n .IP """isSPACE_uvchr""" 4
2968 .el .IP \f(CWisSPACE_uvchr\fR 4
2969 .IX Xref "isSPACE isSPACE_A isSPACE_LC isSPACE_LC_utf8_safe isSPACE_LC_uvchr isSPACE_L1 isSPACE_utf8 isSPACE_utf8_safe isSPACE_uvchr"
2970 .IX Item "isSPACE_uvchr"
2971 .PD
2972 Returns a boolean indicating whether the specified character is a
2973 whitespace character. This is analogous
2974 to what \f(CW\*(C`m/\es/\*(C'\fR matches in a regular expression. Starting in Perl 5.18
2975 this also matches what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does. Prior to 5.18, only the
2976 locale forms of this macro (the ones with \f(CW\*(C`LC\*(C'\fR in their names) matched
2977 precisely what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does. In those releases, the only difference,
2978 in the non-locale variants, was that \f(CWisSPACE()\fR did not match a vertical tab.
2979 (See "isPSXSPC" for a macro that matches a vertical tab in all releases.)
2980 See the top of this section for an explanation of
2981 the variants.
2982 .RS 4
2983 .Sp
2984 .Vb 9
2985 \& bool isSPACE (UV ch)
2986 \& bool isSPACE_A (UV ch)
2987 \& bool isSPACE_LC (UV ch)
2988 \& bool isSPACE_LC_utf8_safe(U8 * s, U8 *end)
2989 \& bool isSPACE_LC_uvchr (UV ch)
2990 \& bool isSPACE_L1 (UV ch)
2991 \& bool isSPACE_utf8 (U8 * s, U8 * end)
2992 \& bool isSPACE_utf8_safe (U8 * s, U8 * end)
2993 \& bool isSPACE_uvchr (UV ch)
2994 .Ve
2995 .RE
2996 .RS 4
2997 .RE
2998 .ie n .IP """isUPPER""" 4
2999 .el .IP \f(CWisUPPER\fR 4
3000 .IX Item "isUPPER"
3001 .PD 0
3002 .ie n .IP """isUPPER_A""" 4
3003 .el .IP \f(CWisUPPER_A\fR 4
3004 .IX Item "isUPPER_A"
3005 .ie n .IP """isUPPER_LC""" 4
3006 .el .IP \f(CWisUPPER_LC\fR 4
3007 .IX Item "isUPPER_LC"
3008 .ie n .IP """isUPPER_LC_utf8_safe""" 4
3009 .el .IP \f(CWisUPPER_LC_utf8_safe\fR 4
3010 .IX Item "isUPPER_LC_utf8_safe"
3011 .ie n .IP """isUPPER_LC_uvchr""" 4
3012 .el .IP \f(CWisUPPER_LC_uvchr\fR 4
3013 .IX Item "isUPPER_LC_uvchr"
3014 .ie n .IP """isUPPER_L1""" 4
3015 .el .IP \f(CWisUPPER_L1\fR 4
3016 .IX Item "isUPPER_L1"
3017 .ie n .IP """isUPPER_utf8""" 4
3018 .el .IP \f(CWisUPPER_utf8\fR 4
3019 .IX Item "isUPPER_utf8"
3020 .ie n .IP """isUPPER_utf8_safe""" 4
3021 .el .IP \f(CWisUPPER_utf8_safe\fR 4
3022 .IX Item "isUPPER_utf8_safe"
3023 .ie n .IP """isUPPER_uvchr""" 4
3024 .el .IP \f(CWisUPPER_uvchr\fR 4
3025 .IX Xref "isUPPER isUPPER_A isUPPER_LC isUPPER_LC_utf8_safe isUPPER_LC_uvchr isUPPER_L1 isUPPER_utf8 isUPPER_utf8_safe isUPPER_uvchr"
3026 .IX Item "isUPPER_uvchr"
3027 .PD
3028 Returns a boolean indicating whether the specified character is an
3029 uppercase character, analogous to \f(CW\*(C`m/[[:upper:]]/\*(C'\fR.
3030 See the top of this section for an explanation of
3031 the variants.
3032 .RS 4
3033 .Sp
3034 .Vb 9
3035 \& bool isUPPER (UV ch)
3036 \& bool isUPPER_A (UV ch)
3037 \& bool isUPPER_LC (UV ch)
3038 \& bool isUPPER_LC_utf8_safe(U8 * s, U8 *end)
3039 \& bool isUPPER_LC_uvchr (UV ch)
3040 \& bool isUPPER_L1 (UV ch)
3041 \& bool isUPPER_utf8 (U8 * s, U8 * end)
3042 \& bool isUPPER_utf8_safe (U8 * s, U8 * end)
3043 \& bool isUPPER_uvchr (UV ch)
3044 .Ve
3045 .RE
3046 .RS 4
3047 .RE
3048 .ie n .IP """isWORDCHAR""" 4
3049 .el .IP \f(CWisWORDCHAR\fR 4
3050 .IX Item "isWORDCHAR"
3051 .PD 0
3052 .ie n .IP """isWORDCHAR_A""" 4
3053 .el .IP \f(CWisWORDCHAR_A\fR 4
3054 .IX Item "isWORDCHAR_A"
3055 .ie n .IP """isWORDCHAR_LC""" 4
3056 .el .IP \f(CWisWORDCHAR_LC\fR 4
3057 .IX Item "isWORDCHAR_LC"
3058 .ie n .IP """isWORDCHAR_LC_utf8_safe""" 4
3059 .el .IP \f(CWisWORDCHAR_LC_utf8_safe\fR 4
3060 .IX Item "isWORDCHAR_LC_utf8_safe"
3061 .ie n .IP """isWORDCHAR_LC_uvchr""" 4
3062 .el .IP \f(CWisWORDCHAR_LC_uvchr\fR 4
3063 .IX Item "isWORDCHAR_LC_uvchr"
3064 .ie n .IP """isWORDCHAR_L1""" 4
3065 .el .IP \f(CWisWORDCHAR_L1\fR 4
3066 .IX Item "isWORDCHAR_L1"
3067 .ie n .IP """isWORDCHAR_utf8""" 4
3068 .el .IP \f(CWisWORDCHAR_utf8\fR 4
3069 .IX Item "isWORDCHAR_utf8"
3070 .ie n .IP """isWORDCHAR_utf8_safe""" 4
3071 .el .IP \f(CWisWORDCHAR_utf8_safe\fR 4
3072 .IX Item "isWORDCHAR_utf8_safe"
3073 .ie n .IP """isWORDCHAR_uvchr""" 4
3074 .el .IP \f(CWisWORDCHAR_uvchr\fR 4
3075 .IX Xref "isWORDCHAR isWORDCHAR_A isWORDCHAR_LC isWORDCHAR_LC_utf8_safe isWORDCHAR_LC_uvchr isWORDCHAR_L1 isWORDCHAR_utf8 isWORDCHAR_utf8_safe isWORDCHAR_uvchr"
3076 .IX Item "isWORDCHAR_uvchr"
3077 .PD
3078 Returns a boolean indicating whether the specified character is a character
3079 that is a word character, analogous to what \f(CW\*(C`m/\ew/\*(C'\fR and \f(CW\*(C`m/[[:word:]]/\*(C'\fR match
3080 in a regular expression. A word character is an alphabetic character, a
3081 decimal digit, a connecting punctuation character (such as an underscore), or
3082 a "mark" character that attaches to one of those (like some sort of accent).
3083 .Sp
3084 See the top of this section for an explanation of
3085 the variants.
3086 .Sp
3087 \&\f(CW\*(C`isWORDCHAR_A\*(C'\fR, \f(CW\*(C`isWORDCHAR_L1\*(C'\fR, \f(CW\*(C`isWORDCHAR_uvchr\*(C'\fR,
3088 \&\f(CW\*(C`isWORDCHAR_LC\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_uvchr\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_utf8\*(C'\fR, and
3089 \&\f(CW\*(C`isWORDCHAR_LC_utf8_safe\*(C'\fR are also as described there, but additionally
3090 include the platform's native underscore.
3091 .RS 4
3092 .Sp
3093 .Vb 9
3094 \& bool isWORDCHAR (UV ch)
3095 \& bool isWORDCHAR_A (UV ch)
3096 \& bool isWORDCHAR_LC (UV ch)
3097 \& bool isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
3098 \& bool isWORDCHAR_LC_uvchr (UV ch)
3099 \& bool isWORDCHAR_L1 (UV ch)
3100 \& bool isWORDCHAR_utf8 (U8 * s, U8 * end)
3101 \& bool isWORDCHAR_utf8_safe (U8 * s, U8 * end)
3102 \& bool isWORDCHAR_uvchr (UV ch)
3103 .Ve
3104 .RE
3105 .RS 4
3106 .RE
3107 .ie n .IP """isXDIGIT""" 4
3108 .el .IP \f(CWisXDIGIT\fR 4
3109 .IX Item "isXDIGIT"
3110 .PD 0
3111 .ie n .IP """isXDIGIT_A""" 4
3112 .el .IP \f(CWisXDIGIT_A\fR 4
3113 .IX Item "isXDIGIT_A"
3114 .ie n .IP """isXDIGIT_LC""" 4
3115 .el .IP \f(CWisXDIGIT_LC\fR 4
3116 .IX Item "isXDIGIT_LC"
3117 .ie n .IP """isXDIGIT_LC_utf8_safe""" 4
3118 .el .IP \f(CWisXDIGIT_LC_utf8_safe\fR 4
3119 .IX Item "isXDIGIT_LC_utf8_safe"
3120 .ie n .IP """isXDIGIT_LC_uvchr""" 4
3121 .el .IP \f(CWisXDIGIT_LC_uvchr\fR 4
3122 .IX Item "isXDIGIT_LC_uvchr"
3123 .ie n .IP """isXDIGIT_L1""" 4
3124 .el .IP \f(CWisXDIGIT_L1\fR 4
3125 .IX Item "isXDIGIT_L1"
3126 .ie n .IP """isXDIGIT_utf8""" 4
3127 .el .IP \f(CWisXDIGIT_utf8\fR 4
3128 .IX Item "isXDIGIT_utf8"
3129 .ie n .IP """isXDIGIT_utf8_safe""" 4
3130 .el .IP \f(CWisXDIGIT_utf8_safe\fR 4
3131 .IX Item "isXDIGIT_utf8_safe"
3132 .ie n .IP """isXDIGIT_uvchr""" 4
3133 .el .IP \f(CWisXDIGIT_uvchr\fR 4
3134 .IX Xref "isXDIGIT isXDIGIT_A isXDIGIT_LC isXDIGIT_LC_utf8_safe isXDIGIT_LC_uvchr isXDIGIT_L1 isXDIGIT_utf8 isXDIGIT_utf8_safe isXDIGIT_uvchr"
3135 .IX Item "isXDIGIT_uvchr"
3136 .PD
3137 Returns a boolean indicating whether the specified character is a hexadecimal
3138 digit. In the ASCII range these are \f(CW\*(C`[0\-9A\-Fa\-f]\*(C'\fR. Variants \f(CWisXDIGIT_A()\fR
3139 and \f(CWisXDIGIT_L1()\fR are identical to \f(CWisXDIGIT()\fR.
3140 See the top of this section for an explanation of
3141 the variants.
3142 .RS 4
3143 .Sp
3144 .Vb 9
3145 \& bool isXDIGIT (UV ch)
3146 \& bool isXDIGIT_A (UV ch)
3147 \& bool isXDIGIT_LC (UV ch)
3148 \& bool isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
3149 \& bool isXDIGIT_LC_uvchr (UV ch)
3150 \& bool isXDIGIT_L1 (UV ch)
3151 \& bool isXDIGIT_utf8 (U8 * s, U8 * end)
3152 \& bool isXDIGIT_utf8_safe (U8 * s, U8 * end)
3153 \& bool isXDIGIT_uvchr (UV ch)
3154 .Ve
3155 .RE
3156 .RS 4
3157 .RE
3158 .SH "Compiler and Preprocessor information"
3159 .IX Header "Compiler and Preprocessor information"
3160 .ie n .IP """CPPLAST""" 4
3161 .el .IP \f(CWCPPLAST\fR 4
3162 .IX Xref "CPPLAST"
3163 .IX Item "CPPLAST"
3164 This symbol is intended to be used along with \f(CW\*(C`CPPRUN\*(C'\fR in the same manner
3165 symbol \f(CW\*(C`CPPMINUS\*(C'\fR is used with \f(CW\*(C`CPPSTDIN\*(C'\fR. It contains either "\-" or "".
3166 .ie n .IP """CPPMINUS""" 4
3167 .el .IP \f(CWCPPMINUS\fR 4
3168 .IX Xref "CPPMINUS"
3169 .IX Item "CPPMINUS"
3170 This symbol contains the second part of the string which will invoke
3171 the C preprocessor on the standard input and produce to standard
3172 output. This symbol will have the value "\-" if \f(CW\*(C`CPPSTDIN\*(C'\fR needs a minus
3173 to specify standard input, otherwise the value is "".
3174 .ie n .IP """CPPRUN""" 4
3175 .el .IP \f(CWCPPRUN\fR 4
3176 .IX Xref "CPPRUN"
3177 .IX Item "CPPRUN"
3178 This symbol contains the string which will invoke a C preprocessor on
3179 the standard input and produce to standard output. It needs to end
3180 with \f(CW\*(C`CPPLAST\*(C'\fR, after all other preprocessor flags have been specified.
3181 The main difference with \f(CW\*(C`CPPSTDIN\*(C'\fR is that this program will never be a
3182 pointer to a shell wrapper, i.e. it will be empty if no preprocessor is
3183 available directly to the user. Note that it may well be different from
3184 the preprocessor used to compile the C program.
3185 .ie n .IP """CPPSTDIN""" 4
3186 .el .IP \f(CWCPPSTDIN\fR 4
3187 .IX Xref "CPPSTDIN"
3188 .IX Item "CPPSTDIN"
3189 This symbol contains the first part of the string which will invoke
3190 the C preprocessor on the standard input and produce to standard
3191 output. Typical value of "cc \-E" or "\fI/lib/cpp\fR", but it can also
3192 call a wrapper. See \f(CW"CPPRUN"\fR.
3193 .ie n .IP """HASATTRIBUTE_ALWAYS_INLINE""" 4
3194 .el .IP \f(CWHASATTRIBUTE_ALWAYS_INLINE\fR 4
3195 .IX Xref "HASATTRIBUTE_ALWAYS_INLINE"
3196 .IX Item "HASATTRIBUTE_ALWAYS_INLINE"
3197 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should always be
3198 inlined.
3199 .ie n .IP """HASATTRIBUTE_DEPRECATED""" 4
3200 .el .IP \f(CWHASATTRIBUTE_DEPRECATED\fR 4
3201 .IX Xref "HASATTRIBUTE_DEPRECATED"
3202 .IX Item "HASATTRIBUTE_DEPRECATED"
3203 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for marking deprecated \f(CW\*(C`APIs\*(C'\fR
3204 .ie n .IP """HASATTRIBUTE_FORMAT""" 4
3205 .el .IP \f(CWHASATTRIBUTE_FORMAT\fR 4
3206 .IX Xref "HASATTRIBUTE_FORMAT"
3207 .IX Item "HASATTRIBUTE_FORMAT"
3208 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for checking printf-style formats
3209 .ie n .IP """HASATTRIBUTE_NONNULL""" 4
3210 .el .IP \f(CWHASATTRIBUTE_NONNULL\fR 4
3211 .IX Xref "HASATTRIBUTE_NONNULL"
3212 .IX Item "HASATTRIBUTE_NONNULL"
3213 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for nonnull function parms.
3214 .ie n .IP """HASATTRIBUTE_NORETURN""" 4
3215 .el .IP \f(CWHASATTRIBUTE_NORETURN\fR 4
3216 .IX Xref "HASATTRIBUTE_NORETURN"
3217 .IX Item "HASATTRIBUTE_NORETURN"
3218 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that do not return
3219 .ie n .IP """HASATTRIBUTE_PURE""" 4
3220 .el .IP \f(CWHASATTRIBUTE_PURE\fR 4
3221 .IX Xref "HASATTRIBUTE_PURE"
3222 .IX Item "HASATTRIBUTE_PURE"
3223 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for pure functions
3224 .ie n .IP """HASATTRIBUTE_UNUSED""" 4
3225 .el .IP \f(CWHASATTRIBUTE_UNUSED\fR 4
3226 .IX Xref "HASATTRIBUTE_UNUSED"
3227 .IX Item "HASATTRIBUTE_UNUSED"
3228 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for unused variables and arguments
3229 .ie n .IP """HASATTRIBUTE_VISIBILITY""" 4
3230 .el .IP \f(CWHASATTRIBUTE_VISIBILITY\fR 4
3231 .IX Xref "HASATTRIBUTE_VISIBILITY"
3232 .IX Item "HASATTRIBUTE_VISIBILITY"
3233 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should have a
3234 different visibility.
3235 .ie n .IP """HASATTRIBUTE_WARN_UNUSED_RESULT""" 4
3236 .el .IP \f(CWHASATTRIBUTE_WARN_UNUSED_RESULT\fR 4
3237 .IX Xref "HASATTRIBUTE_WARN_UNUSED_RESULT"
3238 .IX Item "HASATTRIBUTE_WARN_UNUSED_RESULT"
3239 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for warning on unused results
3240 .ie n .IP """HAS_BUILTIN_ADD_OVERFLOW""" 4
3241 .el .IP \f(CWHAS_BUILTIN_ADD_OVERFLOW\fR 4
3242 .IX Xref "HAS_BUILTIN_ADD_OVERFLOW"
3243 .IX Item "HAS_BUILTIN_ADD_OVERFLOW"
3244 This symbol, if defined, indicates that the compiler supports
3245 \&\f(CW\*(C`_\|_builtin_add_overflow\*(C'\fR for adding integers with overflow checks.
3246 .ie n .IP """HAS_BUILTIN_CHOOSE_EXPR""" 4
3247 .el .IP \f(CWHAS_BUILTIN_CHOOSE_EXPR\fR 4
3248 .IX Xref "HAS_BUILTIN_CHOOSE_EXPR"
3249 .IX Item "HAS_BUILTIN_CHOOSE_EXPR"
3250 Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for compile-time ternary-like expressions
3251 .ie n .IP """HAS_BUILTIN_EXPECT""" 4
3252 .el .IP \f(CWHAS_BUILTIN_EXPECT\fR 4
3253 .IX Xref "HAS_BUILTIN_EXPECT"
3254 .IX Item "HAS_BUILTIN_EXPECT"
3255 Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for telling that certain values are more
3256 likely
3257 .ie n .IP """HAS_BUILTIN_MUL_OVERFLOW""" 4
3258 .el .IP \f(CWHAS_BUILTIN_MUL_OVERFLOW\fR 4
3259 .IX Xref "HAS_BUILTIN_MUL_OVERFLOW"
3260 .IX Item "HAS_BUILTIN_MUL_OVERFLOW"
3261 This symbol, if defined, indicates that the compiler supports
3262 \&\f(CW\*(C`_\|_builtin_mul_overflow\*(C'\fR for multiplying integers with overflow checks.
3263 .ie n .IP """HAS_BUILTIN_SUB_OVERFLOW""" 4
3264 .el .IP \f(CWHAS_BUILTIN_SUB_OVERFLOW\fR 4
3265 .IX Xref "HAS_BUILTIN_SUB_OVERFLOW"
3266 .IX Item "HAS_BUILTIN_SUB_OVERFLOW"
3267 This symbol, if defined, indicates that the compiler supports
3268 \&\f(CW\*(C`_\|_builtin_sub_overflow\*(C'\fR for subtracting integers with overflow checks.
3269 .ie n .IP """HAS_C99_VARIADIC_MACROS""" 4
3270 .el .IP \f(CWHAS_C99_VARIADIC_MACROS\fR 4
3271 .IX Xref "HAS_C99_VARIADIC_MACROS"
3272 .IX Item "HAS_C99_VARIADIC_MACROS"
3273 If defined, the compiler supports C99 variadic macros.
3274 .ie n .IP """HAS_STATIC_INLINE""" 4
3275 .el .IP \f(CWHAS_STATIC_INLINE\fR 4
3276 .IX Xref "HAS_STATIC_INLINE"
3277 .IX Item "HAS_STATIC_INLINE"
3278 This symbol, if defined, indicates that the C compiler supports
3279 C99\-style static inline. That is, the function can't be called
3280 from another translation unit.
3281 .ie n .IP """MEM_ALIGNBYTES""" 4
3282 .el .IP \f(CWMEM_ALIGNBYTES\fR 4
3283 .IX Xref "MEM_ALIGNBYTES"
3284 .IX Item "MEM_ALIGNBYTES"
3285 This symbol contains the number of bytes required to align a
3286 double, or a long double when applicable. Usual values are 2,
3287 4 and 8. The default is eight, for safety. For cross-compiling
3288 or multiarch support, Configure will set a minimum of 8.
3289 .ie n .IP """PERL_STATIC_INLINE""" 4
3290 .el .IP \f(CWPERL_STATIC_INLINE\fR 4
3291 .IX Xref "PERL_STATIC_INLINE"
3292 .IX Item "PERL_STATIC_INLINE"
3293 This symbol gives the best-guess incantation to use for static
3294 inline functions. If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is defined, this will
3295 give C99\-style inline. If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is not defined,
3296 this will give a plain 'static'. It will always be defined
3297 to something that gives static linkage.
3298 Possibilities include
3299 .Sp
3300 .Vb 5
3301 \& static inline (c99)
3302 \& static _\|_inline_\|_ (gcc \-ansi)
3303 \& static _\|_inline (MSVC)
3304 \& static _inline (older MSVC)
3305 \& static (c89 compilers)
3306 .Ve
3307 .ie n .IP """PERL_THREAD_LOCAL""" 4
3308 .el .IP \f(CWPERL_THREAD_LOCAL\fR 4
3309 .IX Xref "PERL_THREAD_LOCAL"
3310 .IX Item "PERL_THREAD_LOCAL"
3311 This symbol, if defined, gives a linkage specification for thread-local
3312 storage. For example, for a C11 compiler this will be \f(CW\*(C`_Thread_local\*(C'\fR.
3313 Beware, some compilers are sensitive to the C language standard they are
3314 told to parse. For example, suncc defaults to C11, so our probe will
3315 report that \f(CW\*(C`_Thread_local\*(C'\fR can be used. However, if the \-std=c99 is later
3316 added to the compiler flags, then \f(CW\*(C`_Thread_local\*(C'\fR will become a syntax
3317 error. Hence it is important for these flags to be consistent between
3318 probing and use.
3319 .ie n .IP """U32_ALIGNMENT_REQUIRED""" 4
3320 .el .IP \f(CWU32_ALIGNMENT_REQUIRED\fR 4
3321 .IX Xref "U32_ALIGNMENT_REQUIRED"
3322 .IX Item "U32_ALIGNMENT_REQUIRED"
3323 This symbol, if defined, indicates that you must access
3324 character data through U32\-aligned pointers.
3325 .SH "Compiler directives"
3326 .IX Header "Compiler directives"
3327 .ie n .IP """_\|_ASSERT_""" 4
3328 .el .IP \f(CW_\|_ASSERT_\fR 4
3329 .IX Xref "__ASSERT_"
3330 .IX Item "__ASSERT_"
3331 This is a helper macro to avoid preprocessor issues, replaced by nothing
3332 unless under DEBUGGING, where it expands to an assert of its argument,
3333 followed by a comma (hence the comma operator). If we just used a straight
3334 \&\fBassert()\fR, we would get a comma with nothing before it when not DEBUGGING.
3335 .RS 4
3336 .Sp
3337 .Vb 1
3338 \& _\|_ASSERT_(bool expr)
3339 .Ve
3340 .RE
3341 .RS 4
3342 .RE
3343 .ie n .IP """ASSUME""" 4
3344 .el .IP \f(CWASSUME\fR 4
3345 .IX Xref "ASSUME"
3346 .IX Item "ASSUME"
3347 \&\f(CW\*(C`ASSUME\*(C'\fR is like \f(CWassert()\fR, but it has a benefit in a release build. It is a
3348 hint to a compiler about a statement of fact in a function call free
3349 expression, which allows the compiler to generate better machine code. In a
3350 debug build, \f(CWASSUME(x)\fR is a synonym for \f(CWassert(x)\fR. \f(CWASSUME(0)\fR means the
3351 control path is unreachable. In a for loop, \f(CW\*(C`ASSUME\*(C'\fR can be used to hint that
3352 a loop will run at least X times. \f(CW\*(C`ASSUME\*(C'\fR is based off MSVC's \f(CW\*(C`_\|_assume\*(C'\fR
3353 intrinsic function, see its documents for more details.
3354 .RS 4
3355 .Sp
3356 .Vb 1
3357 \& ASSUME(bool expr)
3358 .Ve
3359 .RE
3360 .RS 4
3361 .RE
3362 .ie n .IP """dNOOP""" 4
3363 .el .IP \f(CWdNOOP\fR 4
3364 .IX Xref "dNOOP"
3365 .IX Item "dNOOP"
3366 Declare nothing; typically used as a placeholder to replace something that used
3367 to declare something. Works on compilers that require declarations before any
3368 code.
3369 .RS 4
3370 .Sp
3371 .Vb 1
3372 \& dNOOP;
3373 .Ve
3374 .RE
3375 .RS 4
3376 .RE
3377 .ie n .IP """END_EXTERN_C""" 4
3378 .el .IP \f(CWEND_EXTERN_C\fR 4
3379 .IX Xref "END_EXTERN_C"
3380 .IX Item "END_EXTERN_C"
3381 When not compiling using C++, expands to nothing.
3382 Otherwise ends a section of code already begun by a \f(CW"START_EXTERN_C"\fR.
3383 .RS 4
3384 .Sp
3385 .Vb 1
3386 \& END_EXTERN_C
3387 .Ve
3388 .RE
3389 .RS 4
3390 .RE
3391 .ie n .IP """EXTERN_C""" 4
3392 .el .IP \f(CWEXTERN_C\fR 4
3393 .IX Xref "EXTERN_C"
3394 .IX Item "EXTERN_C"
3395 When not compiling using C++, expands to nothing.
3396 Otherwise is used in a declaration of a function to indicate the function
3397 should have external C linkage. This is required for things to work for just
3398 about all functions with external linkage compiled into perl.
3399 Often, you can use \f(CW"START_EXTERN_C"\fR ... \f(CW"END_EXTERN_C"\fR blocks
3400 surrounding all your code that you need to have this linkage.
3401 .Sp
3402 Example usage:
3403 .Sp
3404 .Vb 1
3405 \& EXTERN_C int flock(int fd, int op);
3406 .Ve
3407 .ie n .IP """LIKELY""" 4
3408 .el .IP \f(CWLIKELY\fR 4
3409 .IX Xref "LIKELY"
3410 .IX Item "LIKELY"
3411 Returns the input unchanged, but at the same time it gives a branch prediction
3412 hint to the compiler that this condition is likely to be true.
3413 .RS 4
3414 .Sp
3415 .Vb 1
3416 \& LIKELY(bool expr)
3417 .Ve
3418 .RE
3419 .RS 4
3420 .RE
3421 .ie n .IP """NOOP""" 4
3422 .el .IP \f(CWNOOP\fR 4
3423 .IX Xref "NOOP"
3424 .IX Item "NOOP"
3425 Do nothing; typically used as a placeholder to replace something that used to
3426 do something.
3427 .RS 4
3428 .Sp
3429 .Vb 1
3430 \& NOOP;
3431 .Ve
3432 .RE
3433 .RS 4
3434 .RE
3435 .ie n .IP """PERL_UNUSED_ARG""" 4
3436 .el .IP \f(CWPERL_UNUSED_ARG\fR 4
3437 .IX Xref "PERL_UNUSED_ARG"
3438 .IX Item "PERL_UNUSED_ARG"
3439 This is used to suppress compiler warnings that a parameter to a function is
3440 not used. This situation can arise, for example, when a parameter is needed
3441 under some configuration conditions, but not others, so that C preprocessor
3442 conditional compilation causes it be used just sometimes.
3443 .RS 4
3444 .Sp
3445 .Vb 1
3446 \& PERL_UNUSED_ARG(void x);
3447 .Ve
3448 .RE
3449 .RS 4
3450 .RE
3451 .ie n .IP """PERL_UNUSED_CONTEXT""" 4
3452 .el .IP \f(CWPERL_UNUSED_CONTEXT\fR 4
3453 .IX Xref "PERL_UNUSED_CONTEXT"
3454 .IX Item "PERL_UNUSED_CONTEXT"
3455 This is used to suppress compiler warnings that the thread context parameter to
3456 a function is not used. This situation can arise, for example, when a
3457 C preprocessor conditional compilation causes it be used just some times.
3458 .RS 4
3459 .Sp
3460 .Vb 1
3461 \& PERL_UNUSED_CONTEXT;
3462 .Ve
3463 .RE
3464 .RS 4
3465 .RE
3466 .ie n .IP """PERL_UNUSED_DECL""" 4
3467 .el .IP \f(CWPERL_UNUSED_DECL\fR 4
3468 .IX Xref "PERL_UNUSED_DECL"
3469 .IX Item "PERL_UNUSED_DECL"
3470 Tells the compiler that the parameter in the function prototype just before it
3471 is not necessarily expected to be used in the function. Not that many
3472 compilers understand this, so this should only be used in cases where
3473 \&\f(CW"PERL_UNUSED_ARG"\fR can't conveniently be used.
3474 .Sp
3475 Example usage:
3476 .RS 4
3477 .Sp
3478 .Vb 3
3479 \& Signal_t
3480 \& Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
3481 \& void *uap PERL_UNUSED_DECL, bool safe)
3482 .Ve
3483 .RE
3484 .RS 4
3485 .RE
3486 .ie n .IP """PERL_UNUSED_RESULT""" 4
3487 .el .IP \f(CWPERL_UNUSED_RESULT\fR 4
3488 .IX Xref "PERL_UNUSED_RESULT"
3489 .IX Item "PERL_UNUSED_RESULT"
3490 This macro indicates to discard the return value of the function call inside
3491 it, \fIe.g.\fR,
3492 .Sp
3493 .Vb 1
3494 \& PERL_UNUSED_RESULT(foo(a, b))
3495 .Ve
3496 .Sp
3497 The main reason for this is that the combination of \f(CW\*(C`gcc \-Wunused\-result\*(C'\fR
3498 (part of \f(CW\*(C`\-Wall\*(C'\fR) and the \f(CW\*(C`_\|_attribute_\|_((warn_unused_result))\*(C'\fR cannot
3499 be silenced with casting to \f(CW\*(C`void\*(C'\fR. This causes trouble when the system
3500 header files use the attribute.
3501 .Sp
3502 Use \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR sparingly, though, since usually the warning
3503 is there for a good reason: you might lose success/failure information,
3504 or leak resources, or changes in resources.
3505 .Sp
3506 But sometimes you just want to ignore the return value, \fIe.g.\fR, on
3507 codepaths soon ending up in abort, or in "best effort" attempts,
3508 or in situations where there is no good way to handle failures.
3509 .Sp
3510 Sometimes \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR might not be the most natural way:
3511 another possibility is that you can capture the return value
3512 and use \f(CW"PERL_UNUSED_VAR"\fR on that.
3513 .RS 4
3514 .Sp
3515 .Vb 1
3516 \& PERL_UNUSED_RESULT(void x)
3517 .Ve
3518 .RE
3519 .RS 4
3520 .RE
3521 .ie n .IP """PERL_UNUSED_VAR""" 4
3522 .el .IP \f(CWPERL_UNUSED_VAR\fR 4
3523 .IX Xref "PERL_UNUSED_VAR"
3524 .IX Item "PERL_UNUSED_VAR"
3525 This is used to suppress compiler warnings that the variable \fIx\fR is not used.
3526 This situation can arise, for example, when a C preprocessor conditional
3527 compilation causes it be used just some times.
3528 .RS 4
3529 .Sp
3530 .Vb 1
3531 \& PERL_UNUSED_VAR(void x);
3532 .Ve
3533 .RE
3534 .RS 4
3535 .RE
3536 .ie n .IP """START_EXTERN_C""" 4
3537 .el .IP \f(CWSTART_EXTERN_C\fR 4
3538 .IX Xref "START_EXTERN_C"
3539 .IX Item "START_EXTERN_C"
3540 When not compiling using C++, expands to nothing.
3541 Otherwise begins a section of code in which every function will effectively
3542 have \f(CW"EXTERN_C"\fR applied to it, that is to have external C linkage. The
3543 section is ended by a \f(CW"END_EXTERN_C"\fR.
3544 .RS 4
3545 .Sp
3546 .Vb 1
3547 \& START_EXTERN_C
3548 .Ve
3549 .RE
3550 .RS 4
3551 .RE
3552 .ie n .IP """STATIC""" 4
3553 .el .IP \f(CWSTATIC\fR 4
3554 .IX Item "STATIC"
3555 Described in perlguts.
3556 .ie n .IP """STMT_END""" 4
3557 .el .IP \f(CWSTMT_END\fR 4
3558 .IX Item "STMT_END"
3559 .PD 0
3560 .ie n .IP """STMT_START""" 4
3561 .el .IP \f(CWSTMT_START\fR 4
3562 .IX Xref "STMT_END STMT_START"
3563 .IX Item "STMT_START"
3564 .PD
3565 These allow a series of statements in a macro to be used as a single statement,
3566 as in
3567 .Sp
3568 .Vb 1
3569 \& if (x) STMT_START { ... } STMT_END else ...
3570 .Ve
3571 .Sp
3572 Note that you can't return a value out of this construct and cannot use it as
3573 an operand to the comma operator. These limit its utility.
3574 .Sp
3575 But, a value could be returned by constructing the API so that a pointer is
3576 passed and the macro dereferences this to set the return. If the value can be
3577 any of various types, depending on context, you can handle that situation in
3578 some situations by adding the type of the return as an extra accompanying
3579 parameter:
3580 .Sp
3581 .Vb 3
3582 \& #define foo(param, type) STMT_START {
3583 \& type * param; *param = do_calc; ...
3584 \& } STMT_END
3585 .Ve
3586 .Sp
3587 This could be awkward, so consider instead using a C language \f(CW\*(C`static inline\*(C'\fR
3588 function.
3589 .Sp
3590 If you do use this construct, it is easy to forget that it is a macro and not a
3591 function, and hence fall into traps that might not show up until someone
3592 someday writes code which contains names that clash with the ones you chose
3593 here, or calls it with a parameter which is an expression with side effects,
3594 the consequences of which you didn't think about. See "Writing
3595 safer macros" in perlhacktips for how to avoid these.
3596 .ie n .IP """UNLIKELY""" 4
3597 .el .IP \f(CWUNLIKELY\fR 4
3598 .IX Xref "UNLIKELY"
3599 .IX Item "UNLIKELY"
3600 Returns the input unchanged, but at the same time it gives a branch prediction
3601 hint to the compiler that this condition is likely to be false.
3602 .RS 4
3603 .Sp
3604 .Vb 1
3605 \& UNLIKELY(bool expr)
3606 .Ve
3607 .RE
3608 .RS 4
3609 .RE
3610 .SH "Compile-time scope hooks"
3611 .IX Header "Compile-time scope hooks"
3612 .ie n .IP """BhkDISABLE""" 4
3613 .el .IP \f(CWBhkDISABLE\fR 4
3614 .IX Xref "BhkDISABLE"
3615 .IX Item "BhkDISABLE"
3616 NOTE: \f(CW\*(C`BhkDISABLE\*(C'\fR is \fBexperimental\fR and may change or be
3617 removed without notice.
3618 .Sp
3619 Temporarily disable an entry in this BHK structure, by clearing the
3620 appropriate flag. \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which
3621 entry to disable.
3622 .RS 4
3623 .Sp
3624 .Vb 1
3625 \& void BhkDISABLE(BHK *hk, token which)
3626 .Ve
3627 .RE
3628 .RS 4
3629 .RE
3630 .ie n .IP """BhkENABLE""" 4
3631 .el .IP \f(CWBhkENABLE\fR 4
3632 .IX Xref "BhkENABLE"
3633 .IX Item "BhkENABLE"
3634 NOTE: \f(CW\*(C`BhkENABLE\*(C'\fR is \fBexperimental\fR and may change or be
3635 removed without notice.
3636 .Sp
3637 Re-enable an entry in this BHK structure, by setting the appropriate
3638 flag. \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which entry to enable.
3639 This will assert (under \-DDEBUGGING) if the entry doesn't contain a valid
3640 pointer.
3641 .RS 4
3642 .Sp
3643 .Vb 1
3644 \& void BhkENABLE(BHK *hk, token which)
3645 .Ve
3646 .RE
3647 .RS 4
3648 .RE
3649 .ie n .IP """BhkENTRY_set""" 4
3650 .el .IP \f(CWBhkENTRY_set\fR 4
3651 .IX Xref "BhkENTRY_set"
3652 .IX Item "BhkENTRY_set"
3653 NOTE: \f(CW\*(C`BhkENTRY_set\*(C'\fR is \fBexperimental\fR and may change or be
3654 removed without notice.
3655 .Sp
3656 Set an entry in the BHK structure, and set the flags to indicate it is
3657 valid. \f(CW\*(C`which\*(C'\fR is a preprocessing token indicating which entry to set.
3658 The type of \f(CW\*(C`ptr\*(C'\fR depends on the entry.
3659 .RS 4
3660 .Sp
3661 .Vb 1
3662 \& void BhkENTRY_set(BHK *hk, token which, void *ptr)
3663 .Ve
3664 .RE
3665 .RS 4
3666 .RE
3667 .ie n .IP """blockhook_register""" 4
3668 .el .IP \f(CWblockhook_register\fR 4
3669 .IX Xref "blockhook_register"
3670 .IX Item "blockhook_register"
3671 NOTE: \f(CW\*(C`blockhook_register\*(C'\fR is \fBexperimental\fR and may change or be
3672 removed without notice.
3673 .Sp
3674 Register a set of hooks to be called when the Perl lexical scope changes
3675 at compile time. See "Compile-time scope hooks" in perlguts.
3676 .Sp
3677 NOTE: \f(CW\*(C`blockhook_register\*(C'\fR must be explicitly called as
3678 \&\f(CW\*(C`Perl_blockhook_register\*(C'\fR
3679 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
3680 .RS 4
3681 .Sp
3682 .Vb 1
3683 \& void Perl_blockhook_register(pTHX_ BHK *hk)
3684 .Ve
3685 .RE
3686 .RS 4
3687 .RE
3688 .SH Concurrency
3689 .IX Header "Concurrency"
3690 .ie n .IP """aTHX""" 4
3691 .el .IP \f(CWaTHX\fR 4
3692 .IX Item "aTHX"
3693 Described in perlguts.
3694 .ie n .IP """aTHX_""" 4
3695 .el .IP \f(CWaTHX_\fR 4
3696 .IX Item "aTHX_"
3697 Described in perlguts.
3698 .ie n .IP """CPERLscope""" 4
3699 .el .IP \f(CWCPERLscope\fR 4
3700 .IX Xref "CPERLscope"
3701 .IX Item "CPERLscope"
3702 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`CPERLscope\*(C'\fR
3703 from a future release of Perl. Do not use it for
3704 new code; remove it from existing code.
3705 .Sp
3706 Now a no-op.
3707 .RS 4
3708 .Sp
3709 .Vb 1
3710 \& void CPERLscope(void x)
3711 .Ve
3712 .RE
3713 .RS 4
3714 .RE
3715 .ie n .IP """dTHR""" 4
3716 .el .IP \f(CWdTHR\fR 4
3717 .IX Item "dTHR"
3718 Described in perlguts.
3719 .ie n .IP """dTHX""" 4
3720 .el .IP \f(CWdTHX\fR 4
3721 .IX Item "dTHX"
3722 Described in perlguts.
3723 .ie n .IP """dTHXa""" 4
3724 .el .IP \f(CWdTHXa\fR 4
3725 .IX Xref "dTHXa"
3726 .IX Item "dTHXa"
3727 On threaded perls, set \f(CW\*(C`pTHX\*(C'\fR to \f(CW\*(C`a\*(C'\fR; on unthreaded perls, do nothing
3728 .ie n .IP """dTHXoa""" 4
3729 .el .IP \f(CWdTHXoa\fR 4
3730 .IX Xref "dTHXoa"
3731 .IX Item "dTHXoa"
3732 Now a synonym for \f(CW"dTHXa"\fR.
3733 .ie n .IP """dVAR""" 4
3734 .el .IP \f(CWdVAR\fR 4
3735 .IX Xref "dVAR"
3736 .IX Item "dVAR"
3737 This is now a synonym for dNOOP: declare nothing
3738 .ie n .IP """GETENV_PRESERVES_OTHER_THREAD""" 4
3739 .el .IP \f(CWGETENV_PRESERVES_OTHER_THREAD\fR 4
3740 .IX Xref "GETENV_PRESERVES_OTHER_THREAD"
3741 .IX Item "GETENV_PRESERVES_OTHER_THREAD"
3742 This symbol, if defined, indicates that the getenv system call doesn't
3743 zap the static buffer of \f(CWgetenv()\fR in a different thread.
3744 The typical \f(CWgetenv()\fR implementation will return a pointer to the proper
3745 position in **environ. But some may instead copy them to a static
3746 buffer in \f(CWgetenv()\fR. If there is a per-thread instance of that buffer,
3747 or the return points to **environ, then a many\-reader/1\-writer mutex
3748 will work; otherwise an exclusive locking mutex is required to prevent
3749 races.
3750 .ie n .IP """HAS_PTHREAD_ATFORK""" 4
3751 .el .IP \f(CWHAS_PTHREAD_ATFORK\fR 4
3752 .IX Xref "HAS_PTHREAD_ATFORK"
3753 .IX Item "HAS_PTHREAD_ATFORK"
3754 This symbol, if defined, indicates that the \f(CW\*(C`pthread_atfork\*(C'\fR routine
3755 is available to setup fork handlers.
3756 .ie n .IP """HAS_PTHREAD_ATTR_SETSCOPE""" 4
3757 .el .IP \f(CWHAS_PTHREAD_ATTR_SETSCOPE\fR 4
3758 .IX Xref "HAS_PTHREAD_ATTR_SETSCOPE"
3759 .IX Item "HAS_PTHREAD_ATTR_SETSCOPE"
3760 This symbol, if defined, indicates that the \f(CW\*(C`pthread_attr_setscope\*(C'\fR
3761 system call is available to set the contention scope attribute of
3762 a thread attribute object.
3763 .ie n .IP """HAS_PTHREAD_YIELD""" 4
3764 .el .IP \f(CWHAS_PTHREAD_YIELD\fR 4
3765 .IX Xref "HAS_PTHREAD_YIELD"
3766 .IX Item "HAS_PTHREAD_YIELD"
3767 This symbol, if defined, indicates that the \f(CW\*(C`pthread_yield\*(C'\fR
3768 routine is available to yield the execution of the current
3769 thread. \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR.
3770 .ie n .IP """HAS_SCHED_YIELD""" 4
3771 .el .IP \f(CWHAS_SCHED_YIELD\fR 4
3772 .IX Xref "HAS_SCHED_YIELD"
3773 .IX Item "HAS_SCHED_YIELD"
3774 This symbol, if defined, indicates that the \f(CW\*(C`sched_yield\*(C'\fR
3775 routine is available to yield the execution of the current
3776 thread. \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR.
3777 .ie n .IP """I_MACH_CTHREADS""" 4
3778 .el .IP \f(CWI_MACH_CTHREADS\fR 4
3779 .IX Xref "I_MACH_CTHREADS"
3780 .IX Item "I_MACH_CTHREADS"
3781 This symbol, if defined, indicates to the C program that it should
3782 include \fImach/cthreads.h\fR.
3783 .RS 4
3784 .Sp
3785 .Vb 3
3786 \& #ifdef I_MACH_CTHREADS
3787 \& #include <mach_cthreads.h>
3788 \& #endif
3789 .Ve
3790 .RE
3791 .RS 4
3792 .RE
3793 .ie n .IP """I_PTHREAD""" 4
3794 .el .IP \f(CWI_PTHREAD\fR 4
3795 .IX Xref "I_PTHREAD"
3796 .IX Item "I_PTHREAD"
3797 This symbol, if defined, indicates to the C program that it should
3798 include \fIpthread.h\fR.
3799 .RS 4
3800 .Sp
3801 .Vb 3
3802 \& #ifdef I_PTHREAD
3803 \& #include <pthread.h>
3804 \& #endif
3805 .Ve
3806 .RE
3807 .RS 4
3808 .RE
3809 .ie n .IP """MULTIPLICITY""" 4
3810 .el .IP \f(CWMULTIPLICITY\fR 4
3811 .IX Item "MULTIPLICITY"
3812 This symbol, if defined, indicates that Perl should
3813 be built to use multiplicity.
3814 .ie n .IP """OLD_PTHREAD_CREATE_JOINABLE""" 4
3815 .el .IP \f(CWOLD_PTHREAD_CREATE_JOINABLE\fR 4
3816 .IX Xref "OLD_PTHREAD_CREATE_JOINABLE"
3817 .IX Item "OLD_PTHREAD_CREATE_JOINABLE"
3818 This symbol, if defined, indicates how to create pthread
3819 in joinable (aka undetached) state. \f(CW\*(C`NOTE\*(C'\fR: not defined
3820 if \fIpthread.h\fR already has defined \f(CW\*(C`PTHREAD_CREATE_JOINABLE\*(C'\fR
3821 (the new version of the constant).
3822 If defined, known values are \f(CW\*(C`PTHREAD_CREATE_UNDETACHED\*(C'\fR
3823 and \f(CW\*(C`_\|_UNDETACHED\*(C'\fR.
3824 .ie n .IP """OLD_PTHREADS_API""" 4
3825 .el .IP \f(CWOLD_PTHREADS_API\fR 4
3826 .IX Xref "OLD_PTHREADS_API"
3827 .IX Item "OLD_PTHREADS_API"
3828 This symbol, if defined, indicates that Perl should
3829 be built to use the old draft \f(CW\*(C`POSIX\*(C'\fR threads \f(CW\*(C`API\*(C'\fR.
3830 .ie n .IP """PERL_IMPLICIT_CONTEXT""" 4
3831 .el .IP \f(CWPERL_IMPLICIT_CONTEXT\fR 4
3832 .IX Item "PERL_IMPLICIT_CONTEXT"
3833 Described in perlguts.
3834 .ie n .IP """PERL_NO_GET_CONTEXT""" 4
3835 .el .IP \f(CWPERL_NO_GET_CONTEXT\fR 4
3836 .IX Item "PERL_NO_GET_CONTEXT"
3837 Described in perlguts.
3838 .ie n .IP """pTHX""" 4
3839 .el .IP \f(CWpTHX\fR 4
3840 .IX Item "pTHX"
3841 Described in perlguts.
3842 .ie n .IP """pTHX_""" 4
3843 .el .IP \f(CWpTHX_\fR 4
3844 .IX Item "pTHX_"
3845 Described in perlguts.
3846 .ie n .IP """SCHED_YIELD""" 4
3847 .el .IP \f(CWSCHED_YIELD\fR 4
3848 .IX Xref "SCHED_YIELD"
3849 .IX Item "SCHED_YIELD"
3850 This symbol defines the way to yield the execution of
3851 the current thread. Known ways are \f(CW\*(C`sched_yield\*(C'\fR,
3852 \&\f(CW\*(C`pthread_yield\*(C'\fR, and \f(CW\*(C`pthread_yield\*(C'\fR with \f(CW\*(C`NULL\*(C'\fR.
3853 .SH "COPs and Hint Hashes"
3854 .IX Xref "COPHH_KEY_UTF8"
3855 .IX Header "COPs and Hint Hashes"
3856 .ie n .IP """cop_fetch_label""" 4
3857 .el .IP \f(CWcop_fetch_label\fR 4
3858 .IX Xref "cop_fetch_label"
3859 .IX Item "cop_fetch_label"
3860 NOTE: \f(CW\*(C`cop_fetch_label\*(C'\fR is \fBexperimental\fR and may change or be
3861 removed without notice.
3862 .Sp
3863 Returns the label attached to a cop, and stores its length in bytes into
3864 \&\f(CW*len\fR.
3865 Upon return, \f(CW*flags\fR will be set to either \f(CW\*(C`SVf_UTF8\*(C'\fR or 0.
3866 .Sp
3867 Alternatively, use the macro \f(CW"CopLABEL_len_flags"\fR;
3868 or if you don't need to know if the label is UTF\-8 or not, the macro
3869 \&\f(CW"CopLABEL_len"\fR;
3870 or if you additionally don't need to know the length, \f(CW"CopLABEL"\fR.
3871 .RS 4
3872 .Sp
3873 .Vb 2
3874 \& const char * cop_fetch_label(COP * const cop, STRLEN *len,
3875 \& U32 *flags)
3876 .Ve
3877 .RE
3878 .RS 4
3879 .RE
3880 .ie n .IP """CopFILE""" 4
3881 .el .IP \f(CWCopFILE\fR 4
3882 .IX Xref "CopFILE"
3883 .IX Item "CopFILE"
3884 Returns the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3885 .RS 4
3886 .Sp
3887 .Vb 1
3888 \& const char * CopFILE(const COP * c)
3889 .Ve
3890 .RE
3891 .RS 4
3892 .RE
3893 .ie n .IP """CopFILEAV""" 4
3894 .el .IP \f(CWCopFILEAV\fR 4
3895 .IX Xref "CopFILEAV"
3896 .IX Item "CopFILEAV"
3897 Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, creating it if necessary.
3898 .RS 4
3899 .Sp
3900 .Vb 1
3901 \& AV * CopFILEAV(const COP * c)
3902 .Ve
3903 .RE
3904 .RS 4
3905 .RE
3906 .ie n .IP """CopFILEAVn""" 4
3907 .el .IP \f(CWCopFILEAVn\fR 4
3908 .IX Xref "CopFILEAVn"
3909 .IX Item "CopFILEAVn"
3910 Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, returning NULL if it
3911 doesn't already exist.
3912 .RS 4
3913 .Sp
3914 .Vb 1
3915 \& AV * CopFILEAVn(const COP * c)
3916 .Ve
3917 .RE
3918 .RS 4
3919 .RE
3920 .ie n .IP """CopFILE_copy""" 4
3921 .el .IP \f(CWCopFILE_copy\fR 4
3922 .IX Xref "CopFILE_copy"
3923 .IX Item "CopFILE_copy"
3924 Efficiently copies the cop file name from one COP to another. Wraps
3925 the required logic to do a refcounted copy under threads or not.
3926 .RS 4
3927 .Sp
3928 .Vb 1
3929 \& void CopFILE_copy(COP * dst, COP * src)
3930 .Ve
3931 .RE
3932 .RS 4
3933 .RE
3934 .ie n .IP """CopFILE_free""" 4
3935 .el .IP \f(CWCopFILE_free\fR 4
3936 .IX Xref "CopFILE_free"
3937 .IX Item "CopFILE_free"
3938 Frees the file data in a cop. Under the hood this is a refcounting
3939 operation.
3940 .RS 4
3941 .Sp
3942 .Vb 1
3943 \& void CopFILE_free(COP * c)
3944 .Ve
3945 .RE
3946 .RS 4
3947 .RE
3948 .ie n .IP """CopFILEGV""" 4
3949 .el .IP \f(CWCopFILEGV\fR 4
3950 .IX Xref "CopFILEGV"
3951 .IX Item "CopFILEGV"
3952 Returns the GV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3953 .RS 4
3954 .Sp
3955 .Vb 1
3956 \& GV * CopFILEGV(const COP * c)
3957 .Ve
3958 .RE
3959 .RS 4
3960 .RE
3961 .ie n .IP """CopFILEGV_set""" 4
3962 .el .IP \f(CWCopFILEGV_set\fR 4
3963 .IX Xref "CopFILEGV_set"
3964 .IX Item "CopFILEGV_set"
3965 Available only on unthreaded perls. Makes \f(CW\*(C`pv\*(C'\fR the name of the file
3966 associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3967 .RS 4
3968 .Sp
3969 .Vb 1
3970 \& void CopFILEGV_set(COP *c, GV *gv)
3971 .Ve
3972 .RE
3973 .RS 4
3974 .RE
3975 .ie n .IP """CopFILE_LEN""" 4
3976 .el .IP \f(CWCopFILE_LEN\fR 4
3977 .IX Xref "CopFILE_LEN"
3978 .IX Item "CopFILE_LEN"
3979 Returns the length of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3980 .RS 4
3981 .Sp
3982 .Vb 1
3983 \& const char * CopFILE_LEN(const COP * c)
3984 .Ve
3985 .RE
3986 .RS 4
3987 .RE
3988 .ie n .IP """CopFILE_set""" 4
3989 .el .IP \f(CWCopFILE_set\fR 4
3990 .IX Xref "CopFILE_set"
3991 .IX Item "CopFILE_set"
3992 Makes \f(CW\*(C`pv\*(C'\fR the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3993 .RS 4
3994 .Sp
3995 .Vb 1
3996 \& void CopFILE_set(COP * c, const char * pv)
3997 .Ve
3998 .RE
3999 .RS 4
4000 .RE
4001 .ie n .IP """CopFILE_setn""" 4
4002 .el .IP \f(CWCopFILE_setn\fR 4
4003 .IX Xref "CopFILE_setn"
4004 .IX Item "CopFILE_setn"
4005 Makes \f(CW\*(C`pv\*(C'\fR the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
4006 .RS 4
4007 .Sp
4008 .Vb 1
4009 \& void CopFILE_setn(COP * c, const char * pv, STRLEN len)
4010 .Ve
4011 .RE
4012 .RS 4
4013 .RE
4014 .ie n .IP """CopFILESV""" 4
4015 .el .IP \f(CWCopFILESV\fR 4
4016 .IX Xref "CopFILESV"
4017 .IX Item "CopFILESV"
4018 Returns the SV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
4019 .RS 4
4020 .Sp
4021 .Vb 1
4022 \& SV * CopFILESV(const COP * c)
4023 .Ve
4024 .RE
4025 .RS 4
4026 .RE
4027 .ie n .IP """cophh_copy""" 4
4028 .el .IP \f(CWcophh_copy\fR 4
4029 .IX Xref "cophh_copy"
4030 .IX Item "cophh_copy"
4031 NOTE: \f(CW\*(C`cophh_copy\*(C'\fR is \fBexperimental\fR and may change or be
4032 removed without notice.
4033 .Sp
4034 Make and return a complete copy of the cop hints hash \f(CW\*(C`cophh\*(C'\fR.
4035 .RS 4
4036 .Sp
4037 .Vb 1
4038 \& COPHH * cophh_copy(COPHH *cophh)
4039 .Ve
4040 .RE
4041 .RS 4
4042 .RE
4043 .ie n .IP """cophh_delete_pv""" 4
4044 .el .IP \f(CWcophh_delete_pv\fR 4
4045 .IX Item "cophh_delete_pv"
4046 .PD 0
4047 .ie n .IP """cophh_delete_pvn""" 4
4048 .el .IP \f(CWcophh_delete_pvn\fR 4
4049 .IX Item "cophh_delete_pvn"
4050 .ie n .IP """cophh_delete_pvs""" 4
4051 .el .IP \f(CWcophh_delete_pvs\fR 4
4052 .IX Item "cophh_delete_pvs"
4053 .ie n .IP """cophh_delete_sv""" 4
4054 .el .IP \f(CWcophh_delete_sv\fR 4
4055 .IX Xref "cophh_delete_pv cophh_delete_pvn cophh_delete_pvs cophh_delete_sv"
4056 .IX Item "cophh_delete_sv"
4057 .PD
4058 NOTE: all these forms are \fBexperimental\fR and may change or be
4059 removed without notice.
4060 .Sp
4061 These delete a key and its associated value from the cop hints hash \f(CW\*(C`cophh\*(C'\fR,
4062 and return the modified hash. The returned hash pointer is in general
4063 not the same as the hash pointer that was passed in. The input hash is
4064 consumed by the function, and the pointer to it must not be subsequently
4065 used. Use "cophh_copy" if you need both hashes.
4066 .Sp
4067 The forms differ in how the key is specified. In all forms, the key is pointed
4068 to by \f(CW\*(C`key\*(C'\fR.
4069 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
4070 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4071 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4072 the string, which hence, may contain embedded-NUL characters.
4073 In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
4074 using \f(CW"SvPV_const"\fR.
4075 .Sp
4076 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4077 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4078 automatically at compile time.
4079 .Sp
4080 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4081 It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
4082 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4083 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4084 the octets.
4085 .RS 4
4086 .Sp
4087 .Vb 7
4088 \& COPHH * cophh_delete_pv (COPHH *cophh, const char *key, U32 hash,
4089 \& U32 flags)
4090 \& COPHH * cophh_delete_pvn(COPHH *cophh, const char *key,
4091 \& STRLEN keylen, U32 hash, U32 flags)
4092 \& COPHH * cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
4093 \& COPHH * cophh_delete_sv (COPHH *cophh, SV *key, U32 hash,
4094 \& U32 flags)
4095 .Ve
4096 .RE
4097 .RS 4
4098 .RE
4099 .ie n .IP """cophh_exists_pvn""" 4
4100 .el .IP \f(CWcophh_exists_pvn\fR 4
4101 .IX Xref "cophh_exists_pvn"
4102 .IX Item "cophh_exists_pvn"
4103 NOTE: \f(CW\*(C`cophh_exists_pvn\*(C'\fR is \fBexperimental\fR and may change or be
4104 removed without notice.
4105 .Sp
4106 These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
4107 \&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning true if a value exists,
4108 and false otherwise.
4109 .Sp
4110 The forms differ in how the key is specified.
4111 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
4112 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4113 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4114 the string, which hence, may contain embedded-NUL characters.
4115 In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
4116 using \f(CW"SvPV_const"\fR.
4117 .Sp
4118 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4119 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4120 automatically at compile time.
4121 .Sp
4122 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4123 It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
4124 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4125 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4126 the octets.
4127 .RS 4
4128 .Sp
4129 .Vb 2
4130 \& bool cophh_exists_pvn(const COPHH *cophh, const char *key,
4131 \& STRLEN keylen, U32 hash, U32 flags)
4132 .Ve
4133 .RE
4134 .RS 4
4135 .RE
4136 .ie n .IP """cophh_fetch_pv""" 4
4137 .el .IP \f(CWcophh_fetch_pv\fR 4
4138 .IX Item "cophh_fetch_pv"
4139 .PD 0
4140 .ie n .IP """cophh_fetch_pvn""" 4
4141 .el .IP \f(CWcophh_fetch_pvn\fR 4
4142 .IX Item "cophh_fetch_pvn"
4143 .ie n .IP """cophh_fetch_pvs""" 4
4144 .el .IP \f(CWcophh_fetch_pvs\fR 4
4145 .IX Item "cophh_fetch_pvs"
4146 .ie n .IP """cophh_fetch_sv""" 4
4147 .el .IP \f(CWcophh_fetch_sv\fR 4
4148 .IX Xref "cophh_fetch_pv cophh_fetch_pvn cophh_fetch_pvs cophh_fetch_sv"
4149 .IX Item "cophh_fetch_sv"
4150 .PD
4151 NOTE: all these forms are \fBexperimental\fR and may change or be
4152 removed without notice.
4153 .Sp
4154 These look up the entry in the cop hints hash \f(CW\*(C`cophh\*(C'\fR with the key specified by
4155 \&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning that value as a mortal
4156 scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the
4157 key.
4158 .Sp
4159 The forms differ in how the key is specified.
4160 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
4161 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4162 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4163 the string, which hence, may contain embedded-NUL characters.
4164 In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
4165 using \f(CW"SvPV_const"\fR.
4166 .Sp
4167 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4168 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4169 automatically at compile time.
4170 .Sp
4171 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4172 It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
4173 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4174 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4175 the octets.
4176 .RS 4
4177 .Sp
4178 .Vb 7
4179 \& SV * cophh_fetch_pv (const COPHH *cophh, const char *key,
4180 \& U32 hash, U32 flags)
4181 \& SV * cophh_fetch_pvn(const COPHH *cophh, const char *key,
4182 \& STRLEN keylen, U32 hash, U32 flags)
4183 \& SV * cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
4184 \& SV * cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash,
4185 \& U32 flags)
4186 .Ve
4187 .RE
4188 .RS 4
4189 .RE
4190 .ie n .IP """cophh_free""" 4
4191 .el .IP \f(CWcophh_free\fR 4
4192 .IX Xref "cophh_free"
4193 .IX Item "cophh_free"
4194 NOTE: \f(CW\*(C`cophh_free\*(C'\fR is \fBexperimental\fR and may change or be
4195 removed without notice.
4196 .Sp
4197 Discard the cop hints hash \f(CW\*(C`cophh\*(C'\fR, freeing all resources associated
4198 with it.
4199 .RS 4
4200 .Sp
4201 .Vb 1
4202 \& void cophh_free(COPHH *cophh)
4203 .Ve
4204 .RE
4205 .RS 4
4206 .RE
4207 .ie n .IP """cophh_2hv""" 4
4208 .el .IP \f(CWcophh_2hv\fR 4
4209 .IX Xref "cophh_2hv"
4210 .IX Item "cophh_2hv"
4211 NOTE: \f(CW\*(C`cophh_2hv\*(C'\fR is \fBexperimental\fR and may change or be
4212 removed without notice.
4213 .Sp
4214 Generates and returns a standard Perl hash representing the full set of
4215 key/value pairs in the cop hints hash \f(CW\*(C`cophh\*(C'\fR. \f(CW\*(C`flags\*(C'\fR is currently
4216 unused and must be zero.
4217 .RS 4
4218 .Sp
4219 .Vb 1
4220 \& HV * cophh_2hv(const COPHH *cophh, U32 flags)
4221 .Ve
4222 .RE
4223 .RS 4
4224 .RE
4225 .ie n .IP """cophh_new_empty""" 4
4226 .el .IP \f(CWcophh_new_empty\fR 4
4227 .IX Xref "cophh_new_empty"
4228 .IX Item "cophh_new_empty"
4229 NOTE: \f(CW\*(C`cophh_new_empty\*(C'\fR is \fBexperimental\fR and may change or be
4230 removed without notice.
4231 .Sp
4232 Generate and return a fresh cop hints hash containing no entries.
4233 .RS 4
4234 .Sp
4235 .Vb 1
4236 \& COPHH * cophh_new_empty()
4237 .Ve
4238 .RE
4239 .RS 4
4240 .RE
4241 .ie n .IP """cophh_store_pv""" 4
4242 .el .IP \f(CWcophh_store_pv\fR 4
4243 .IX Item "cophh_store_pv"
4244 .PD 0
4245 .ie n .IP """cophh_store_pvn""" 4
4246 .el .IP \f(CWcophh_store_pvn\fR 4
4247 .IX Item "cophh_store_pvn"
4248 .ie n .IP """cophh_store_pvs""" 4
4249 .el .IP \f(CWcophh_store_pvs\fR 4
4250 .IX Item "cophh_store_pvs"
4251 .ie n .IP """cophh_store_sv""" 4
4252 .el .IP \f(CWcophh_store_sv\fR 4
4253 .IX Xref "cophh_store_pv cophh_store_pvn cophh_store_pvs cophh_store_sv"
4254 .IX Item "cophh_store_sv"
4255 .PD
4256 NOTE: all these forms are \fBexperimental\fR and may change or be
4257 removed without notice.
4258 .Sp
4259 These store a value, associated with a key, in the cop hints hash \f(CW\*(C`cophh\*(C'\fR,
4260 and return the modified hash. The returned hash pointer is in general
4261 not the same as the hash pointer that was passed in. The input hash is
4262 consumed by the function, and the pointer to it must not be subsequently
4263 used. Use "cophh_copy" if you need both hashes.
4264 .Sp
4265 \&\f(CW\*(C`value\*(C'\fR is the scalar value to store for this key. \f(CW\*(C`value\*(C'\fR is copied
4266 by these functions, which thus do not take ownership of any reference
4267 to it, and hence later changes to the scalar will not be reflected in the value
4268 visible in the cop hints hash. Complex types of scalar will not be stored with
4269 referential integrity, but will be coerced to strings.
4270 .Sp
4271 The forms differ in how the key is specified. In all forms, the key is pointed
4272 to by \f(CW\*(C`key\*(C'\fR.
4273 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
4274 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4275 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4276 the string, which hence, may contain embedded-NUL characters.
4277 In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
4278 using \f(CW"SvPV_const"\fR.
4279 .Sp
4280 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4281 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4282 automatically at compile time.
4283 .Sp
4284 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4285 It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
4286 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4287 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4288 the octets.
4289 .RS 4
4290 .Sp
4291 .Vb 9
4292 \& COPHH * cophh_store_pv (COPHH *cophh, const char *key, U32 hash,
4293 \& SV *value, U32 flags)
4294 \& COPHH * cophh_store_pvn(COPHH *cophh, const char *key,
4295 \& STRLEN keylen, U32 hash, SV *value,
4296 \& U32 flags)
4297 \& COPHH * cophh_store_pvs(COPHH *cophh, "key", SV *value,
4298 \& U32 flags)
4299 \& COPHH * cophh_store_sv (COPHH *cophh, SV *key, U32 hash,
4300 \& SV *value, U32 flags)
4301 .Ve
4302 .RE
4303 .RS 4
4304 .RE
4305 .ie n .IP """cop_hints_exists_pv""" 4
4306 .el .IP \f(CWcop_hints_exists_pv\fR 4
4307 .IX Item "cop_hints_exists_pv"
4308 .PD 0
4309 .ie n .IP """cop_hints_exists_pvn""" 4
4310 .el .IP \f(CWcop_hints_exists_pvn\fR 4
4311 .IX Item "cop_hints_exists_pvn"
4312 .ie n .IP """cop_hints_exists_pvs""" 4
4313 .el .IP \f(CWcop_hints_exists_pvs\fR 4
4314 .IX Item "cop_hints_exists_pvs"
4315 .ie n .IP """cop_hints_exists_sv""" 4
4316 .el .IP \f(CWcop_hints_exists_sv\fR 4
4317 .IX Xref "cop_hints_exists_pv cop_hints_exists_pvn cop_hints_exists_pvs cop_hints_exists_sv"
4318 .IX Item "cop_hints_exists_sv"
4319 .PD
4320 These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
4321 \&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning true if a value exists,
4322 and false otherwise.
4323 .Sp
4324 The forms differ in how the key is specified. In all forms, the key is pointed
4325 to by \f(CW\*(C`key\*(C'\fR.
4326 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
4327 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4328 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4329 the string, which hence, may contain embedded-NUL characters.
4330 In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
4331 using \f(CW"SvPV_const"\fR.
4332 .Sp
4333 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4334 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4335 automatically at compile time.
4336 .Sp
4337 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4338 It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
4339 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4340 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4341 the octets.
4342 .RS 4
4343 .Sp
4344 .Vb 7
4345 \& bool cop_hints_exists_pv (const COP *cop, const char *key,
4346 \& U32 hash, U32 flags)
4347 \& bool cop_hints_exists_pvn(const COP *cop, const char *key,
4348 \& STRLEN keylen, U32 hash, U32 flags)
4349 \& bool cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
4350 \& bool cop_hints_exists_sv (const COP *cop, SV *key, U32 hash,
4351 \& U32 flags)
4352 .Ve
4353 .RE
4354 .RS 4
4355 .RE
4356 .ie n .IP """cop_hints_fetch_pv""" 4
4357 .el .IP \f(CWcop_hints_fetch_pv\fR 4
4358 .IX Item "cop_hints_fetch_pv"
4359 .PD 0
4360 .ie n .IP """cop_hints_fetch_pvn""" 4
4361 .el .IP \f(CWcop_hints_fetch_pvn\fR 4
4362 .IX Item "cop_hints_fetch_pvn"
4363 .ie n .IP """cop_hints_fetch_pvs""" 4
4364 .el .IP \f(CWcop_hints_fetch_pvs\fR 4
4365 .IX Item "cop_hints_fetch_pvs"
4366 .ie n .IP """cop_hints_fetch_sv""" 4
4367 .el .IP \f(CWcop_hints_fetch_sv\fR 4
4368 .IX Xref "cop_hints_fetch_pv cop_hints_fetch_pvn cop_hints_fetch_pvs cop_hints_fetch_sv"
4369 .IX Item "cop_hints_fetch_sv"
4370 .PD
4371 These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
4372 \&\f(CW\*(C`key\*(C'\fR (and \f(CW\*(C`keylen\*(C'\fR in the \f(CW\*(C`pvn\*(C'\fR form), returning that value as a mortal
4373 scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the
4374 key.
4375 .Sp
4376 The forms differ in how the key is specified.
4377 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL-terminated string.
4378 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4379 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4380 the string, which hence, may contain embedded-NUL characters.
4381 In the \f(CW\*(C`sv\*(C'\fR form, \f(CW*key\fR is an SV, and the key is the PV extracted from that.
4382 using \f(CW"SvPV_const"\fR.
4383 .Sp
4384 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4385 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4386 automatically at compile time.
4387 .Sp
4388 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4389 It is illegal to set this in the \f(CW\*(C`sv\*(C'\fR form. In the \f(CW\*(C`pv*\*(C'\fR forms, it specifies
4390 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4391 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4392 the octets.
4393 .RS 4
4394 .Sp
4395 .Vb 7
4396 \& SV * cop_hints_fetch_pv (const COP *cop, const char *key,
4397 \& U32 hash, U32 flags)
4398 \& SV * cop_hints_fetch_pvn(const COP *cop, const char *key,
4399 \& STRLEN keylen, U32 hash, U32 flags)
4400 \& SV * cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
4401 \& SV * cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash,
4402 \& U32 flags)
4403 .Ve
4404 .RE
4405 .RS 4
4406 .RE
4407 .ie n .IP """cop_hints_2hv""" 4
4408 .el .IP \f(CWcop_hints_2hv\fR 4
4409 .IX Xref "cop_hints_2hv"
4410 .IX Item "cop_hints_2hv"
4411 Generates and returns a standard Perl hash representing the full set of
4412 hint entries in the cop \f(CW\*(C`cop\*(C'\fR. \f(CW\*(C`flags\*(C'\fR is currently unused and must
4413 be zero.
4414 .RS 4
4415 .Sp
4416 .Vb 1
4417 \& HV * cop_hints_2hv(const COP *cop, U32 flags)
4418 .Ve
4419 .RE
4420 .RS 4
4421 .RE
4422 .ie n .IP """CopLABEL""" 4
4423 .el .IP \f(CWCopLABEL\fR 4
4424 .IX Item "CopLABEL"
4425 .PD 0
4426 .ie n .IP """CopLABEL_len""" 4
4427 .el .IP \f(CWCopLABEL_len\fR 4
4428 .IX Item "CopLABEL_len"
4429 .ie n .IP """CopLABEL_len_flags""" 4
4430 .el .IP \f(CWCopLABEL_len_flags\fR 4
4431 .IX Xref "CopLABEL CopLABEL_len CopLABEL_len_flags"
4432 .IX Item "CopLABEL_len_flags"
4433 .PD
4434 These return the label attached to a cop.
4435 .Sp
4436 \&\f(CW\*(C`CopLABEL_len\*(C'\fR and \f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally store the number of
4437 bytes comprising the returned label into \f(CW*len\fR.
4438 .Sp
4439 \&\f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally returns the UTF\-8ness of the returned label,
4440 by setting \f(CW*flags\fR to 0 or \f(CW\*(C`SVf_UTF8\*(C'\fR.
4441 .RS 4
4442 .Sp
4443 .Vb 4
4444 \& const char * CopLABEL (COP *const cop)
4445 \& const char * CopLABEL_len (COP *const cop, STRLEN *len)
4446 \& const char * CopLABEL_len_flags(COP *const cop, STRLEN *len,
4447 \& U32 *flags)
4448 .Ve
4449 .RE
4450 .RS 4
4451 .RE
4452 .ie n .IP """CopLINE""" 4
4453 .el .IP \f(CWCopLINE\fR 4
4454 .IX Xref "CopLINE"
4455 .IX Item "CopLINE"
4456 Returns the line number in the source code associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
4457 .RS 4
4458 .Sp
4459 .Vb 1
4460 \& line_t CopLINE(const COP * c)
4461 .Ve
4462 .RE
4463 .RS 4
4464 .RE
4465 .ie n .IP """CopSTASH""" 4
4466 .el .IP \f(CWCopSTASH\fR 4
4467 .IX Xref "CopSTASH"
4468 .IX Item "CopSTASH"
4469 Returns the stash associated with \f(CW\*(C`c\*(C'\fR.
4470 .RS 4
4471 .Sp
4472 .Vb 1
4473 \& HV * CopSTASH(const COP * c)
4474 .Ve
4475 .RE
4476 .RS 4
4477 .RE
4478 .ie n .IP """CopSTASH_eq""" 4
4479 .el .IP \f(CWCopSTASH_eq\fR 4
4480 .IX Xref "CopSTASH_eq"
4481 .IX Item "CopSTASH_eq"
4482 Returns a boolean as to whether or not \f(CW\*(C`hv\*(C'\fR is the stash associated with \f(CW\*(C`c\*(C'\fR.
4483 .RS 4
4484 .Sp
4485 .Vb 1
4486 \& bool CopSTASH_eq(const COP * c, const HV * hv)
4487 .Ve
4488 .RE
4489 .RS 4
4490 .RE
4491 .ie n .IP """CopSTASHPV""" 4
4492 .el .IP \f(CWCopSTASHPV\fR 4
4493 .IX Xref "CopSTASHPV"
4494 .IX Item "CopSTASHPV"
4495 Returns the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if no
4496 associated stash
4497 .RS 4
4498 .Sp
4499 .Vb 1
4500 \& char * CopSTASHPV(const COP * c)
4501 .Ve
4502 .RE
4503 .RS 4
4504 .RE
4505 .ie n .IP """CopSTASHPV_set""" 4
4506 .el .IP \f(CWCopSTASHPV_set\fR 4
4507 .IX Xref "CopSTASHPV_set"
4508 .IX Item "CopSTASHPV_set"
4509 Set the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, to the NUL-terminated C
4510 string \f(CW\*(C`p\*(C'\fR, creating the package if necessary.
4511 .RS 4
4512 .Sp
4513 .Vb 1
4514 \& void CopSTASHPV_set(COP * c, const char * pv)
4515 .Ve
4516 .RE
4517 .RS 4
4518 .RE
4519 .ie n .IP """CopSTASH_set""" 4
4520 .el .IP \f(CWCopSTASH_set\fR 4
4521 .IX Xref "CopSTASH_set"
4522 .IX Item "CopSTASH_set"
4523 Set the stash associated with \f(CW\*(C`c\*(C'\fR to \f(CW\*(C`hv\*(C'\fR.
4524 .RS 4
4525 .Sp
4526 .Vb 1
4527 \& bool CopSTASH_set(COP * c, HV * hv)
4528 .Ve
4529 .RE
4530 .RS 4
4531 .RE
4532 .ie n .IP """cop_store_label""" 4
4533 .el .IP \f(CWcop_store_label\fR 4
4534 .IX Xref "cop_store_label"
4535 .IX Item "cop_store_label"
4536 NOTE: \f(CW\*(C`cop_store_label\*(C'\fR is \fBexperimental\fR and may change or be
4537 removed without notice.
4538 .Sp
4539 Save a label into a \f(CW\*(C`cop_hints_hash\*(C'\fR.
4540 You need to set flags to \f(CW\*(C`SVf_UTF8\*(C'\fR
4541 for a UTF\-8 label. Any other flag is ignored.
4542 .RS 4
4543 .Sp
4544 .Vb 2
4545 \& void cop_store_label(COP * const cop, const char *label,
4546 \& STRLEN len, U32 flags)
4547 .Ve
4548 .RE
4549 .RS 4
4550 .RE
4551 .ie n .IP """PERL_SI""" 4
4552 .el .IP \f(CWPERL_SI\fR 4
4553 .IX Xref "PERL_SI"
4554 .IX Item "PERL_SI"
4555 Use this typedef to declare variables that are to hold \f(CW\*(C`struct stackinfo\*(C'\fR.
4556 .ie n .IP """PL_curcop""" 4
4557 .el .IP \f(CWPL_curcop\fR 4
4558 .IX Xref "PL_curcop"
4559 .IX Item "PL_curcop"
4560 The currently active COP (control op) roughly representing the current
4561 statement in the source.
4562 .Sp
4563 On threaded perls, each thread has an independent copy of this variable;
4564 each initialized at creation time with the current value of the creating
4565 thread's copy.
4566 .RS 4
4567 .Sp
4568 .Vb 1
4569 \& COP* PL_curcop
4570 .Ve
4571 .RE
4572 .RS 4
4573 .RE
4574 .ie n .IP """RCPV_LEN""" 4
4575 .el .IP \f(CWRCPV_LEN\fR 4
4576 .IX Xref "RCPV_LEN"
4577 .IX Item "RCPV_LEN"
4578 Returns the length of a pv created with \f(CWrcpv_new()\fR.
4579 Note that this reflects the length of the string from the callers
4580 point of view, it does not include the mandatory null which is
4581 always injected at the end of the string by \fBrcpv_new()\fR.
4582 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4583 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4584 this is the case.
4585 .RS 4
4586 .Sp
4587 .Vb 1
4588 \& RCPV * RCPV_LEN(char *pv)
4589 .Ve
4590 .RE
4591 .RS 4
4592 .RE
4593 .ie n .IP """RCPV_REFCNT_dec""" 4
4594 .el .IP \f(CWRCPV_REFCNT_dec\fR 4
4595 .IX Xref "RCPV_REFCNT_dec"
4596 .IX Item "RCPV_REFCNT_dec"
4597 Decrements the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created
4598 with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_free()\fR.
4599 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4600 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4601 this is the case.
4602 .RS 4
4603 .Sp
4604 .Vb 1
4605 \& RCPV * RCPV_REFCNT_dec(char *pv)
4606 .Ve
4607 .RE
4608 .RS 4
4609 .RE
4610 .ie n .IP """RCPV_REFCNT_inc""" 4
4611 .el .IP \f(CWRCPV_REFCNT_inc\fR 4
4612 .IX Xref "RCPV_REFCNT_inc"
4613 .IX Item "RCPV_REFCNT_inc"
4614 Increments the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created
4615 with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_copy()\fR.
4616 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4617 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4618 this is the case.
4619 .RS 4
4620 .Sp
4621 .Vb 1
4622 \& RCPV * RCPV_REFCNT_inc(char *pv)
4623 .Ve
4624 .RE
4625 .RS 4
4626 .RE
4627 .ie n .IP """RCPV_REFCOUNT""" 4
4628 .el .IP \f(CWRCPV_REFCOUNT\fR 4
4629 .IX Xref "RCPV_REFCOUNT"
4630 .IX Item "RCPV_REFCOUNT"
4631 Returns the refcount for a pv created with \f(CWrcpv_new()\fR.
4632 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4633 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4634 this is the case.
4635 .RS 4
4636 .Sp
4637 .Vb 1
4638 \& RCPV * RCPV_REFCOUNT(char *pv)
4639 .Ve
4640 .RE
4641 .RS 4
4642 .RE
4643 .ie n .IP """RCPVx""" 4
4644 .el .IP \f(CWRCPVx\fR 4
4645 .IX Xref "RCPVx"
4646 .IX Item "RCPVx"
4647 Returns the RCPV structure (struct rcpv) for a refcounted
4648 string pv created with \f(CWrcpv_new()\fR.
4649 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4650 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4651 this is the case.
4652 .RS 4
4653 .Sp
4654 .Vb 1
4655 \& RCPV * RCPVx(char *pv)
4656 .Ve
4657 .RE
4658 .RS 4
4659 .RE
4660 .SH "Custom Operators"
4661 .IX Header "Custom Operators"
4662 .ie n .IP """custom_op_register""" 4
4663 .el .IP \f(CWcustom_op_register\fR 4
4664 .IX Xref "custom_op_register"
4665 .IX Item "custom_op_register"
4666 Register a custom op. See "Custom Operators" in perlguts.
4667 .Sp
4668 NOTE: \f(CW\*(C`custom_op_register\*(C'\fR must be explicitly called as
4669 \&\f(CW\*(C`Perl_custom_op_register\*(C'\fR
4670 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
4671 .RS 4
4672 .Sp
4673 .Vb 2
4674 \& void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
4675 \& const XOP *xop)
4676 .Ve
4677 .RE
4678 .RS 4
4679 .RE
4680 .ie n .IP """Perl_custom_op_xop""" 4
4681 .el .IP \f(CWPerl_custom_op_xop\fR 4
4682 .IX Xref "Perl_custom_op_xop"
4683 .IX Item "Perl_custom_op_xop"
4684 Return the XOP structure for a given custom op. This macro should be
4685 considered internal to \f(CW\*(C`OP_NAME\*(C'\fR and the other access macros: use them instead.
4686 This macro does call a function. Prior
4687 to 5.19.6, this was implemented as a
4688 function.
4689 .RS 4
4690 .Sp
4691 .Vb 1
4692 \& const XOP * Perl_custom_op_xop(pTHX_ const OP *o)
4693 .Ve
4694 .RE
4695 .RS 4
4696 .RE
4697 .ie n .IP """XopDISABLE""" 4
4698 .el .IP \f(CWXopDISABLE\fR 4
4699 .IX Xref "XopDISABLE"
4700 .IX Item "XopDISABLE"
4701 Temporarily disable a member of the XOP, by clearing the appropriate flag.
4702 .RS 4
4703 .Sp
4704 .Vb 1
4705 \& void XopDISABLE(XOP *xop, token which)
4706 .Ve
4707 .RE
4708 .RS 4
4709 .RE
4710 .ie n .IP """XopENABLE""" 4
4711 .el .IP \f(CWXopENABLE\fR 4
4712 .IX Xref "XopENABLE"
4713 .IX Item "XopENABLE"
4714 Reenable a member of the XOP which has been disabled.
4715 .RS 4
4716 .Sp
4717 .Vb 1
4718 \& void XopENABLE(XOP *xop, token which)
4719 .Ve
4720 .RE
4721 .RS 4
4722 .RE
4723 .ie n .IP """XopENTRY""" 4
4724 .el .IP \f(CWXopENTRY\fR 4
4725 .IX Xref "XopENTRY"
4726 .IX Item "XopENTRY"
4727 Return a member of the XOP structure. \f(CW\*(C`which\*(C'\fR is a cpp token
4728 indicating which entry to return. If the member is not set
4729 this will return a default value. The return type depends
4730 on \f(CW\*(C`which\*(C'\fR. This macro evaluates its arguments more than
4731 once. If you are using \f(CW\*(C`Perl_custom_op_xop\*(C'\fR to retrieve a
4732 \&\f(CW\*(C`XOP *\*(C'\fR from a \f(CW\*(C`OP *\*(C'\fR, use the more efficient "XopENTRYCUSTOM" instead.
4733 .RS 4
4734 .Sp
4735 .Vb 1
4736 \& XopENTRY(XOP *xop, token which)
4737 .Ve
4738 .RE
4739 .RS 4
4740 .RE
4741 .ie n .IP """XopENTRYCUSTOM""" 4
4742 .el .IP \f(CWXopENTRYCUSTOM\fR 4
4743 .IX Xref "XopENTRYCUSTOM"
4744 .IX Item "XopENTRYCUSTOM"
4745 Exactly like \f(CW\*(C`XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which)\*(C'\fR but more
4746 efficient. The \f(CW\*(C`which\*(C'\fR parameter is identical to "XopENTRY".
4747 .RS 4
4748 .Sp
4749 .Vb 1
4750 \& XopENTRYCUSTOM(const OP *o, token which)
4751 .Ve
4752 .RE
4753 .RS 4
4754 .RE
4755 .ie n .IP """XopENTRY_set""" 4
4756 .el .IP \f(CWXopENTRY_set\fR 4
4757 .IX Xref "XopENTRY_set"
4758 .IX Item "XopENTRY_set"
4759 Set a member of the XOP structure. \f(CW\*(C`which\*(C'\fR is a cpp token
4760 indicating which entry to set. See "Custom Operators" in perlguts
4761 for details about the available members and how
4762 they are used. This macro evaluates its argument
4763 more than once.
4764 .RS 4
4765 .Sp
4766 .Vb 1
4767 \& void XopENTRY_set(XOP *xop, token which, value)
4768 .Ve
4769 .RE
4770 .RS 4
4771 .RE
4772 .ie n .IP """XopFLAGS""" 4
4773 .el .IP \f(CWXopFLAGS\fR 4
4774 .IX Xref "XopFLAGS"
4775 .IX Item "XopFLAGS"
4776 Return the XOP's flags.
4777 .RS 4
4778 .Sp
4779 .Vb 1
4780 \& U32 XopFLAGS(XOP *xop)
4781 .Ve
4782 .RE
4783 .RS 4
4784 .RE
4785 .SH "CV Handling"
4786 .IX Xref "CV GV_ADD"
4787 .IX Header "CV Handling"
4788 This section documents functions to manipulate CVs which are
4789 code-values, meaning subroutines. For more information, see
4790 perlguts.
4791 .ie n .IP """caller_cx""" 4
4792 .el .IP \f(CWcaller_cx\fR 4
4793 .IX Xref "caller_cx"
4794 .IX Item "caller_cx"
4795 The XSUB-writer's equivalent of \fBcaller()\fR. The
4796 returned \f(CW\*(C`PERL_CONTEXT\*(C'\fR structure can be interrogated to find all the
4797 information returned to Perl by \f(CW\*(C`caller\*(C'\fR. Note that XSUBs don't get a
4798 stack frame, so \f(CW\*(C`caller_cx(0, NULL)\*(C'\fR will return information for the
4799 immediately-surrounding Perl code.
4800 .Sp
4801 This function skips over the automatic calls to \f(CW&DB::sub\fR made on the
4802 behalf of the debugger. If the stack frame requested was a sub called by
4803 \&\f(CW\*(C`DB::sub\*(C'\fR, the return value will be the frame for the call to
4804 \&\f(CW\*(C`DB::sub\*(C'\fR, since that has the correct line number/etc. for the call
4805 site. If \fIdbcxp\fR is non\-\f(CW\*(C`NULL\*(C'\fR, it will be set to a pointer to the
4806 frame for the sub call itself.
4807 .RS 4
4808 .Sp
4809 .Vb 2
4810 \& const PERL_CONTEXT * caller_cx(I32 level,
4811 \& const PERL_CONTEXT **dbcxp)
4812 .Ve
4813 .RE
4814 .RS 4
4815 .RE
4816 .ie n .IP """CvDEPTH""" 4
4817 .el .IP \f(CWCvDEPTH\fR 4
4818 .IX Xref "CvDEPTH"
4819 .IX Item "CvDEPTH"
4820 Returns the recursion level of the CV \f(CW\*(C`sv\*(C'\fR. Hence >= 2 indicates we are in a
4821 recursive call.
4822 .RS 4
4823 .Sp
4824 .Vb 1
4825 \& I32 * CvDEPTH(const CV * const sv)
4826 .Ve
4827 .RE
4828 .RS 4
4829 .RE
4830 .ie n .IP """CvGV""" 4
4831 .el .IP \f(CWCvGV\fR 4
4832 .IX Xref "CvGV"
4833 .IX Item "CvGV"
4834 Returns the GV associated with the CV \f(CW\*(C`sv\*(C'\fR, reifying it if necessary.
4835 .RS 4
4836 .Sp
4837 .Vb 1
4838 \& GV * CvGV(CV *sv)
4839 .Ve
4840 .RE
4841 .RS 4
4842 .RE
4843 .ie n .IP """CvSTASH""" 4
4844 .el .IP \f(CWCvSTASH\fR 4
4845 .IX Xref "CvSTASH"
4846 .IX Item "CvSTASH"
4847 Returns the stash of the CV. A stash is the symbol table hash, containing
4848 the package-scoped variables in the package where the subroutine was defined.
4849 For more information, see perlguts.
4850 .Sp
4851 This also has a special use with XS AUTOLOAD subs.
4852 See "Autoloading with XSUBs" in perlguts.
4853 .RS 4
4854 .Sp
4855 .Vb 1
4856 \& HV* CvSTASH(CV* cv)
4857 .Ve
4858 .RE
4859 .RS 4
4860 .RE
4861 .ie n .IP """find_runcv""" 4
4862 .el .IP \f(CWfind_runcv\fR 4
4863 .IX Xref "find_runcv"
4864 .IX Item "find_runcv"
4865 Locate the CV corresponding to the currently executing sub or eval.
4866 If \f(CW\*(C`db_seqp\*(C'\fR is non_null, skip CVs that are in the DB package and populate
4867 \&\f(CW*db_seqp\fR with the cop sequence number at the point that the DB:: code was
4868 entered. (This allows debuggers to eval in the scope of the breakpoint
4869 rather than in the scope of the debugger itself.)
4870 .RS 4
4871 .Sp
4872 .Vb 1
4873 \& CV * find_runcv(U32 *db_seqp)
4874 .Ve
4875 .RE
4876 .RS 4
4877 .RE
4878 .ie n .IP """get_cv""" 4
4879 .el .IP \f(CWget_cv\fR 4
4880 .IX Item "get_cv"
4881 .PD 0
4882 .ie n .IP """get_cvn_flags""" 4
4883 .el .IP \f(CWget_cvn_flags\fR 4
4884 .IX Item "get_cvn_flags"
4885 .ie n .IP """get_cvs""" 4
4886 .el .IP \f(CWget_cvs\fR 4
4887 .IX Xref "get_cv get_cvn_flags get_cvs"
4888 .IX Item "get_cvs"
4889 .PD
4890 These return the CV of the specified Perl subroutine. \f(CW\*(C`flags\*(C'\fR are passed to
4891 \&\f(CW\*(C`gv_fetchpvn_flags\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the Perl subroutine does not
4892 exist then it will be declared (which has the same effect as saying
4893 \&\f(CW\*(C`sub name;\*(C'\fR). If \f(CW\*(C`GV_ADD\*(C'\fR is not set and the subroutine does not exist,
4894 then NULL is returned.
4895 .Sp
4896 The forms differ only in how the subroutine is specified.. With \f(CW\*(C`get_cvs\*(C'\fR,
4897 the name is a literal C string, enclosed in double quotes. With \f(CW\*(C`get_cv\*(C'\fR, the
4898 name is given by the \f(CW\*(C`name\*(C'\fR parameter, which must be a NUL-terminated C
4899 string. With \f(CW\*(C`get_cvn_flags\*(C'\fR, the name is also given by the \f(CW\*(C`name\*(C'\fR
4900 parameter, but it is a Perl string (possibly containing embedded NUL bytes),
4901 and its length in bytes is contained in the \f(CW\*(C`len\*(C'\fR parameter.
4902 .Sp
4903 NOTE: the \f(CWperl_get_cv()\fR form is \fBdeprecated\fR.
4904 .Sp
4905 NOTE: the \f(CWperl_get_cvn_flags()\fR form is \fBdeprecated\fR.
4906 .Sp
4907 NOTE: the \f(CWperl_get_cvs()\fR form is \fBdeprecated\fR.
4908 .RS 4
4909 .Sp
4910 .Vb 3
4911 \& CV * get_cv (const char *name, I32 flags)
4912 \& CV * get_cvn_flags(const char *name, STRLEN len, I32 flags)
4913 \& CV * get_cvs ("string", I32 flags)
4914 .Ve
4915 .RE
4916 .RS 4
4917 .RE
4918 .ie n .IP """Nullcv""" 4
4919 .el .IP \f(CWNullcv\fR 4
4920 .IX Xref "Nullcv"
4921 .IX Item "Nullcv"
4922 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullcv\*(C'\fR
4923 from a future release of Perl. Do not use it for
4924 new code; remove it from existing code.
4925 .Sp
4926 Null CV pointer.
4927 .Sp
4928 (deprecated \- use \f(CW\*(C`(CV *)NULL\*(C'\fR instead)
4929 .SH Debugging
4930 .IX Header "Debugging"
4931 .ie n .IP """av_dump""" 4
4932 .el .IP \f(CWav_dump\fR 4
4933 .IX Xref "av_dump"
4934 .IX Item "av_dump"
4935 Dumps the contents of an AV to the \f(CW\*(C`STDERR\*(C'\fR filehandle,
4936 Similar to using Devel::Peek on an arrayref but does not
4937 expect an RV wrapper. Dumps contents to a depth of 3 levels
4938 deep.
4939 .RS 4
4940 .Sp
4941 .Vb 1
4942 \& void av_dump(AV *av)
4943 .Ve
4944 .RE
4945 .RS 4
4946 .RE
4947 .ie n .IP """deb""" 4
4948 .el .IP \f(CWdeb\fR 4
4949 .IX Item "deb"
4950 .PD 0
4951 .ie n .IP """deb_nocontext""" 4
4952 .el .IP \f(CWdeb_nocontext\fR 4
4953 .IX Xref "deb deb_nocontext"
4954 .IX Item "deb_nocontext"
4955 .PD
4956 When perl is compiled with \f(CW\*(C`\-DDEBUGGING\*(C'\fR, this prints to STDERR the
4957 information given by the arguments, prefaced by the name of the file containing
4958 the script causing the call, and the line number within that file.
4959 .Sp
4960 If the \f(CW\*(C`v\*(C'\fR (verbose) debugging option is in effect, the process id is also
4961 printed.
4962 .Sp
4963 The two forms differ only in that \f(CW\*(C`deb_nocontext\*(C'\fR does not take a thread
4964 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
4965 already have the thread context.
4966 .Sp
4967 NOTE: \f(CW\*(C`deb\*(C'\fR must be explicitly called as
4968 \&\f(CW\*(C`Perl_deb\*(C'\fR
4969 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
4970 .RS 4
4971 .Sp
4972 .Vb 2
4973 \& void Perl_deb (pTHX_ const char *pat, ...)
4974 \& void deb_nocontext(const char *pat, ...)
4975 .Ve
4976 .RE
4977 .RS 4
4978 .RE
4979 .ie n .IP """debstack""" 4
4980 .el .IP \f(CWdebstack\fR 4
4981 .IX Xref "debstack"
4982 .IX Item "debstack"
4983 Dump the current stack
4984 .RS 4
4985 .Sp
4986 .Vb 1
4987 \& I32 debstack()
4988 .Ve
4989 .RE
4990 .RS 4
4991 .RE
4992 .ie n .IP """dump_all""" 4
4993 .el .IP \f(CWdump_all\fR 4
4994 .IX Xref "dump_all"
4995 .IX Item "dump_all"
4996 Dumps the entire optree of the current program starting at \f(CW\*(C`PL_main_root\*(C'\fR to
4997 \&\f(CW\*(C`STDERR\*(C'\fR. Also dumps the optrees for all visible subroutines in
4998 \&\f(CW\*(C`PL_defstash\*(C'\fR.
4999 .RS 4
5000 .Sp
5001 .Vb 1
5002 \& void dump_all()
5003 .Ve
5004 .RE
5005 .RS 4
5006 .RE
5007 .ie n .IP """dump_c_backtrace""" 4
5008 .el .IP \f(CWdump_c_backtrace\fR 4
5009 .IX Xref "dump_c_backtrace"
5010 .IX Item "dump_c_backtrace"
5011 Dumps the C backtrace to the given \f(CW\*(C`fp\*(C'\fR.
5012 .Sp
5013 Returns true if a backtrace could be retrieved, false if not.
5014 .RS 4
5015 .Sp
5016 .Vb 1
5017 \& bool dump_c_backtrace(PerlIO *fp, int max_depth, int skip)
5018 .Ve
5019 .RE
5020 .RS 4
5021 .RE
5022 .ie n .IP """dump_eval""" 4
5023 .el .IP \f(CWdump_eval\fR 4
5024 .IX Item "dump_eval"
5025 Described in perlguts.
5026 .RS 4
5027 .Sp
5028 .Vb 1
5029 \& void dump_eval()
5030 .Ve
5031 .RE
5032 .RS 4
5033 .RE
5034 .ie n .IP """dump_form""" 4
5035 .el .IP \f(CWdump_form\fR 4
5036 .IX Xref "dump_form"
5037 .IX Item "dump_form"
5038 Dumps the contents of the format contained in the GV \f(CW\*(C`gv\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR, or a
5039 message that one doesn't exist.
5040 .RS 4
5041 .Sp
5042 .Vb 1
5043 \& void dump_form(const GV *gv)
5044 .Ve
5045 .RE
5046 .RS 4
5047 .RE
5048 .ie n .IP """dump_packsubs""" 4
5049 .el .IP \f(CWdump_packsubs\fR 4
5050 .IX Xref "dump_packsubs"
5051 .IX Item "dump_packsubs"
5052 Dumps the optrees for all visible subroutines in \f(CW\*(C`stash\*(C'\fR.
5053 .RS 4
5054 .Sp
5055 .Vb 1
5056 \& void dump_packsubs(const HV *stash)
5057 .Ve
5058 .RE
5059 .RS 4
5060 .RE
5061 .ie n .IP """dump_sub""" 4
5062 .el .IP \f(CWdump_sub\fR 4
5063 .IX Item "dump_sub"
5064 Described in perlguts.
5065 .RS 4
5066 .Sp
5067 .Vb 1
5068 \& void dump_sub(const GV *gv)
5069 .Ve
5070 .RE
5071 .RS 4
5072 .RE
5073 .ie n .IP """get_c_backtrace_dump""" 4
5074 .el .IP \f(CWget_c_backtrace_dump\fR 4
5075 .IX Xref "get_c_backtrace_dump"
5076 .IX Item "get_c_backtrace_dump"
5077 Returns a SV containing a dump of \f(CW\*(C`depth\*(C'\fR frames of the call stack, skipping
5078 the \f(CW\*(C`skip\*(C'\fR innermost ones. \f(CW\*(C`depth\*(C'\fR of 20 is usually enough.
5079 .Sp
5080 The appended output looks like:
5081 .Sp
5082 .Vb 4
5083 \& ...
5084 \& 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl
5085 \& 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl
5086 \& ...
5087 .Ve
5088 .Sp
5089 The fields are tab-separated. The first column is the depth (zero
5090 being the innermost non-skipped frame). In the hex:offset, the hex is
5091 where the program counter was in \f(CW\*(C`S_parse_body\*(C'\fR, and the :offset (might
5092 be missing) tells how much inside the \f(CW\*(C`S_parse_body\*(C'\fR the program counter was.
5093 .Sp
5094 The \f(CW\*(C`util.c:1716\*(C'\fR is the source code file and line number.
5095 .Sp
5096 The \fI/usr/bin/perl\fR is obvious (hopefully).
5097 .Sp
5098 Unknowns are \f(CW"\-"\fR. Unknowns can happen unfortunately quite easily:
5099 if the platform doesn't support retrieving the information;
5100 if the binary is missing the debug information;
5101 if the optimizer has transformed the code by for example inlining.
5102 .RS 4
5103 .Sp
5104 .Vb 1
5105 \& SV * get_c_backtrace_dump(int max_depth, int skip)
5106 .Ve
5107 .RE
5108 .RS 4
5109 .RE
5110 .ie n .IP """gv_dump""" 4
5111 .el .IP \f(CWgv_dump\fR 4
5112 .IX Xref "gv_dump"
5113 .IX Item "gv_dump"
5114 Dump the name and, if they differ, the effective name of the GV \f(CW\*(C`gv\*(C'\fR to
5115 \&\f(CW\*(C`STDERR\*(C'\fR.
5116 .RS 4
5117 .Sp
5118 .Vb 1
5119 \& void gv_dump(GV *gv)
5120 .Ve
5121 .RE
5122 .RS 4
5123 .RE
5124 .ie n .IP """HAS_BACKTRACE""" 4
5125 .el .IP \f(CWHAS_BACKTRACE\fR 4
5126 .IX Xref "HAS_BACKTRACE"
5127 .IX Item "HAS_BACKTRACE"
5128 This symbol, if defined, indicates that the \f(CWbacktrace()\fR routine is
5129 available to get a stack trace. The \fIexecinfo.h\fR header must be
5130 included to use this routine.
5131 .ie n .IP """hv_dump""" 4
5132 .el .IP \f(CWhv_dump\fR 4
5133 .IX Xref "hv_dump"
5134 .IX Item "hv_dump"
5135 Dumps the contents of an HV to the \f(CW\*(C`STDERR\*(C'\fR filehandle.
5136 Similar to using Devel::Peek on an hashref but does not
5137 expect an RV wrapper. Dumps contents to a depth of 3 levels
5138 deep.
5139 .RS 4
5140 .Sp
5141 .Vb 1
5142 \& void hv_dump(HV *hv)
5143 .Ve
5144 .RE
5145 .RS 4
5146 .RE
5147 .ie n .IP """magic_dump""" 4
5148 .el .IP \f(CWmagic_dump\fR 4
5149 .IX Xref "magic_dump"
5150 .IX Item "magic_dump"
5151 Dumps the contents of the MAGIC \f(CW\*(C`mg\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR.
5152 .RS 4
5153 .Sp
5154 .Vb 1
5155 \& void magic_dump(const MAGIC *mg)
5156 .Ve
5157 .RE
5158 .RS 4
5159 .RE
5160 .ie n .IP """op_class""" 4
5161 .el .IP \f(CWop_class\fR 4
5162 .IX Xref "op_class"
5163 .IX Item "op_class"
5164 Given an op, determine what type of struct it has been allocated as.
5165 Returns one of the OPclass enums, such as OPclass_LISTOP.
5166 .RS 4
5167 .Sp
5168 .Vb 1
5169 \& OPclass op_class(const OP *o)
5170 .Ve
5171 .RE
5172 .RS 4
5173 .RE
5174 .ie n .IP """op_dump""" 4
5175 .el .IP \f(CWop_dump\fR 4
5176 .IX Xref "op_dump"
5177 .IX Item "op_dump"
5178 Dumps the optree starting at OP \f(CW\*(C`o\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR.
5179 .RS 4
5180 .Sp
5181 .Vb 1
5182 \& void op_dump(const OP *o)
5183 .Ve
5184 .RE
5185 .RS 4
5186 .RE
5187 .ie n .IP """PL_op""" 4
5188 .el .IP \f(CWPL_op\fR 4
5189 .IX Item "PL_op"
5190 Described in perlhacktips.
5191 .ie n .IP """PL_runops""" 4
5192 .el .IP \f(CWPL_runops\fR 4
5193 .IX Item "PL_runops"
5194 Described in perlguts.
5195 .ie n .IP """PL_sv_serial""" 4
5196 .el .IP \f(CWPL_sv_serial\fR 4
5197 .IX Item "PL_sv_serial"
5198 Described in perlhacktips.
5199 .ie n .IP """pmop_dump""" 4
5200 .el .IP \f(CWpmop_dump\fR 4
5201 .IX Xref "pmop_dump"
5202 .IX Item "pmop_dump"
5203 Dump an OP that is related to Pattern Matching, such as \f(CW\*(C`s/foo/bar/\*(C'\fR; these require
5204 special handling.
5205 .RS 4
5206 .Sp
5207 .Vb 1
5208 \& void pmop_dump(PMOP *pm)
5209 .Ve
5210 .RE
5211 .RS 4
5212 .RE
5213 .ie n .IP """sv_dump""" 4
5214 .el .IP \f(CWsv_dump\fR 4
5215 .IX Xref "sv_dump"
5216 .IX Item "sv_dump"
5217 Dumps the contents of an SV to the \f(CW\*(C`STDERR\*(C'\fR filehandle.
5218 .Sp
5219 For an example of its output, see Devel::Peek. If
5220 the item is an SvROK it will dump items to a depth of 4,
5221 otherwise it will dump only the top level item, which
5222 means that it will not dump the contents of an AV * or
5223 HV *. For that use \f(CWav_dump()\fR or \f(CWhv_dump()\fR.
5224 .RS 4
5225 .Sp
5226 .Vb 1
5227 \& void sv_dump(SV *sv)
5228 .Ve
5229 .RE
5230 .RS 4
5231 .RE
5232 .ie n .IP """sv_dump_depth""" 4
5233 .el .IP \f(CWsv_dump_depth\fR 4
5234 .IX Xref "sv_dump_depth"
5235 .IX Item "sv_dump_depth"
5236 Dumps the contents of an SV to the \f(CW\*(C`STDERR\*(C'\fR filehandle
5237 to the depth requested. This function can be used on any
5238 SV derived type (GV, HV, AV) with an appropriate cast.
5239 This is a more flexible variant of \fBsv_dump()\fR. For example
5240 .Sp
5241 .Vb 2
5242 \& HV *hv = ...;
5243 \& sv_dump_depth((SV*)hv, 2);
5244 .Ve
5245 .Sp
5246 would dump the hv, its keys and values, but would not recurse
5247 into any RV values.
5248 .RS 4
5249 .Sp
5250 .Vb 1
5251 \& void sv_dump_depth(SV *sv, I32 depth)
5252 .Ve
5253 .RE
5254 .RS 4
5255 .RE
5256 .ie n .IP """vdeb""" 4
5257 .el .IP \f(CWvdeb\fR 4
5258 .IX Xref "vdeb"
5259 .IX Item "vdeb"
5260 This is like \f(CW"deb"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated argument list.
5261 .RS 4
5262 .Sp
5263 .Vb 1
5264 \& void vdeb(const char *pat, va_list *args)
5265 .Ve
5266 .RE
5267 .RS 4
5268 .RE
5269 .SH "Display functions"
5270 .IX Xref "PERL_PV_ESCAPE_ALL PERL_PV_ESCAPE_FIRSTCHAR PERL_PV_ESCAPE_NOBACKSLASH PERL_PV_ESCAPE_NOCLEAR PERL_PV_ESCAPE_NONASCII PERL_PV_ESCAPE_NON_WC PERL_PV_ESCAPE_QUOTE PERL_PV_ESCAPE_RE PERL_PV_ESCAPE_UNI PERL_PV_ESCAPE_UNI_DETECT PERL_PV_PRETTY_ELLIPSES PERL_PV_PRETTY_LTGT PERL_PV_PRETTY_QUOTE"
5271 .IX Header "Display functions"
5272 .ie n .IP """form""" 4
5273 .el .IP \f(CWform\fR 4
5274 .IX Item "form"
5275 .PD 0
5276 .ie n .IP """form_nocontext""" 4
5277 .el .IP \f(CWform_nocontext\fR 4
5278 .IX Xref "form form_nocontext"
5279 .IX Item "form_nocontext"
5280 .PD
5281 These take a sprintf-style format pattern and conventional
5282 (non-SV) arguments and return the formatted string.
5283 .Sp
5284 .Vb 1
5285 \& (char *) Perl_form(aTHX_ const char* pat, ...)
5286 .Ve
5287 .Sp
5288 They can be used any place a string (char *) is required:
5289 .Sp
5290 .Vb 1
5291 \& char * s = form_nocontext("%d.%d", major, minor);
5292 .Ve
5293 .Sp
5294 They each return a temporary that will be freed "soon", automatically by the
5295 system, at the same time that SVs operated on by \f(CW"sv_2mortal"\fR are freed.
5296 .Sp
5297 Use the result immediately, or copy to a stable place for longer retention.
5298 This is contrary to the incorrect previous documentation of these that claimed
5299 that the return was a single per-thread buffer. That was (and is) actually
5300 true only when these are called during global destruction.
5301 .Sp
5302 The two forms differ only in that \f(CW\*(C`form_nocontext\*(C'\fR does not take a thread
5303 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
5304 already have the thread context.
5305 .Sp
5306 \&\f(CW"vform"\fR is the same except the arguments are an encapsulated argument list.
5307 .Sp
5308 NOTE: \f(CW\*(C`form\*(C'\fR must be explicitly called as
5309 \&\f(CW\*(C`Perl_form\*(C'\fR
5310 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
5311 .RS 4
5312 .Sp
5313 .Vb 2
5314 \& char * Perl_form (pTHX_ const char *pat, ...)
5315 \& char * form_nocontext(const char *pat, ...)
5316 .Ve
5317 .RE
5318 .RS 4
5319 .RE
5320 .ie n .IP """mess""" 4
5321 .el .IP \f(CWmess\fR 4
5322 .IX Item "mess"
5323 .PD 0
5324 .ie n .IP """mess_nocontext""" 4
5325 .el .IP \f(CWmess_nocontext\fR 4
5326 .IX Xref "mess mess_nocontext"
5327 .IX Item "mess_nocontext"
5328 .PD
5329 These take a sprintf-style format pattern and argument list, which are used to
5330 generate a string message. If the message does not end with a newline, then it
5331 will be extended with some indication of the current location in the code, as
5332 described for \f(CW"mess_sv"\fR.
5333 .Sp
5334 Normally, the resulting message is returned in a new mortal SV.
5335 But during global destruction a single SV may be shared between uses of
5336 this function.
5337 .Sp
5338 The two forms differ only in that \f(CW\*(C`mess_nocontext\*(C'\fR does not take a thread
5339 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
5340 already have the thread context.
5341 .Sp
5342 NOTE: \f(CW\*(C`mess\*(C'\fR must be explicitly called as
5343 \&\f(CW\*(C`Perl_mess\*(C'\fR
5344 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
5345 .RS 4
5346 .Sp
5347 .Vb 2
5348 \& SV * Perl_mess (pTHX_ const char *pat, ...)
5349 \& SV * mess_nocontext(const char *pat, ...)
5350 .Ve
5351 .RE
5352 .RS 4
5353 .RE
5354 .ie n .IP """mess_sv""" 4
5355 .el .IP \f(CWmess_sv\fR 4
5356 .IX Xref "mess_sv"
5357 .IX Item "mess_sv"
5358 Expands a message, intended for the user, to include an indication of
5359 the current location in the code, if the message does not already appear
5360 to be complete.
5361 .Sp
5362 \&\f(CW\*(C`basemsg\*(C'\fR is the initial message or object. If it is a reference, it
5363 will be used as-is and will be the result of this function. Otherwise it
5364 is used as a string, and if it already ends with a newline, it is taken
5365 to be complete, and the result of this function will be the same string.
5366 If the message does not end with a newline, then a segment such as \f(CW\*(C`at
5367 foo.pl line 37\*(C'\fR will be appended, and possibly other clauses indicating
5368 the current state of execution. The resulting message will end with a
5369 dot and a newline.
5370 .Sp
5371 Normally, the resulting message is returned in a new mortal SV.
5372 During global destruction a single SV may be shared between uses of this
5373 function. If \f(CW\*(C`consume\*(C'\fR is true, then the function is permitted (but not
5374 required) to modify and return \f(CW\*(C`basemsg\*(C'\fR instead of allocating a new SV.
5375 .RS 4
5376 .Sp
5377 .Vb 1
5378 \& SV * mess_sv(SV *basemsg, bool consume)
5379 .Ve
5380 .RE
5381 .RS 4
5382 .RE
5383 .ie n .IP """pv_display""" 4
5384 .el .IP \f(CWpv_display\fR 4
5385 .IX Xref "pv_display"
5386 .IX Item "pv_display"
5387 Similar to
5388 .Sp
5389 .Vb 1
5390 \& pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
5391 .Ve
5392 .Sp
5393 except that an additional "\e0" will be appended to the string when
5394 len > cur and pv[cur] is "\e0".
5395 .Sp
5396 Note that the final string may be up to 7 chars longer than pvlim.
5397 .RS 4
5398 .Sp
5399 .Vb 2
5400 \& char * pv_display(SV *dsv, const char *pv, STRLEN cur,
5401 \& STRLEN len, STRLEN pvlim)
5402 .Ve
5403 .RE
5404 .RS 4
5405 .RE
5406 .ie n .IP """pv_escape""" 4
5407 .el .IP \f(CWpv_escape\fR 4
5408 .IX Xref "pv_escape"
5409 .IX Item "pv_escape"
5410 Escapes at most the first \f(CW\*(C`count\*(C'\fR chars of \f(CW\*(C`pv\*(C'\fR and puts the results into
5411 \&\f(CW\*(C`dsv\*(C'\fR such that the size of the escaped string will not exceed \f(CW\*(C`max\*(C'\fR chars
5412 and will not contain any incomplete escape sequences. The number of bytes
5413 escaped will be returned in the \f(CW\*(C`STRLEN *escaped\*(C'\fR parameter if it is not null.
5414 When the \f(CW\*(C`dsv\*(C'\fR parameter is null no escaping actually occurs, but the number
5415 of bytes that would be escaped were it not null will be calculated.
5416 .Sp
5417 If flags contains \f(CW\*(C`PERL_PV_ESCAPE_QUOTE\*(C'\fR then any double quotes in the string
5418 will also be escaped.
5419 .Sp
5420 Normally the SV will be cleared before the escaped string is prepared,
5421 but when \f(CW\*(C`PERL_PV_ESCAPE_NOCLEAR\*(C'\fR is set this will not occur.
5422 .Sp
5423 If \f(CW\*(C`PERL_PV_ESCAPE_UNI\*(C'\fR is set then the input string is treated as UTF\-8.
5424 If \f(CW\*(C`PERL_PV_ESCAPE_UNI_DETECT\*(C'\fR is set then the input string is scanned
5425 using \f(CWis_utf8_string()\fR to determine if it is UTF\-8.
5426 .Sp
5427 If \f(CW\*(C`PERL_PV_ESCAPE_ALL\*(C'\fR is set then all input chars will be output
5428 using \f(CW\*(C`\ex01F1\*(C'\fR style escapes, otherwise if \f(CW\*(C`PERL_PV_ESCAPE_NONASCII\*(C'\fR
5429 is set, only non-ASCII chars will be escaped using this style;
5430 otherwise, only chars above 255 will be so escaped; other non printable
5431 chars will use octal or common escaped patterns like \f(CW\*(C`\en\*(C'\fR. Otherwise,
5432 if \f(CW\*(C`PERL_PV_ESCAPE_NOBACKSLASH\*(C'\fR then all chars below 255 will be
5433 treated as printable and will be output as literals. The
5434 \&\f(CW\*(C`PERL_PV_ESCAPE_NON_WC\*(C'\fR modifies the previous rules to cause word
5435 chars, unicode or otherwise, to be output as literals, note this uses
5436 the *unicode* rules for deciding on word characters.
5437 .Sp
5438 If \f(CW\*(C`PERL_PV_ESCAPE_FIRSTCHAR\*(C'\fR is set then only the first char of the
5439 string will be escaped, regardless of max. If the output is to be in
5440 hex, then it will be returned as a plain hex sequence. Thus the output
5441 will either be a single char, an octal escape sequence, a special escape
5442 like \f(CW\*(C`\en\*(C'\fR or a hex value.
5443 .Sp
5444 If \f(CW\*(C`PERL_PV_ESCAPE_RE\*(C'\fR is set then the escape char used will be a
5445 \&\f(CW"%"\fR and not a \f(CW"\e\e"\fR. This is because regexes very often contain
5446 backslashed sequences, whereas \f(CW"%"\fR is not a particularly common
5447 character in patterns.
5448 .Sp
5449 Returns a pointer to the escaped text as held by \f(CW\*(C`dsv\*(C'\fR.
5450 .RS 4
5451 .Sp
5452 .Vb 3
5453 \& char * pv_escape(SV *dsv, char const * const str,
5454 \& const STRLEN count, STRLEN max,
5455 \& STRLEN * const escaped, U32 flags)
5456 .Ve
5457 .RE
5458 .RS 4
5459 .RE
5460 .ie n .IP """pv_pretty""" 4
5461 .el .IP \f(CWpv_pretty\fR 4
5462 .IX Xref "pv_pretty"
5463 .IX Item "pv_pretty"
5464 Converts a string into something presentable, handling escaping via
5465 \&\f(CWpv_escape()\fR and supporting quoting and ellipses.
5466 .Sp
5467 If the \f(CW\*(C`PERL_PV_PRETTY_QUOTE\*(C'\fR flag is set then the result will be
5468 double quoted with any double quotes in the string escaped. Otherwise
5469 if the \f(CW\*(C`PERL_PV_PRETTY_LTGT\*(C'\fR flag is set then the result be wrapped in
5470 angle brackets.
5471 .Sp
5472 If the \f(CW\*(C`PERL_PV_PRETTY_ELLIPSES\*(C'\fR flag is set and not all characters in
5473 string were output then an ellipsis \f(CW\*(C`...\*(C'\fR will be appended to the
5474 string. Note that this happens AFTER it has been quoted.
5475 .Sp
5476 If \f(CW\*(C`start_color\*(C'\fR is non-null then it will be inserted after the opening
5477 quote (if there is one) but before the escaped text. If \f(CW\*(C`end_color\*(C'\fR
5478 is non-null then it will be inserted after the escaped text but before
5479 any quotes or ellipses.
5480 .Sp
5481 Returns a pointer to the prettified text as held by \f(CW\*(C`dsv\*(C'\fR.
5482 .RS 4
5483 .Sp
5484 .Vb 4
5485 \& char * pv_pretty(SV *dsv, char const * const str,
5486 \& const STRLEN count, const STRLEN max,
5487 \& char const * const start_color,
5488 \& char const * const end_color, const U32 flags)
5489 .Ve
5490 .RE
5491 .RS 4
5492 .RE
5493 .ie n .IP """vform""" 4
5494 .el .IP \f(CWvform\fR 4
5495 .IX Xref "vform"
5496 .IX Item "vform"
5497 Like \f(CW"form"\fR except the arguments are an encapsulated argument list.
5498 .RS 4
5499 .Sp
5500 .Vb 1
5501 \& char * vform(const char *pat, va_list *args)
5502 .Ve
5503 .RE
5504 .RS 4
5505 .RE
5506 .ie n .IP """vmess""" 4
5507 .el .IP \f(CWvmess\fR 4
5508 .IX Xref "vmess"
5509 .IX Item "vmess"
5510 \&\f(CW\*(C`pat\*(C'\fR and \f(CW\*(C`args\*(C'\fR are a sprintf-style format pattern and encapsulated
5511 argument list, respectively. These are used to generate a string message. If
5512 the
5513 message does not end with a newline, then it will be extended with
5514 some indication of the current location in the code, as described for
5515 "mess_sv".
5516 .Sp
5517 Normally, the resulting message is returned in a new mortal SV.
5518 During global destruction a single SV may be shared between uses of
5519 this function.
5520 .RS 4
5521 .Sp
5522 .Vb 1
5523 \& SV * vmess(const char *pat, va_list *args)
5524 .Ve
5525 .RE
5526 .RS 4
5527 .RE
5528 .SH "Embedding, Threads, and Interpreter Cloning"
5529 .IX Xref "CV_NAME_NOTQUAL PADNAMEf_OUTER PERL_EXIT_ABORT PERL_EXIT_DESTRUCT_END PERL_EXIT_EXPECTED PERL_EXIT_WARN PERL_LOADMOD_DENY PERL_LOADMOD_IMPORT_OPS PERL_LOADMOD_NOIMPORT"
5530 .IX Header "Embedding, Threads, and Interpreter Cloning"
5531 .ie n .IP """call_atexit""" 4
5532 .el .IP \f(CWcall_atexit\fR 4
5533 .IX Xref "call_atexit"
5534 .IX Item "call_atexit"
5535 Add a function \f(CW\*(C`fn\*(C'\fR to the list of functions to be called at global
5536 destruction. \f(CW\*(C`ptr\*(C'\fR will be passed as an argument to \f(CW\*(C`fn\*(C'\fR; it can point to a
5537 \&\f(CW\*(C`struct\*(C'\fR so that you can pass anything you want.
5538 .Sp
5539 Note that under threads, \f(CW\*(C`fn\*(C'\fR may run multiple times. This is because the
5540 list is executed each time the current or any descendent thread terminates.
5541 .RS 4
5542 .Sp
5543 .Vb 1
5544 \& void call_atexit(ATEXIT_t fn, void *ptr)
5545 .Ve
5546 .RE
5547 .RS 4
5548 .RE
5549 .ie n .IP """cv_clone""" 4
5550 .el .IP \f(CWcv_clone\fR 4
5551 .IX Xref "cv_clone"
5552 .IX Item "cv_clone"
5553 Clone a CV, making a lexical closure. \f(CW\*(C`proto\*(C'\fR supplies the prototype
5554 of the function: its code, pad structure, and other attributes.
5555 The prototype is combined with a capture of outer lexicals to which the
5556 code refers, which are taken from the currently-executing instance of
5557 the immediately surrounding code.
5558 .RS 4
5559 .Sp
5560 .Vb 1
5561 \& CV * cv_clone(CV *proto)
5562 .Ve
5563 .RE
5564 .RS 4
5565 .RE
5566 .ie n .IP """cv_name""" 4
5567 .el .IP \f(CWcv_name\fR 4
5568 .IX Xref "cv_name"
5569 .IX Item "cv_name"
5570 Returns an SV containing the name of the CV, mainly for use in error
5571 reporting. The CV may actually be a GV instead, in which case the returned
5572 SV holds the GV's name. Anything other than a GV or CV is treated as a
5573 string already holding the sub name, but this could change in the future.
5574 .Sp
5575 An SV may be passed as a second argument. If so, the name will be assigned
5576 to it and it will be returned. Otherwise the returned SV will be a new
5577 mortal.
5578 .Sp
5579 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`CV_NAME_NOTQUAL\*(C'\fR bit set, then the package name will not be
5580 included. If the first argument is neither a CV nor a GV, this flag is
5581 ignored (subject to change).
5582 .RS 4
5583 .Sp
5584 .Vb 1
5585 \& SV * cv_name(CV *cv, SV *sv, U32 flags)
5586 .Ve
5587 .RE
5588 .RS 4
5589 .RE
5590 .ie n .IP """cv_undef""" 4
5591 .el .IP \f(CWcv_undef\fR 4
5592 .IX Xref "cv_undef"
5593 .IX Item "cv_undef"
5594 Clear out all the active components of a CV. This can happen either
5595 by an explicit \f(CW\*(C`undef &foo\*(C'\fR, or by the reference count going to zero.
5596 In the former case, we keep the \f(CW\*(C`CvOUTSIDE\*(C'\fR pointer, so that any anonymous
5597 children can still follow the full lexical scope chain.
5598 .RS 4
5599 .Sp
5600 .Vb 1
5601 \& void cv_undef(CV *cv)
5602 .Ve
5603 .RE
5604 .RS 4
5605 .RE
5606 .ie n .IP """find_rundefsv""" 4
5607 .el .IP \f(CWfind_rundefsv\fR 4
5608 .IX Xref "find_rundefsv"
5609 .IX Item "find_rundefsv"
5610 Returns the global variable \f(CW$_\fR.
5611 .RS 4
5612 .Sp
5613 .Vb 1
5614 \& SV * find_rundefsv()
5615 .Ve
5616 .RE
5617 .RS 4
5618 .RE
5619 .ie n .IP """get_op_descs""" 4
5620 .el .IP \f(CWget_op_descs\fR 4
5621 .IX Xref "get_op_descs"
5622 .IX Item "get_op_descs"
5623 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`get_op_descs\*(C'\fR
5624 from a future release of Perl. Do not use it for
5625 new code; remove it from existing code.
5626 .Sp
5627 Return a pointer to the array of all the descriptions of the various OPs
5628 Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_desc[opcode]\*(C'\fR returns a
5629 pointer to a C language string giving its description.
5630 .RS 4
5631 .Sp
5632 .Vb 1
5633 \& char ** get_op_descs()
5634 .Ve
5635 .RE
5636 .RS 4
5637 .RE
5638 .ie n .IP """get_op_names""" 4
5639 .el .IP \f(CWget_op_names\fR 4
5640 .IX Xref "get_op_names"
5641 .IX Item "get_op_names"
5642 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`get_op_names\*(C'\fR
5643 from a future release of Perl. Do not use it for
5644 new code; remove it from existing code.
5645 .Sp
5646 Return a pointer to the array of all the names of the various OPs
5647 Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_name[opcode]\*(C'\fR returns a
5648 pointer to a C language string giving its name.
5649 .RS 4
5650 .Sp
5651 .Vb 1
5652 \& char ** get_op_names()
5653 .Ve
5654 .RE
5655 .RS 4
5656 .RE
5657 .ie n .IP """HAS_SKIP_LOCALE_INIT""" 4
5658 .el .IP \f(CWHAS_SKIP_LOCALE_INIT\fR 4
5659 .IX Item "HAS_SKIP_LOCALE_INIT"
5660 Described in perlembed.
5661 .ie n .IP """intro_my""" 4
5662 .el .IP \f(CWintro_my\fR 4
5663 .IX Xref "intro_my"
5664 .IX Item "intro_my"
5665 "Introduce" \f(CW\*(C`my\*(C'\fR variables to visible status. This is called during parsing
5666 at the end of each statement to make lexical variables visible to subsequent
5667 statements.
5668 .RS 4
5669 .Sp
5670 .Vb 1
5671 \& U32 intro_my()
5672 .Ve
5673 .RE
5674 .RS 4
5675 .RE
5676 .ie n .IP """load_module""" 4
5677 .el .IP \f(CWload_module\fR 4
5678 .IX Item "load_module"
5679 .PD 0
5680 .ie n .IP """load_module_nocontext""" 4
5681 .el .IP \f(CWload_module_nocontext\fR 4
5682 .IX Xref "load_module load_module_nocontext"
5683 .IX Item "load_module_nocontext"
5684 .PD
5685 These load the module whose name is pointed to by the string part of \f(CW\*(C`name\*(C'\fR.
5686 Note that the actual module name, not its filename, should be given.
5687 Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if specified and not NULL,
5688 provides version semantics similar to \f(CW\*(C`use Foo::Bar VERSION\*(C'\fR. The optional
5689 trailing arguments can be used to specify arguments to the module's \f(CWimport()\fR
5690 method, similar to \f(CW\*(C`use Foo::Bar VERSION LIST\*(C'\fR; their precise handling depends
5691 on the flags. The flags argument is a bitwise-ORed collection of any of
5692 \&\f(CW\*(C`PERL_LOADMOD_DENY\*(C'\fR, \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR, or \f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR
5693 (or 0 for no flags).
5694 .Sp
5695 If \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR is set, the module is loaded as if with an empty
5696 import list, as in \f(CW\*(C`use Foo::Bar ()\*(C'\fR; this is the only circumstance in which
5697 the trailing optional arguments may be omitted entirely. Otherwise, if
5698 \&\f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is set, the trailing arguments must consist of
5699 exactly one \f(CW\*(C`OP*\*(C'\fR, containing the op tree that produces the relevant import
5700 arguments. Otherwise, the trailing arguments must all be \f(CW\*(C`SV*\*(C'\fR values that
5701 will be used as import arguments; and the list must be terminated with \f(CW\*(C`(SV*)
5702 NULL\*(C'\fR. If neither \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR nor \f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is
5703 set, the trailing \f(CW\*(C`NULL\*(C'\fR pointer is needed even if no import arguments are
5704 desired. The reference count for each specified \f(CW\*(C`SV*\*(C'\fR argument is
5705 decremented. In addition, the \f(CW\*(C`name\*(C'\fR argument is modified.
5706 .Sp
5707 If \f(CW\*(C`PERL_LOADMOD_DENY\*(C'\fR is set, the module is loaded as if with \f(CW\*(C`no\*(C'\fR rather
5708 than \f(CW\*(C`use\*(C'\fR.
5709 .Sp
5710 \&\f(CW\*(C`load_module\*(C'\fR and \f(CW\*(C`load_module_nocontext\*(C'\fR have the same apparent signature,
5711 but the former hides the fact that it is accessing a thread context parameter.
5712 So use the latter when you get a compilation error about \f(CW\*(C`pTHX\*(C'\fR.
5713 .RS 4
5714 .Sp
5715 .Vb 2
5716 \& void load_module (U32 flags, SV *name, SV *ver, ...)
5717 \& void load_module_nocontext(U32 flags, SV *name, SV *ver, ...)
5718 .Ve
5719 .RE
5720 .RS 4
5721 .RE
5722 .ie n .IP """my_exit""" 4
5723 .el .IP \f(CWmy_exit\fR 4
5724 .IX Xref "my_exit"
5725 .IX Item "my_exit"
5726 A wrapper for the C library \fBexit\fR\|(3), honoring what "PL_exit_flags" in perlapi
5727 say to do.
5728 .RS 4
5729 .Sp
5730 .Vb 1
5731 \& void my_exit(U32 status)
5732 .Ve
5733 .RE
5734 .RS 4
5735 .RE
5736 .ie n .IP """my_failure_exit""" 4
5737 .el .IP \f(CWmy_failure_exit\fR 4
5738 .IX Xref "my_failure_exit"
5739 .IX Item "my_failure_exit"
5740 Exit the running Perl process with an error.
5741 .Sp
5742 On non-VMS platforms, this is essentially equivalent to "\f(CW\*(C`my_exit\*(C'\fR", using
5743 \&\f(CW\*(C`errno\*(C'\fR, but forces an en error code of 255 if \f(CW\*(C`errno\*(C'\fR is 0.
5744 .Sp
5745 On VMS, it takes care to set the appropriate severity bits in the exit status.
5746 .RS 4
5747 .Sp
5748 .Vb 1
5749 \& void my_failure_exit()
5750 .Ve
5751 .RE
5752 .RS 4
5753 .RE
5754 .ie n .IP """my_strlcat""" 4
5755 .el .IP \f(CWmy_strlcat\fR 4
5756 .IX Xref "my_strlcat"
5757 .IX Item "my_strlcat"
5758 The C library \f(CW\*(C`strlcat\*(C'\fR if available, or a Perl implementation of it.
5759 This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings.
5760 .Sp
5761 \&\f(CWmy_strlcat()\fR appends string \f(CW\*(C`src\*(C'\fR to the end of \f(CW\*(C`dst\*(C'\fR. It will append at
5762 most \f(CW\*(C`size\ \-\ strlen(dst)\ \-\ 1\*(C'\fR bytes. It will then \f(CW\*(C`NUL\*(C'\fR\-terminate,
5763 unless \f(CW\*(C`size\*(C'\fR is 0 or the original \f(CW\*(C`dst\*(C'\fR string was longer than \f(CW\*(C`size\*(C'\fR (in
5764 practice this should not happen as it means that either \f(CW\*(C`size\*(C'\fR is incorrect or
5765 that \f(CW\*(C`dst\*(C'\fR is not a proper \f(CW\*(C`NUL\*(C'\fR\-terminated string).
5766 .Sp
5767 Note that \f(CW\*(C`size\*(C'\fR is the full size of the destination buffer and
5768 the result is guaranteed to be \f(CW\*(C`NUL\*(C'\fR\-terminated if there is room. Note that
5769 room for the \f(CW\*(C`NUL\*(C'\fR should be included in \f(CW\*(C`size\*(C'\fR.
5770 .Sp
5771 The return value is the total length that \f(CW\*(C`dst\*(C'\fR would have if \f(CW\*(C`size\*(C'\fR is
5772 sufficiently large. Thus it is the initial length of \f(CW\*(C`dst\*(C'\fR plus the length of
5773 \&\f(CW\*(C`src\*(C'\fR. If \f(CW\*(C`size\*(C'\fR is smaller than the return, the excess was not appended.
5774 .RS 4
5775 .Sp
5776 .Vb 1
5777 \& Size_t my_strlcat(char *dst, const char *src, Size_t size)
5778 .Ve
5779 .RE
5780 .RS 4
5781 .RE
5782 .ie n .IP """my_strlcpy""" 4
5783 .el .IP \f(CWmy_strlcpy\fR 4
5784 .IX Xref "my_strlcpy"
5785 .IX Item "my_strlcpy"
5786 The C library \f(CW\*(C`strlcpy\*(C'\fR if available, or a Perl implementation of it.
5787 This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings.
5788 .Sp
5789 \&\f(CWmy_strlcpy()\fR copies up to \f(CW\*(C`size\ \-\ 1\*(C'\fR bytes from the string \f(CW\*(C`src\*(C'\fR
5790 to \f(CW\*(C`dst\*(C'\fR, \f(CW\*(C`NUL\*(C'\fR\-terminating the result if \f(CW\*(C`size\*(C'\fR is not 0.
5791 .Sp
5792 The return value is the total length \f(CW\*(C`src\*(C'\fR would be if the copy completely
5793 succeeded. If it is larger than \f(CW\*(C`size\*(C'\fR, the excess was not copied.
5794 .RS 4
5795 .Sp
5796 .Vb 1
5797 \& Size_t my_strlcpy(char *dst, const char *src, Size_t size)
5798 .Ve
5799 .RE
5800 .RS 4
5801 .RE
5802 .ie n .IP """newPADNAMELIST""" 4
5803 .el .IP \f(CWnewPADNAMELIST\fR 4
5804 .IX Xref "newPADNAMELIST"
5805 .IX Item "newPADNAMELIST"
5806 NOTE: \f(CW\*(C`newPADNAMELIST\*(C'\fR is \fBexperimental\fR and may change or be
5807 removed without notice.
5808 .Sp
5809 Creates a new pad name list. \f(CW\*(C`max\*(C'\fR is the highest index for which space
5810 is allocated.
5811 .RS 4
5812 .Sp
5813 .Vb 1
5814 \& PADNAMELIST * newPADNAMELIST(size_t max)
5815 .Ve
5816 .RE
5817 .RS 4
5818 .RE
5819 .ie n .IP """newPADNAMEouter""" 4
5820 .el .IP \f(CWnewPADNAMEouter\fR 4
5821 .IX Xref "newPADNAMEouter"
5822 .IX Item "newPADNAMEouter"
5823 NOTE: \f(CW\*(C`newPADNAMEouter\*(C'\fR is \fBexperimental\fR and may change or be
5824 removed without notice.
5825 .Sp
5826 Constructs and returns a new pad name. Only use this function for names
5827 that refer to outer lexicals. (See also "newPADNAMEpvn".) \f(CW\*(C`outer\*(C'\fR is
5828 the outer pad name that this one mirrors. The returned pad name has the
5829 \&\f(CW\*(C`PADNAMEf_OUTER\*(C'\fR flag already set.
5830 .RS 4
5831 .Sp
5832 .Vb 1
5833 \& PADNAME * newPADNAMEouter(PADNAME *outer)
5834 .Ve
5835 .RE
5836 .RS 4
5837 .RE
5838 .ie n .IP """newPADNAMEpvn""" 4
5839 .el .IP \f(CWnewPADNAMEpvn\fR 4
5840 .IX Xref "newPADNAMEpvn"
5841 .IX Item "newPADNAMEpvn"
5842 NOTE: \f(CW\*(C`newPADNAMEpvn\*(C'\fR is \fBexperimental\fR and may change or be
5843 removed without notice.
5844 .Sp
5845 Constructs and returns a new pad name. \f(CW\*(C`s\*(C'\fR must be a UTF\-8 string. Do not
5846 use this for pad names that point to outer lexicals. See
5847 \&\f(CW"newPADNAMEouter"\fR.
5848 .RS 4
5849 .Sp
5850 .Vb 1
5851 \& PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
5852 .Ve
5853 .RE
5854 .RS 4
5855 .RE
5856 .ie n .IP """nothreadhook""" 4
5857 .el .IP \f(CWnothreadhook\fR 4
5858 .IX Xref "nothreadhook"
5859 .IX Item "nothreadhook"
5860 Stub that provides thread hook for perl_destruct when there are
5861 no threads.
5862 .RS 4
5863 .Sp
5864 .Vb 1
5865 \& int nothreadhook()
5866 .Ve
5867 .RE
5868 .RS 4
5869 .RE
5870 .ie n .IP """pad_add_anon""" 4
5871 .el .IP \f(CWpad_add_anon\fR 4
5872 .IX Xref "pad_add_anon"
5873 .IX Item "pad_add_anon"
5874 Allocates a place in the currently-compiling pad (via "pad_alloc")
5875 for an anonymous function that is lexically scoped inside the
5876 currently-compiling function.
5877 The function \f(CW\*(C`func\*(C'\fR is linked into the pad, and its \f(CW\*(C`CvOUTSIDE\*(C'\fR link
5878 to the outer scope is weakened to avoid a reference loop.
5879 .Sp
5880 One reference count is stolen, so you may need to do \f(CWSvREFCNT_inc(func)\fR.
5881 .Sp
5882 \&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the
5883 pad entry is to support. This doesn't affect operational semantics,
5884 but is used for debugging.
5885 .RS 4
5886 .Sp
5887 .Vb 1
5888 \& PADOFFSET pad_add_anon(CV *func, I32 optype)
5889 .Ve
5890 .RE
5891 .RS 4
5892 .RE
5893 .ie n .IP """pad_add_name_pv""" 4
5894 .el .IP \f(CWpad_add_name_pv\fR 4
5895 .IX Xref "pad_add_name_pv"
5896 .IX Item "pad_add_name_pv"
5897 Exactly like "pad_add_name_pvn", but takes a nul-terminated string
5898 instead of a string/length pair.
5899 .RS 4
5900 .Sp
5901 .Vb 2
5902 \& PADOFFSET pad_add_name_pv(const char *name, const U32 flags,
5903 \& HV *typestash, HV *ourstash)
5904 .Ve
5905 .RE
5906 .RS 4
5907 .RE
5908 .ie n .IP """pad_add_name_pvn""" 4
5909 .el .IP \f(CWpad_add_name_pvn\fR 4
5910 .IX Xref "pad_add_name_pvn"
5911 .IX Item "pad_add_name_pvn"
5912 Allocates a place in the currently-compiling pad for a named lexical
5913 variable. Stores the name and other metadata in the name part of the
5914 pad, and makes preparations to manage the variable's lexical scoping.
5915 Returns the offset of the allocated pad slot.
5916 .Sp
5917 \&\f(CW\*(C`namepv\*(C'\fR/\f(CW\*(C`namelen\*(C'\fR specify the variable's name in UTF\-8, including
5918 leading sigil.
5919 If \f(CW\*(C`typestash\*(C'\fR is non-null, the name is for a typed lexical, and this
5920 identifies the type. If \f(CW\*(C`ourstash\*(C'\fR is non-null, it's a lexical reference
5921 to a package variable, and this identifies the package. The following
5922 flags can be OR'ed together:
5923 .Sp
5924 .Vb 4
5925 \& padadd_OUR redundantly specifies if it\*(Aqs a package var
5926 \& padadd_STATE variable will retain value persistently
5927 \& padadd_NO_DUP_CHECK skip check for lexical shadowing
5928 \& padadd_FIELD specifies that the lexical is a field for a class
5929 .Ve
5930 .RS 4
5931 .Sp
5932 .Vb 3
5933 \& PADOFFSET pad_add_name_pvn(const char *namepv, STRLEN namelen,
5934 \& U32 flags, HV *typestash,
5935 \& HV *ourstash)
5936 .Ve
5937 .RE
5938 .RS 4
5939 .RE
5940 .ie n .IP """pad_add_name_sv""" 4
5941 .el .IP \f(CWpad_add_name_sv\fR 4
5942 .IX Xref "pad_add_name_sv"
5943 .IX Item "pad_add_name_sv"
5944 Exactly like "pad_add_name_pvn", but takes the name string in the form
5945 of an SV instead of a string/length pair.
5946 .RS 4
5947 .Sp
5948 .Vb 2
5949 \& PADOFFSET pad_add_name_sv(SV *name, U32 flags, HV *typestash,
5950 \& HV *ourstash)
5951 .Ve
5952 .RE
5953 .RS 4
5954 .RE
5955 .ie n .IP """pad_alloc""" 4
5956 .el .IP \f(CWpad_alloc\fR 4
5957 .IX Xref "pad_alloc"
5958 .IX Item "pad_alloc"
5959 NOTE: \f(CW\*(C`pad_alloc\*(C'\fR is \fBexperimental\fR and may change or be
5960 removed without notice.
5961 .Sp
5962 Allocates a place in the currently-compiling pad,
5963 returning the offset of the allocated pad slot.
5964 No name is initially attached to the pad slot.
5965 \&\f(CW\*(C`tmptype\*(C'\fR is a set of flags indicating the kind of pad entry required,
5966 which will be set in the value SV for the allocated pad entry:
5967 .Sp
5968 .Vb 3
5969 \& SVs_PADMY named lexical variable ("my", "our", "state")
5970 \& SVs_PADTMP unnamed temporary store
5971 \& SVf_READONLY constant shared between recursion levels
5972 .Ve
5973 .Sp
5974 \&\f(CW\*(C`SVf_READONLY\*(C'\fR has been supported here only since perl 5.20. To work with
5975 earlier versions as well, use \f(CW\*(C`SVf_READONLY|SVs_PADTMP\*(C'\fR. \f(CW\*(C`SVf_READONLY\*(C'\fR
5976 does not cause the SV in the pad slot to be marked read-only, but simply
5977 tells \f(CW\*(C`pad_alloc\*(C'\fR that it \fIwill\fR be made read-only (by the caller), or at
5978 least should be treated as such.
5979 .Sp
5980 \&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the
5981 pad entry is to support. This doesn't affect operational semantics,
5982 but is used for debugging.
5983 .RS 4
5984 .Sp
5985 .Vb 1
5986 \& PADOFFSET pad_alloc(I32 optype, U32 tmptype)
5987 .Ve
5988 .RE
5989 .RS 4
5990 .RE
5991 .ie n .IP """pad_findmy_pv""" 4
5992 .el .IP \f(CWpad_findmy_pv\fR 4
5993 .IX Xref "pad_findmy_pv"
5994 .IX Item "pad_findmy_pv"
5995 Exactly like "pad_findmy_pvn", but takes a nul-terminated string
5996 instead of a string/length pair.
5997 .RS 4
5998 .Sp
5999 .Vb 1
6000 \& PADOFFSET pad_findmy_pv(const char *name, U32 flags)
6001 .Ve
6002 .RE
6003 .RS 4
6004 .RE
6005 .ie n .IP """pad_findmy_pvn""" 4
6006 .el .IP \f(CWpad_findmy_pvn\fR 4
6007 .IX Xref "pad_findmy_pvn"
6008 .IX Item "pad_findmy_pvn"
6009 Given the name of a lexical variable, find its position in the
6010 currently-compiling pad.
6011 \&\f(CW\*(C`namepv\*(C'\fR/\f(CW\*(C`namelen\*(C'\fR specify the variable's name, including leading sigil.
6012 \&\f(CW\*(C`flags\*(C'\fR is reserved and must be zero.
6013 If it is not in the current pad but appears in the pad of any lexically
6014 enclosing scope, then a pseudo-entry for it is added in the current pad.
6015 Returns the offset in the current pad,
6016 or \f(CW\*(C`NOT_IN_PAD\*(C'\fR if no such lexical is in scope.
6017 .RS 4
6018 .Sp
6019 .Vb 2
6020 \& PADOFFSET pad_findmy_pvn(const char *namepv, STRLEN namelen,
6021 \& U32 flags)
6022 .Ve
6023 .RE
6024 .RS 4
6025 .RE
6026 .ie n .IP """pad_findmy_sv""" 4
6027 .el .IP \f(CWpad_findmy_sv\fR 4
6028 .IX Xref "pad_findmy_sv"
6029 .IX Item "pad_findmy_sv"
6030 Exactly like "pad_findmy_pvn", but takes the name string in the form
6031 of an SV instead of a string/length pair.
6032 .RS 4
6033 .Sp
6034 .Vb 1
6035 \& PADOFFSET pad_findmy_sv(SV *name, U32 flags)
6036 .Ve
6037 .RE
6038 .RS 4
6039 .RE
6040 .ie n .IP """padnamelist_fetch""" 4
6041 .el .IP \f(CWpadnamelist_fetch\fR 4
6042 .IX Xref "padnamelist_fetch"
6043 .IX Item "padnamelist_fetch"
6044 NOTE: \f(CW\*(C`padnamelist_fetch\*(C'\fR is \fBexperimental\fR and may change or be
6045 removed without notice.
6046 .Sp
6047 Fetches the pad name from the given index.
6048 .RS 4
6049 .Sp
6050 .Vb 1
6051 \& PADNAME * padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
6052 .Ve
6053 .RE
6054 .RS 4
6055 .RE
6056 .ie n .IP """padnamelist_store""" 4
6057 .el .IP \f(CWpadnamelist_store\fR 4
6058 .IX Xref "padnamelist_store"
6059 .IX Item "padnamelist_store"
6060 NOTE: \f(CW\*(C`padnamelist_store\*(C'\fR is \fBexperimental\fR and may change or be
6061 removed without notice.
6062 .Sp
6063 Stores the pad name (which may be null) at the given index, freeing any
6064 existing pad name in that slot.
6065 .RS 4
6066 .Sp
6067 .Vb 2
6068 \& PADNAME ** padnamelist_store(PADNAMELIST *pnl, SSize_t key,
6069 \& PADNAME *val)
6070 .Ve
6071 .RE
6072 .RS 4
6073 .RE
6074 .ie n .IP """pad_tidy""" 4
6075 .el .IP \f(CWpad_tidy\fR 4
6076 .IX Xref "pad_tidy"
6077 .IX Item "pad_tidy"
6078 NOTE: \f(CW\*(C`pad_tidy\*(C'\fR is \fBexperimental\fR and may change or be
6079 removed without notice.
6080 .Sp
6081 Tidy up a pad at the end of compilation of the code to which it belongs.
6082 Jobs performed here are: remove most stuff from the pads of anonsub
6083 prototypes; give it a \f(CW@_\fR; mark temporaries as such. \f(CW\*(C`type\*(C'\fR indicates
6084 the kind of subroutine:
6085 .Sp
6086 .Vb 3
6087 \& padtidy_SUB ordinary subroutine
6088 \& padtidy_SUBCLONE prototype for lexical closure
6089 \& padtidy_FORMAT format
6090 .Ve
6091 .RS 4
6092 .Sp
6093 .Vb 1
6094 \& void pad_tidy(padtidy_type type)
6095 .Ve
6096 .RE
6097 .RS 4
6098 .RE
6099 .ie n .IP """perl_alloc""" 4
6100 .el .IP \f(CWperl_alloc\fR 4
6101 .IX Xref "perl_alloc"
6102 .IX Item "perl_alloc"
6103 Allocates a new Perl interpreter. See perlembed.
6104 .RS 4
6105 .Sp
6106 .Vb 1
6107 \& PerlInterpreter * perl_alloc()
6108 .Ve
6109 .RE
6110 .RS 4
6111 .RE
6112 .ie n .IP """PERL_ASYNC_CHECK""" 4
6113 .el .IP \f(CWPERL_ASYNC_CHECK\fR 4
6114 .IX Item "PERL_ASYNC_CHECK"
6115 Described in perlinterp.
6116 .RS 4
6117 .Sp
6118 .Vb 1
6119 \& void PERL_ASYNC_CHECK()
6120 .Ve
6121 .RE
6122 .RS 4
6123 .RE
6124 .ie n .IP """perl_clone""" 4
6125 .el .IP \f(CWperl_clone\fR 4
6126 .IX Xref "perl_clone"
6127 .IX Item "perl_clone"
6128 Create and return a new interpreter by cloning the current one.
6129 .Sp
6130 \&\f(CW\*(C`perl_clone\*(C'\fR takes these flags as parameters:
6131 .Sp
6132 \&\f(CW\*(C`CLONEf_COPY_STACKS\*(C'\fR \- is used to, well, copy the stacks also,
6133 without it we only clone the data and zero the stacks,
6134 with it we copy the stacks and the new perl interpreter is
6135 ready to run at the exact same point as the previous one.
6136 The pseudo-fork code uses \f(CW\*(C`COPY_STACKS\*(C'\fR while the
6137 threads\->create doesn't.
6138 .Sp
6139 \&\f(CW\*(C`CLONEf_KEEP_PTR_TABLE\*(C'\fR \-
6140 \&\f(CW\*(C`perl_clone\*(C'\fR keeps a ptr_table with the pointer of the old
6141 variable as a key and the new variable as a value,
6142 this allows it to check if something has been cloned and not
6143 clone it again, but rather just use the value and increase the
6144 refcount.
6145 If \f(CW\*(C`KEEP_PTR_TABLE\*(C'\fR is not set then \f(CW\*(C`perl_clone\*(C'\fR will kill the ptr_table
6146 using the function \f(CW\*(C`ptr_table_free(PL_ptr_table);\ PL_ptr_table\ =\ NULL;\*(C'\fR.
6147 A reason to keep it around is if you want to dup some of your own
6148 variables which are outside the graph that perl scans.
6149 .Sp
6150 \&\f(CW\*(C`CLONEf_CLONE_HOST\*(C'\fR \-
6151 This is a win32 thing, it is ignored on unix, it tells perl's
6152 win32host code (which is c++) to clone itself, this is needed on
6153 win32 if you want to run two threads at the same time,
6154 if you just want to do some stuff in a separate perl interpreter
6155 and then throw it away and return to the original one,
6156 you don't need to do anything.
6157 .RS 4
6158 .Sp
6159 .Vb 2
6160 \& PerlInterpreter * perl_clone(PerlInterpreter *proto_perl,
6161 \& UV flags)
6162 .Ve
6163 .RE
6164 .RS 4
6165 .RE
6166 .ie n .IP """perl_construct""" 4
6167 .el .IP \f(CWperl_construct\fR 4
6168 .IX Xref "perl_construct"
6169 .IX Item "perl_construct"
6170 Initializes a new Perl interpreter. See perlembed.
6171 .RS 4
6172 .Sp
6173 .Vb 1
6174 \& void perl_construct(PerlInterpreter *my_perl)
6175 .Ve
6176 .RE
6177 .RS 4
6178 .RE
6179 .ie n .IP """perl_destruct""" 4
6180 .el .IP \f(CWperl_destruct\fR 4
6181 .IX Xref "perl_destruct"
6182 .IX Item "perl_destruct"
6183 Shuts down a Perl interpreter. See perlembed for a tutorial.
6184 .Sp
6185 \&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter. It must have been previously
6186 created through the use of "perl_alloc" and "perl_construct". It may
6187 have been initialised through "perl_parse", and may have been used
6188 through "perl_run" and other means. This function should be called for
6189 any Perl interpreter that has been constructed with "perl_construct",
6190 even if subsequent operations on it failed, for example if "perl_parse"
6191 returned a non-zero value.
6192 .Sp
6193 If the interpreter's \f(CW\*(C`PL_exit_flags\*(C'\fR word has the
6194 \&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function will execute code
6195 in \f(CW\*(C`END\*(C'\fR blocks before performing the rest of destruction. If it is
6196 desired to make any use of the interpreter between "perl_parse" and
6197 "perl_destruct" other than just calling "perl_run", then this flag
6198 should be set early on. This matters if "perl_run" will not be called,
6199 or if anything else will be done in addition to calling "perl_run".
6200 .Sp
6201 Returns a value be a suitable value to pass to the C library function
6202 \&\f(CW\*(C`exit\*(C'\fR (or to return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating
6203 the nature of the way the interpreter terminated. This takes into account
6204 any failure of "perl_parse" and any early exit from "perl_run".
6205 The exit code is of the type required by the host operating system,
6206 so because of differing exit code conventions it is not portable to
6207 interpret specific numeric values as having specific meanings.
6208 .RS 4
6209 .Sp
6210 .Vb 1
6211 \& int perl_destruct(PerlInterpreter *my_perl)
6212 .Ve
6213 .RE
6214 .RS 4
6215 .RE
6216 .ie n .IP """perl_free""" 4
6217 .el .IP \f(CWperl_free\fR 4
6218 .IX Xref "perl_free"
6219 .IX Item "perl_free"
6220 Releases a Perl interpreter. See perlembed.
6221 .RS 4
6222 .Sp
6223 .Vb 1
6224 \& void perl_free(PerlInterpreter *my_perl)
6225 .Ve
6226 .RE
6227 .RS 4
6228 .RE
6229 .ie n .IP """PERL_GET_CONTEXT""" 4
6230 .el .IP \f(CWPERL_GET_CONTEXT\fR 4
6231 .IX Item "PERL_GET_CONTEXT"
6232 Described in perlguts.
6233 .ie n .IP """PerlInterpreter""" 4
6234 .el .IP \f(CWPerlInterpreter\fR 4
6235 .IX Item "PerlInterpreter"
6236 Described in perlembed.
6237 .ie n .IP """perl_parse""" 4
6238 .el .IP \f(CWperl_parse\fR 4
6239 .IX Xref "perl_parse"
6240 .IX Item "perl_parse"
6241 Tells a Perl interpreter to parse a Perl script. This performs most
6242 of the initialisation of a Perl interpreter. See perlembed for
6243 a tutorial.
6244 .Sp
6245 \&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter that is to parse the script.
6246 It must have been previously created through the use of "perl_alloc"
6247 and "perl_construct". \f(CW\*(C`xsinit\*(C'\fR points to a callback function that
6248 will be called to set up the ability for this Perl interpreter to load
6249 XS extensions, or may be null to perform no such setup.
6250 .Sp
6251 \&\f(CW\*(C`argc\*(C'\fR and \f(CW\*(C`argv\*(C'\fR supply a set of command-line arguments to the Perl
6252 interpreter, as would normally be passed to the \f(CW\*(C`main\*(C'\fR function of
6253 a C program. \f(CW\*(C`argv[argc]\*(C'\fR must be null. These arguments are where
6254 the script to parse is specified, either by naming a script file or by
6255 providing a script in a \f(CW\*(C`\-e\*(C'\fR option.
6256 If \f(CW$0\fR will be written to in the Perl interpreter, then
6257 the argument strings must be in writable memory, and so mustn't just be
6258 string constants.
6259 .Sp
6260 \&\f(CW\*(C`env\*(C'\fR specifies a set of environment variables that will be used by
6261 this Perl interpreter. If non-null, it must point to a null-terminated
6262 array of environment strings. If null, the Perl interpreter will use
6263 the environment supplied by the \f(CW\*(C`environ\*(C'\fR global variable.
6264 .Sp
6265 This function initialises the interpreter, and parses and compiles the
6266 script specified by the command-line arguments. This includes executing
6267 code in \f(CW\*(C`BEGIN\*(C'\fR, \f(CW\*(C`UNITCHECK\*(C'\fR, and \f(CW\*(C`CHECK\*(C'\fR blocks. It does not execute
6268 \&\f(CW\*(C`INIT\*(C'\fR blocks or the main program.
6269 .Sp
6270 Returns an integer of slightly tricky interpretation. The correct
6271 use of the return value is as a truth value indicating whether there
6272 was a failure in initialisation. If zero is returned, this indicates
6273 that initialisation was successful, and it is safe to proceed to call
6274 "perl_run" and make other use of it. If a non-zero value is returned,
6275 this indicates some problem that means the interpreter wants to terminate.
6276 The interpreter should not be just abandoned upon such failure; the caller
6277 should proceed to shut the interpreter down cleanly with "perl_destruct"
6278 and free it with "perl_free".
6279 .Sp
6280 For historical reasons, the non-zero return value also attempts to
6281 be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to
6282 return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature
6283 of the way initialisation terminated. However, this isn't portable,
6284 due to differing exit code conventions. An attempt is made to return
6285 an exit code of the type required by the host operating system, but
6286 because it is constrained to be non-zero, it is not necessarily possible
6287 to indicate every type of exit. It is only reliable on Unix, where a
6288 zero exit code can be augmented with a set bit that will be ignored.
6289 In any case, this function is not the correct place to acquire an exit
6290 code: one should get that from "perl_destruct".
6291 .RS 4
6292 .Sp
6293 .Vb 2
6294 \& int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
6295 \& int argc, char **argv, char **env)
6296 .Ve
6297 .RE
6298 .RS 4
6299 .RE
6300 .ie n .IP """perl_run""" 4
6301 .el .IP \f(CWperl_run\fR 4
6302 .IX Xref "perl_run"
6303 .IX Item "perl_run"
6304 Tells a Perl interpreter to run its main program. See perlembed
6305 for a tutorial.
6306 .Sp
6307 \&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter. It must have been previously
6308 created through the use of "perl_alloc" and "perl_construct", and
6309 initialised through "perl_parse". This function should not be called
6310 if "perl_parse" returned a non-zero value, indicating a failure in
6311 initialisation or compilation.
6312 .Sp
6313 This function executes code in \f(CW\*(C`INIT\*(C'\fR blocks, and then executes the
6314 main program. The code to be executed is that established by the prior
6315 call to "perl_parse". If the interpreter's \f(CW\*(C`PL_exit_flags\*(C'\fR word
6316 does not have the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function
6317 will also execute code in \f(CW\*(C`END\*(C'\fR blocks. If it is desired to make any
6318 further use of the interpreter after calling this function, then \f(CW\*(C`END\*(C'\fR
6319 blocks should be postponed to "perl_destruct" time by setting that flag.
6320 .Sp
6321 Returns an integer of slightly tricky interpretation. The correct use
6322 of the return value is as a truth value indicating whether the program
6323 terminated non-locally. If zero is returned, this indicates that
6324 the program ran to completion, and it is safe to make other use of the
6325 interpreter (provided that the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag was set as
6326 described above). If a non-zero value is returned, this indicates that
6327 the interpreter wants to terminate early. The interpreter should not be
6328 just abandoned because of this desire to terminate; the caller should
6329 proceed to shut the interpreter down cleanly with "perl_destruct"
6330 and free it with "perl_free".
6331 .Sp
6332 For historical reasons, the non-zero return value also attempts to
6333 be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to
6334 return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature of
6335 the way the program terminated. However, this isn't portable, due to
6336 differing exit code conventions. An attempt is made to return an exit
6337 code of the type required by the host operating system, but because
6338 it is constrained to be non-zero, it is not necessarily possible to
6339 indicate every type of exit. It is only reliable on Unix, where a zero
6340 exit code can be augmented with a set bit that will be ignored. In any
6341 case, this function is not the correct place to acquire an exit code:
6342 one should get that from "perl_destruct".
6343 .RS 4
6344 .Sp
6345 .Vb 1
6346 \& int perl_run(PerlInterpreter *my_perl)
6347 .Ve
6348 .RE
6349 .RS 4
6350 .RE
6351 .ie n .IP """PERL_SET_CONTEXT""" 4
6352 .el .IP \f(CWPERL_SET_CONTEXT\fR 4
6353 .IX Item "PERL_SET_CONTEXT"
6354 Described in perlguts.
6355 .RS 4
6356 .Sp
6357 .Vb 1
6358 \& void PERL_SET_CONTEXT(PerlInterpreter* i)
6359 .Ve
6360 .RE
6361 .RS 4
6362 .RE
6363 .ie n .IP """PERL_SYS_INIT""" 4
6364 .el .IP \f(CWPERL_SYS_INIT\fR 4
6365 .IX Item "PERL_SYS_INIT"
6366 .PD 0
6367 .ie n .IP """PERL_SYS_INIT3""" 4
6368 .el .IP \f(CWPERL_SYS_INIT3\fR 4
6369 .IX Xref "PERL_SYS_INIT PERL_SYS_INIT3"
6370 .IX Item "PERL_SYS_INIT3"
6371 .PD
6372 These provide system-specific tune up of the C runtime environment necessary to
6373 run Perl interpreters. Only one should be used, and it should be called only
6374 once, before creating any Perl interpreters.
6375 .Sp
6376 They differ in that \f(CW\*(C`PERL_SYS_INIT3\*(C'\fR also initializes \f(CW\*(C`env\*(C'\fR.
6377 .RS 4
6378 .Sp
6379 .Vb 2
6380 \& void PERL_SYS_INIT (int *argc, char*** argv)
6381 \& void PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
6382 .Ve
6383 .RE
6384 .RS 4
6385 .RE
6386 .ie n .IP """PERL_SYS_TERM""" 4
6387 .el .IP \f(CWPERL_SYS_TERM\fR 4
6388 .IX Xref "PERL_SYS_TERM"
6389 .IX Item "PERL_SYS_TERM"
6390 Provides system-specific clean up of the C runtime environment after
6391 running Perl interpreters. This should be called only once, after
6392 freeing any remaining Perl interpreters.
6393 .RS 4
6394 .Sp
6395 .Vb 1
6396 \& void PERL_SYS_TERM()
6397 .Ve
6398 .RE
6399 .RS 4
6400 .RE
6401 .ie n .IP """PL_exit_flags""" 4
6402 .el .IP \f(CWPL_exit_flags\fR 4
6403 .IX Xref "PL_exit_flags"
6404 .IX Item "PL_exit_flags"
6405 Contains flags controlling perl's behaviour on \fBexit()\fR:
6406 .RS 4
6407 .IP \(bu 4
6408 \&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR
6409 .Sp
6410 If set, END blocks are executed when the interpreter is destroyed.
6411 This is normally set by perl itself after the interpreter is
6412 constructed.
6413 .IP \(bu 4
6414 \&\f(CW\*(C`PERL_EXIT_ABORT\*(C'\fR
6415 .Sp
6416 Call \f(CWabort()\fR on exit. This is used internally by perl itself to
6417 abort if exit is called while processing exit.
6418 .IP \(bu 4
6419 \&\f(CW\*(C`PERL_EXIT_WARN\*(C'\fR
6420 .Sp
6421 Warn on exit.
6422 .IP \(bu 4
6423 \&\f(CW\*(C`PERL_EXIT_EXPECTED\*(C'\fR
6424 .Sp
6425 Set by the "exit" in perlfunc operator.
6426 .RE
6427 .RS 4
6428 .Sp
6429 .Vb 1
6430 \& U8 PL_exit_flags
6431 .Ve
6432 .RE
6433 .RS 4
6434 .RE
6435 .ie n .IP """PL_origalen""" 4
6436 .el .IP \f(CWPL_origalen\fR 4
6437 .IX Item "PL_origalen"
6438 Described in perlembed.
6439 .ie n .IP """PL_perl_destruct_level""" 4
6440 .el .IP \f(CWPL_perl_destruct_level\fR 4
6441 .IX Xref "PL_perl_destruct_level"
6442 .IX Item "PL_perl_destruct_level"
6443 This value may be set when embedding for full cleanup.
6444 .Sp
6445 Possible values:
6446 .RS 4
6447 .IP \(bu 4
6448 0 \- none
6449 .IP \(bu 4
6450 1 \- full
6451 .IP \(bu 4
6452 2 or greater \- full with checks.
6453 .RE
6454 .RS 4
6455 .Sp
6456 If \f(CW$ENV{PERL_DESTRUCT_LEVEL}\fR is set to an integer greater than the
6457 value of \f(CW\*(C`PL_perl_destruct_level\*(C'\fR its value is used instead.
6458 .Sp
6459 On threaded perls, each thread has an independent copy of this variable;
6460 each initialized at creation time with the current value of the creating
6461 thread's copy.
6462 .Sp
6463 .Vb 1
6464 \& signed char PL_perl_destruct_level
6465 .Ve
6466 .RE
6467 .RS 4
6468 .RE
6469 .ie n .IP """ptr_table_fetch""" 4
6470 .el .IP \f(CWptr_table_fetch\fR 4
6471 .IX Xref "ptr_table_fetch"
6472 .IX Item "ptr_table_fetch"
6473 Look for \f(CW\*(C`sv\*(C'\fR in the pointer-mapping table \f(CW\*(C`tbl\*(C'\fR, returning its value, or
6474 NULL if not found.
6475 .RS 4
6476 .Sp
6477 .Vb 2
6478 \& void * ptr_table_fetch(PTR_TBL_t * const tbl,
6479 \& const void * const sv)
6480 .Ve
6481 .RE
6482 .RS 4
6483 .RE
6484 .ie n .IP """ptr_table_free""" 4
6485 .el .IP \f(CWptr_table_free\fR 4
6486 .IX Xref "ptr_table_free"
6487 .IX Item "ptr_table_free"
6488 Clear and free a ptr table
6489 .RS 4
6490 .Sp
6491 .Vb 1
6492 \& void ptr_table_free(PTR_TBL_t * const tbl)
6493 .Ve
6494 .RE
6495 .RS 4
6496 .RE
6497 .ie n .IP """ptr_table_new""" 4
6498 .el .IP \f(CWptr_table_new\fR 4
6499 .IX Xref "ptr_table_new"
6500 .IX Item "ptr_table_new"
6501 Create a new pointer-mapping table
6502 .RS 4
6503 .Sp
6504 .Vb 1
6505 \& PTR_TBL_t * ptr_table_new()
6506 .Ve
6507 .RE
6508 .RS 4
6509 .RE
6510 .ie n .IP """ptr_table_split""" 4
6511 .el .IP \f(CWptr_table_split\fR 4
6512 .IX Xref "ptr_table_split"
6513 .IX Item "ptr_table_split"
6514 Double the hash bucket size of an existing ptr table
6515 .RS 4
6516 .Sp
6517 .Vb 1
6518 \& void ptr_table_split(PTR_TBL_t * const tbl)
6519 .Ve
6520 .RE
6521 .RS 4
6522 .RE
6523 .ie n .IP """ptr_table_store""" 4
6524 .el .IP \f(CWptr_table_store\fR 4
6525 .IX Xref "ptr_table_store"
6526 .IX Item "ptr_table_store"
6527 Add a new entry to a pointer-mapping table \f(CW\*(C`tbl\*(C'\fR.
6528 In hash terms, \f(CW\*(C`oldsv\*(C'\fR is the key; Cnewsv> is the value.
6529 .Sp
6530 The names "old" and "new" are specific to the core's typical use of ptr_tables
6531 in thread cloning.
6532 .RS 4
6533 .Sp
6534 .Vb 3
6535 \& void ptr_table_store(PTR_TBL_t * const tbl,
6536 \& const void * const oldsv,
6537 \& void * const newsv)
6538 .Ve
6539 .RE
6540 .RS 4
6541 .RE
6542 .ie n .IP """require_pv""" 4
6543 .el .IP \f(CWrequire_pv\fR 4
6544 .IX Xref "require_pv"
6545 .IX Item "require_pv"
6546 Tells Perl to \f(CW\*(C`require\*(C'\fR the file named by the string argument. It is
6547 analogous to the Perl code \f(CW\*(C`eval "require \*(Aq$file\*(Aq"\*(C'\fR. It's even
6548 implemented that way; consider using load_module instead.
6549 .Sp
6550 NOTE: the \f(CWperl_require_pv()\fR form is \fBdeprecated\fR.
6551 .RS 4
6552 .Sp
6553 .Vb 1
6554 \& void require_pv(const char *pv)
6555 .Ve
6556 .RE
6557 .RS 4
6558 .RE
6559 .ie n .IP """vload_module""" 4
6560 .el .IP \f(CWvload_module\fR 4
6561 .IX Xref "vload_module"
6562 .IX Item "vload_module"
6563 Like \f(CW"load_module"\fR but the arguments are an encapsulated argument list.
6564 .RS 4
6565 .Sp
6566 .Vb 1
6567 \& void vload_module(U32 flags, SV *name, SV *ver, va_list *args)
6568 .Ve
6569 .RE
6570 .RS 4
6571 .RE
6572 .SH Errno
6573 .IX Header "Errno"
6574 .ie n .IP """sv_string_from_errnum""" 4
6575 .el .IP \f(CWsv_string_from_errnum\fR 4
6576 .IX Xref "sv_string_from_errnum"
6577 .IX Item "sv_string_from_errnum"
6578 Generates the message string describing an OS error and returns it as
6579 an SV. \f(CW\*(C`errnum\*(C'\fR must be a value that \f(CW\*(C`errno\*(C'\fR could take, identifying
6580 the type of error.
6581 .Sp
6582 If \f(CW\*(C`tgtsv\*(C'\fR is non-null then the string will be written into that SV
6583 (overwriting existing content) and it will be returned. If \f(CW\*(C`tgtsv\*(C'\fR
6584 is a null pointer then the string will be written into a new mortal SV
6585 which will be returned.
6586 .Sp
6587 The message will be taken from whatever locale would be used by \f(CW$!\fR,
6588 and will be encoded in the SV in whatever manner would be used by \f(CW$!\fR.
6589 The details of this process are subject to future change. Currently,
6590 the message is taken from the C locale by default (usually producing an
6591 English message), and from the currently selected locale when in the scope
6592 of the \f(CW\*(C`use locale\*(C'\fR pragma. A heuristic attempt is made to decode the
6593 message from the locale's character encoding, but it will only be decoded
6594 as either UTF\-8 or ISO\-8859\-1. It is always correctly decoded in a UTF\-8
6595 locale, usually in an ISO\-8859\-1 locale, and never in any other locale.
6596 .Sp
6597 The SV is always returned containing an actual string, and with no other
6598 OK bits set. Unlike \f(CW$!\fR, a message is even yielded for \f(CW\*(C`errnum\*(C'\fR zero
6599 (meaning success), and if no useful message is available then a useless
6600 string (currently empty) is returned.
6601 .RS 4
6602 .Sp
6603 .Vb 1
6604 \& SV * sv_string_from_errnum(int errnum, SV *tgtsv)
6605 .Ve
6606 .RE
6607 .RS 4
6608 .RE
6609 .SH "Exception Handling (simple) Macros"
6610 .IX Header "Exception Handling (simple) Macros"
6611 .ie n .IP """dXCPT""" 4
6612 .el .IP \f(CWdXCPT\fR 4
6613 .IX Xref "dXCPT"
6614 .IX Item "dXCPT"
6615 Set up necessary local variables for exception handling.
6616 See "Exception Handling" in perlguts.
6617 .RS 4
6618 .Sp
6619 .Vb 1
6620 \& dXCPT;
6621 .Ve
6622 .RE
6623 .RS 4
6624 .RE
6625 .ie n .IP """JMPENV_JUMP""" 4
6626 .el .IP \f(CWJMPENV_JUMP\fR 4
6627 .IX Item "JMPENV_JUMP"
6628 Described in perlinterp.
6629 .RS 4
6630 .Sp
6631 .Vb 1
6632 \& void JMPENV_JUMP(int v)
6633 .Ve
6634 .RE
6635 .RS 4
6636 .RE
6637 .ie n .IP """JMPENV_PUSH""" 4
6638 .el .IP \f(CWJMPENV_PUSH\fR 4
6639 .IX Item "JMPENV_PUSH"
6640 Described in perlinterp.
6641 .RS 4
6642 .Sp
6643 .Vb 1
6644 \& void JMPENV_PUSH(int v)
6645 .Ve
6646 .RE
6647 .RS 4
6648 .RE
6649 .ie n .IP """PL_restartop""" 4
6650 .el .IP \f(CWPL_restartop\fR 4
6651 .IX Item "PL_restartop"
6652 Described in perlinterp.
6653 .ie n .IP """XCPT_CATCH""" 4
6654 .el .IP \f(CWXCPT_CATCH\fR 4
6655 .IX Xref "XCPT_CATCH"
6656 .IX Item "XCPT_CATCH"
6657 Introduces a catch block. See "Exception Handling" in perlguts.
6658 .ie n .IP """XCPT_RETHROW""" 4
6659 .el .IP \f(CWXCPT_RETHROW\fR 4
6660 .IX Xref "XCPT_RETHROW"
6661 .IX Item "XCPT_RETHROW"
6662 Rethrows a previously caught exception. See "Exception Handling" in perlguts.
6663 .RS 4
6664 .Sp
6665 .Vb 1
6666 \& XCPT_RETHROW;
6667 .Ve
6668 .RE
6669 .RS 4
6670 .RE
6671 .ie n .IP """XCPT_TRY_END""" 4
6672 .el .IP \f(CWXCPT_TRY_END\fR 4
6673 .IX Xref "XCPT_TRY_END"
6674 .IX Item "XCPT_TRY_END"
6675 Ends a try block. See "Exception Handling" in perlguts.
6676 .ie n .IP """XCPT_TRY_START""" 4
6677 .el .IP \f(CWXCPT_TRY_START\fR 4
6678 .IX Xref "XCPT_TRY_START"
6679 .IX Item "XCPT_TRY_START"
6680 Starts a try block. See "Exception Handling" in perlguts.
6681 .SH "Filesystem configuration values"
6682 .IX Header "Filesystem configuration values"
6683 Also see "List of capability HAS_foo symbols".
6684 .ie n .IP """DIRNAMLEN""" 4
6685 .el .IP \f(CWDIRNAMLEN\fR 4
6686 .IX Xref "DIRNAMLEN"
6687 .IX Item "DIRNAMLEN"
6688 This symbol, if defined, indicates to the C program that the length
6689 of directory entry names is provided by a \f(CW\*(C`d_namlen\*(C'\fR field. Otherwise
6690 you need to do \f(CWstrlen()\fR on the \f(CW\*(C`d_name\*(C'\fR field.
6691 .ie n .IP """DOSUID""" 4
6692 .el .IP \f(CWDOSUID\fR 4
6693 .IX Xref "DOSUID"
6694 .IX Item "DOSUID"
6695 This symbol, if defined, indicates that the C program should
6696 check the script that it is executing for setuid/setgid bits, and
6697 attempt to emulate setuid/setgid on systems that have disabled
6698 setuid #! scripts because the kernel can't do it securely.
6699 It is up to the package designer to make sure that this emulation
6700 is done securely. Among other things, it should do an fstat on
6701 the script it just opened to make sure it really is a setuid/setgid
6702 script, it should make sure the arguments passed correspond exactly
6703 to the argument on the #! line, and it should not trust any
6704 subprocesses to which it must pass the filename rather than the
6705 file descriptor of the script to be executed.
6706 .ie n .IP """EOF_NONBLOCK""" 4
6707 .el .IP \f(CWEOF_NONBLOCK\fR 4
6708 .IX Xref "EOF_NONBLOCK"
6709 .IX Item "EOF_NONBLOCK"
6710 This symbol, if defined, indicates to the C program that a \f(CWread()\fR on
6711 a non-blocking file descriptor will return 0 on \f(CW\*(C`EOF\*(C'\fR, and not the value
6712 held in \f(CW\*(C`RD_NODATA\*(C'\fR (\-1 usually, in that case!).
6713 .ie n .IP """FCNTL_CAN_LOCK""" 4
6714 .el .IP \f(CWFCNTL_CAN_LOCK\fR 4
6715 .IX Xref "FCNTL_CAN_LOCK"
6716 .IX Item "FCNTL_CAN_LOCK"
6717 This symbol, if defined, indicates that \f(CWfcntl()\fR can be used
6718 for file locking. Normally on Unix systems this is defined.
6719 It may be undefined on \f(CW\*(C`VMS\*(C'\fR.
6720 .ie n .IP """FFLUSH_ALL""" 4
6721 .el .IP \f(CWFFLUSH_ALL\fR 4
6722 .IX Xref "FFLUSH_ALL"
6723 .IX Item "FFLUSH_ALL"
6724 This symbol, if defined, tells that to flush
6725 all pending stdio output one must loop through all
6726 the stdio file handles stored in an array and fflush them.
6727 Note that if \f(CW\*(C`fflushNULL\*(C'\fR is defined, fflushall will not
6728 even be probed for and will be left undefined.
6729 .ie n .IP """FFLUSH_NULL""" 4
6730 .el .IP \f(CWFFLUSH_NULL\fR 4
6731 .IX Xref "FFLUSH_NULL"
6732 .IX Item "FFLUSH_NULL"
6733 This symbol, if defined, tells that \f(CWfflush(NULL)\fR correctly
6734 flushes all pending stdio output without side effects. In
6735 particular, on some platforms calling \f(CWfflush(NULL)\fR *still*
6736 corrupts \f(CW\*(C`STDIN\*(C'\fR if it is a pipe.
6737 .ie n .IP """FILE_base""" 4
6738 .el .IP \f(CWFILE_base\fR 4
6739 .IX Xref "FILE_base"
6740 .IX Item "FILE_base"
6741 This macro is used to access the \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the
6742 \&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
6743 defined if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined.
6744 .RS 4
6745 .Sp
6746 .Vb 1
6747 \& void * FILE_base(FILE * f)
6748 .Ve
6749 .RE
6750 .RS 4
6751 .RE
6752 .ie n .IP """FILE_bufsiz""" 4
6753 .el .IP \f(CWFILE_bufsiz\fR 4
6754 .IX Xref "FILE_bufsiz"
6755 .IX Item "FILE_bufsiz"
6756 This macro is used to determine the number of bytes in the I/O
6757 buffer pointed to by \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the \f(CW\*(C`FILE\*(C'\fR
6758 structure pointed to its argument. This macro will always be defined
6759 if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined.
6760 .RS 4
6761 .Sp
6762 .Vb 1
6763 \& Size_t FILE_bufsiz(FILE *f)
6764 .Ve
6765 .RE
6766 .RS 4
6767 .RE
6768 .ie n .IP """FILE_cnt""" 4
6769 .el .IP \f(CWFILE_cnt\fR 4
6770 .IX Xref "FILE_cnt"
6771 .IX Item "FILE_cnt"
6772 This macro is used to access the \f(CW\*(C`_cnt\*(C'\fR field (or equivalent) of the
6773 \&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
6774 defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined.
6775 .RS 4
6776 .Sp
6777 .Vb 1
6778 \& Size_t FILE_cnt(FILE * f)
6779 .Ve
6780 .RE
6781 .RS 4
6782 .RE
6783 .ie n .IP """FILE_ptr""" 4
6784 .el .IP \f(CWFILE_ptr\fR 4
6785 .IX Xref "FILE_ptr"
6786 .IX Item "FILE_ptr"
6787 This macro is used to access the \f(CW\*(C`_ptr\*(C'\fR field (or equivalent) of the
6788 \&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
6789 defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined.
6790 .RS 4
6791 .Sp
6792 .Vb 1
6793 \& void * FILE_ptr(FILE * f)
6794 .Ve
6795 .RE
6796 .RS 4
6797 .RE
6798 .ie n .IP """FLEXFILENAMES""" 4
6799 .el .IP \f(CWFLEXFILENAMES\fR 4
6800 .IX Xref "FLEXFILENAMES"
6801 .IX Item "FLEXFILENAMES"
6802 This symbol, if defined, indicates that the system supports filenames
6803 longer than 14 characters.
6804 .ie n .IP """HAS_DIR_DD_FD""" 4
6805 .el .IP \f(CWHAS_DIR_DD_FD\fR 4
6806 .IX Xref "HAS_DIR_DD_FD"
6807 .IX Item "HAS_DIR_DD_FD"
6808 This symbol, if defined, indicates that the \f(CW\*(C`DIR\*(C'\fR* dirstream
6809 structure contains a member variable named \f(CW\*(C`dd_fd\*(C'\fR.
6810 .ie n .IP """HAS_DUP2""" 4
6811 .el .IP \f(CWHAS_DUP2\fR 4
6812 .IX Xref "HAS_DUP2"
6813 .IX Item "HAS_DUP2"
6814 This symbol, if defined, indicates that the \f(CW\*(C`dup2\*(C'\fR routine is
6815 available to duplicate file descriptors.
6816 .ie n .IP """HAS_DUP3""" 4
6817 .el .IP \f(CWHAS_DUP3\fR 4
6818 .IX Xref "HAS_DUP3"
6819 .IX Item "HAS_DUP3"
6820 This symbol, if defined, indicates that the \f(CW\*(C`dup3\*(C'\fR routine is
6821 available to duplicate file descriptors.
6822 .ie n .IP """HAS_FAST_STDIO""" 4
6823 .el .IP \f(CWHAS_FAST_STDIO\fR 4
6824 .IX Xref "HAS_FAST_STDIO"
6825 .IX Item "HAS_FAST_STDIO"
6826 This symbol, if defined, indicates that the "fast stdio"
6827 is available to manipulate the stdio buffers directly.
6828 .ie n .IP """HAS_FCHDIR""" 4
6829 .el .IP \f(CWHAS_FCHDIR\fR 4
6830 .IX Xref "HAS_FCHDIR"
6831 .IX Item "HAS_FCHDIR"
6832 This symbol, if defined, indicates that the \f(CW\*(C`fchdir\*(C'\fR routine is
6833 available to change directory using a file descriptor.
6834 .ie n .IP """HAS_FCNTL""" 4
6835 .el .IP \f(CWHAS_FCNTL\fR 4
6836 .IX Xref "HAS_FCNTL"
6837 .IX Item "HAS_FCNTL"
6838 This symbol, if defined, indicates to the C program that
6839 the \f(CWfcntl()\fR function exists.
6840 .ie n .IP """HAS_FDCLOSE""" 4
6841 .el .IP \f(CWHAS_FDCLOSE\fR 4
6842 .IX Xref "HAS_FDCLOSE"
6843 .IX Item "HAS_FDCLOSE"
6844 This symbol, if defined, indicates that the \f(CW\*(C`fdclose\*(C'\fR routine is
6845 available to free a \f(CW\*(C`FILE\*(C'\fR structure without closing the underlying
6846 file descriptor. This function appeared in \f(CW\*(C`FreeBSD\*(C'\fR 10.2.
6847 .ie n .IP """HAS_FDOPENDIR""" 4
6848 .el .IP \f(CWHAS_FDOPENDIR\fR 4
6849 .IX Xref "HAS_FDOPENDIR"
6850 .IX Item "HAS_FDOPENDIR"
6851 This symbol, if defined, indicates that the \f(CWfdopendir()\fR routine is
6852 available to open directories using an opened file descriptor already
6853 referring to that directory.
6854 .ie n .IP """HAS_FPATHCONF""" 4
6855 .el .IP \f(CWHAS_FPATHCONF\fR 4
6856 .IX Xref "HAS_FPATHCONF"
6857 .IX Item "HAS_FPATHCONF"
6858 This symbol, if defined, indicates that \f(CWpathconf()\fR is available
6859 to determine file-system related limits and options associated
6860 with a given open file descriptor.
6861 .ie n .IP """HAS_FPOS64_T""" 4
6862 .el .IP \f(CWHAS_FPOS64_T\fR 4
6863 .IX Xref "HAS_FPOS64_T"
6864 .IX Item "HAS_FPOS64_T"
6865 This symbol will be defined if the C compiler supports \f(CW\*(C`fpos64_t\*(C'\fR.
6866 .ie n .IP """HAS_FSTATFS""" 4
6867 .el .IP \f(CWHAS_FSTATFS\fR 4
6868 .IX Xref "HAS_FSTATFS"
6869 .IX Item "HAS_FSTATFS"
6870 This symbol, if defined, indicates that the \f(CW\*(C`fstatfs\*(C'\fR routine is
6871 available to stat filesystems by file descriptors.
6872 .ie n .IP """HAS_FSTATVFS""" 4
6873 .el .IP \f(CWHAS_FSTATVFS\fR 4
6874 .IX Xref "HAS_FSTATVFS"
6875 .IX Item "HAS_FSTATVFS"
6876 This symbol, if defined, indicates that the \f(CW\*(C`fstatvfs\*(C'\fR routine is
6877 available to stat filesystems by file descriptors.
6878 .ie n .IP """HAS_GETFSSTAT""" 4
6879 .el .IP \f(CWHAS_GETFSSTAT\fR 4
6880 .IX Xref "HAS_GETFSSTAT"
6881 .IX Item "HAS_GETFSSTAT"
6882 This symbol, if defined, indicates that the \f(CW\*(C`getfsstat\*(C'\fR routine is
6883 available to stat filesystems in bulk.
6884 .ie n .IP """HAS_GETMNT""" 4
6885 .el .IP \f(CWHAS_GETMNT\fR 4
6886 .IX Xref "HAS_GETMNT"
6887 .IX Item "HAS_GETMNT"
6888 This symbol, if defined, indicates that the \f(CW\*(C`getmnt\*(C'\fR routine is
6889 available to get filesystem mount info by filename.
6890 .ie n .IP """HAS_GETMNTENT""" 4
6891 .el .IP \f(CWHAS_GETMNTENT\fR 4
6892 .IX Xref "HAS_GETMNTENT"
6893 .IX Item "HAS_GETMNTENT"
6894 This symbol, if defined, indicates that the \f(CW\*(C`getmntent\*(C'\fR routine is
6895 available to iterate through mounted file systems to get their info.
6896 .ie n .IP """HAS_HASMNTOPT""" 4
6897 .el .IP \f(CWHAS_HASMNTOPT\fR 4
6898 .IX Xref "HAS_HASMNTOPT"
6899 .IX Item "HAS_HASMNTOPT"
6900 This symbol, if defined, indicates that the \f(CW\*(C`hasmntopt\*(C'\fR routine is
6901 available to query the mount options of file systems.
6902 .ie n .IP """HAS_LSEEK_PROTO""" 4
6903 .el .IP \f(CWHAS_LSEEK_PROTO\fR 4
6904 .IX Xref "HAS_LSEEK_PROTO"
6905 .IX Item "HAS_LSEEK_PROTO"
6906 This symbol, if defined, indicates that the system provides
6907 a prototype for the \f(CWlseek()\fR function. Otherwise, it is up
6908 to the program to supply one. A good guess is
6909 .Sp
6910 .Vb 1
6911 \& extern off_t lseek(int, off_t, int);
6912 .Ve
6913 .ie n .IP """HAS_MKDIR""" 4
6914 .el .IP \f(CWHAS_MKDIR\fR 4
6915 .IX Xref "HAS_MKDIR"
6916 .IX Item "HAS_MKDIR"
6917 This symbol, if defined, indicates that the \f(CW\*(C`mkdir\*(C'\fR routine is available
6918 to create directories. Otherwise you should fork off a new process to
6919 exec \fI/bin/mkdir\fR.
6920 .ie n .IP """HAS_OFF64_T""" 4
6921 .el .IP \f(CWHAS_OFF64_T\fR 4
6922 .IX Xref "HAS_OFF64_T"
6923 .IX Item "HAS_OFF64_T"
6924 This symbol will be defined if the C compiler supports \f(CW\*(C`off64_t\*(C'\fR.
6925 .ie n .IP """HAS_OPENAT""" 4
6926 .el .IP \f(CWHAS_OPENAT\fR 4
6927 .IX Xref "HAS_OPENAT"
6928 .IX Item "HAS_OPENAT"
6929 This symbol is defined if the \f(CWopenat()\fR routine is available.
6930 .ie n .IP """HAS_OPEN3""" 4
6931 .el .IP \f(CWHAS_OPEN3\fR 4
6932 .IX Xref "HAS_OPEN3"
6933 .IX Item "HAS_OPEN3"
6934 This manifest constant lets the C program know that the three
6935 argument form of \f(CWopen(2)\fR is available.
6936 .ie n .IP """HAS_POLL""" 4
6937 .el .IP \f(CWHAS_POLL\fR 4
6938 .IX Xref "HAS_POLL"
6939 .IX Item "HAS_POLL"
6940 This symbol, if defined, indicates that the \f(CW\*(C`poll\*(C'\fR routine is
6941 available to \f(CW\*(C`poll\*(C'\fR active file descriptors. Please check \f(CW\*(C`I_POLL\*(C'\fR and
6942 \&\f(CW\*(C`I_SYS_POLL\*(C'\fR to know which header should be included as well.
6943 .ie n .IP """HAS_READDIR""" 4
6944 .el .IP \f(CWHAS_READDIR\fR 4
6945 .IX Xref "HAS_READDIR"
6946 .IX Item "HAS_READDIR"
6947 This symbol, if defined, indicates that the \f(CW\*(C`readdir\*(C'\fR routine is
6948 available to read directory entries. You may have to include
6949 \&\fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
6950 .ie n .IP """HAS_READDIR64_R""" 4
6951 .el .IP \f(CWHAS_READDIR64_R\fR 4
6952 .IX Xref "HAS_READDIR64_R"
6953 .IX Item "HAS_READDIR64_R"
6954 This symbol, if defined, indicates that the \f(CW\*(C`readdir64_r\*(C'\fR routine
6955 is available to readdir64 re-entrantly.
6956 .ie n .IP """HAS_REWINDDIR""" 4
6957 .el .IP \f(CWHAS_REWINDDIR\fR 4
6958 .IX Xref "HAS_REWINDDIR"
6959 .IX Item "HAS_REWINDDIR"
6960 This symbol, if defined, indicates that the \f(CW\*(C`rewinddir\*(C'\fR routine is
6961 available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
6962 .ie n .IP """HAS_RMDIR""" 4
6963 .el .IP \f(CWHAS_RMDIR\fR 4
6964 .IX Xref "HAS_RMDIR"
6965 .IX Item "HAS_RMDIR"
6966 This symbol, if defined, indicates that the \f(CW\*(C`rmdir\*(C'\fR routine is
6967 available to remove directories. Otherwise you should fork off a
6968 new process to exec \fI/bin/rmdir\fR.
6969 .ie n .IP """HAS_SEEKDIR""" 4
6970 .el .IP \f(CWHAS_SEEKDIR\fR 4
6971 .IX Xref "HAS_SEEKDIR"
6972 .IX Item "HAS_SEEKDIR"
6973 This symbol, if defined, indicates that the \f(CW\*(C`seekdir\*(C'\fR routine is
6974 available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
6975 .ie n .IP """HAS_SELECT""" 4
6976 .el .IP \f(CWHAS_SELECT\fR 4
6977 .IX Xref "HAS_SELECT"
6978 .IX Item "HAS_SELECT"
6979 This symbol, if defined, indicates that the \f(CW\*(C`select\*(C'\fR routine is
6980 available to \f(CW\*(C`select\*(C'\fR active file descriptors. If the timeout field
6981 is used, \fIsys/time.h\fR may need to be included.
6982 .ie n .IP """HAS_SETVBUF""" 4
6983 .el .IP \f(CWHAS_SETVBUF\fR 4
6984 .IX Xref "HAS_SETVBUF"
6985 .IX Item "HAS_SETVBUF"
6986 This symbol, if defined, indicates that the \f(CW\*(C`setvbuf\*(C'\fR routine is
6987 available to change buffering on an open stdio stream.
6988 to a line-buffered mode.
6989 .ie n .IP """HAS_STDIO_STREAM_ARRAY""" 4
6990 .el .IP \f(CWHAS_STDIO_STREAM_ARRAY\fR 4
6991 .IX Xref "HAS_STDIO_STREAM_ARRAY"
6992 .IX Item "HAS_STDIO_STREAM_ARRAY"
6993 This symbol, if defined, tells that there is an array
6994 holding the stdio streams.
6995 .ie n .IP """HAS_STRUCT_FS_DATA""" 4
6996 .el .IP \f(CWHAS_STRUCT_FS_DATA\fR 4
6997 .IX Xref "HAS_STRUCT_FS_DATA"
6998 .IX Item "HAS_STRUCT_FS_DATA"
6999 This symbol, if defined, indicates that the \f(CW\*(C`struct fs_data\*(C'\fR
7000 to do \f(CWstatfs()\fR is supported.
7001 .ie n .IP """HAS_STRUCT_STATFS""" 4
7002 .el .IP \f(CWHAS_STRUCT_STATFS\fR 4
7003 .IX Xref "HAS_STRUCT_STATFS"
7004 .IX Item "HAS_STRUCT_STATFS"
7005 This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR
7006 to do \f(CWstatfs()\fR is supported.
7007 .ie n .IP """HAS_STRUCT_STATFS_F_FLAGS""" 4
7008 .el .IP \f(CWHAS_STRUCT_STATFS_F_FLAGS\fR 4
7009 .IX Xref "HAS_STRUCT_STATFS_F_FLAGS"
7010 .IX Item "HAS_STRUCT_STATFS_F_FLAGS"
7011 This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR
7012 does have the \f(CW\*(C`f_flags\*(C'\fR member containing the mount flags of
7013 the filesystem containing the file.
7014 This kind of \f(CW\*(C`struct statfs\*(C'\fR is coming from \fIsys/mount.h\fR (\f(CW\*(C`BSD\*(C'\fR 4.3),
7015 not from \fIsys/statfs.h\fR (\f(CW\*(C`SYSV\*(C'\fR). Older \f(CW\*(C`BSDs\*(C'\fR (like Ultrix) do not
7016 have \f(CWstatfs()\fR and \f(CW\*(C`struct statfs\*(C'\fR, they have \f(CWustat()\fR and \f(CWgetmnt()\fR
7017 with \f(CW\*(C`struct ustat\*(C'\fR and \f(CW\*(C`struct fs_data\*(C'\fR.
7018 .ie n .IP """HAS_TELLDIR""" 4
7019 .el .IP \f(CWHAS_TELLDIR\fR 4
7020 .IX Xref "HAS_TELLDIR"
7021 .IX Item "HAS_TELLDIR"
7022 This symbol, if defined, indicates that the \f(CW\*(C`telldir\*(C'\fR routine is
7023 available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
7024 .ie n .IP """HAS_USTAT""" 4
7025 .el .IP \f(CWHAS_USTAT\fR 4
7026 .IX Xref "HAS_USTAT"
7027 .IX Item "HAS_USTAT"
7028 This symbol, if defined, indicates that the \f(CW\*(C`ustat\*(C'\fR system call is
7029 available to query file system statistics by \f(CW\*(C`dev_t\*(C'\fR.
7030 .ie n .IP """I_FCNTL""" 4
7031 .el .IP \f(CWI_FCNTL\fR 4
7032 .IX Xref "I_FCNTL"
7033 .IX Item "I_FCNTL"
7034 This manifest constant tells the C program to include \fIfcntl.h\fR.
7035 .RS 4
7036 .Sp
7037 .Vb 3
7038 \& #ifdef I_FCNTL
7039 \& #include <fcntl.h>
7040 \& #endif
7041 .Ve
7042 .RE
7043 .RS 4
7044 .RE
7045 .ie n .IP """I_SYS_DIR""" 4
7046 .el .IP \f(CWI_SYS_DIR\fR 4
7047 .IX Xref "I_SYS_DIR"
7048 .IX Item "I_SYS_DIR"
7049 This symbol, if defined, indicates to the C program that it should
7050 include \fIsys/dir.h\fR.
7051 .RS 4
7052 .Sp
7053 .Vb 3
7054 \& #ifdef I_SYS_DIR
7055 \& #include <sys_dir.h>
7056 \& #endif
7057 .Ve
7058 .RE
7059 .RS 4
7060 .RE
7061 .ie n .IP """I_SYS_FILE""" 4
7062 .el .IP \f(CWI_SYS_FILE\fR 4
7063 .IX Xref "I_SYS_FILE"
7064 .IX Item "I_SYS_FILE"
7065 This symbol, if defined, indicates to the C program that it should
7066 include \fIsys/file.h\fR to get definition of \f(CW\*(C`R_OK\*(C'\fR and friends.
7067 .RS 4
7068 .Sp
7069 .Vb 3
7070 \& #ifdef I_SYS_FILE
7071 \& #include <sys_file.h>
7072 \& #endif
7073 .Ve
7074 .RE
7075 .RS 4
7076 .RE
7077 .ie n .IP """I_SYS_NDIR""" 4
7078 .el .IP \f(CWI_SYS_NDIR\fR 4
7079 .IX Xref "I_SYS_NDIR"
7080 .IX Item "I_SYS_NDIR"
7081 This symbol, if defined, indicates to the C program that it should
7082 include \fIsys/ndir.h\fR.
7083 .RS 4
7084 .Sp
7085 .Vb 3
7086 \& #ifdef I_SYS_NDIR
7087 \& #include <sys_ndir.h>
7088 \& #endif
7089 .Ve
7090 .RE
7091 .RS 4
7092 .RE
7093 .ie n .IP """I_SYS_STATFS""" 4
7094 .el .IP \f(CWI_SYS_STATFS\fR 4
7095 .IX Xref "I_SYS_STATFS"
7096 .IX Item "I_SYS_STATFS"
7097 This symbol, if defined, indicates that \fIsys/statfs.h\fR exists.
7098 .RS 4
7099 .Sp
7100 .Vb 3
7101 \& #ifdef I_SYS_STATFS
7102 \& #include <sys_statfs.h>
7103 \& #endif
7104 .Ve
7105 .RE
7106 .RS 4
7107 .RE
7108 .ie n .IP """LSEEKSIZE""" 4
7109 .el .IP \f(CWLSEEKSIZE\fR 4
7110 .IX Xref "LSEEKSIZE"
7111 .IX Item "LSEEKSIZE"
7112 This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR.
7113 .ie n .IP """RD_NODATA""" 4
7114 .el .IP \f(CWRD_NODATA\fR 4
7115 .IX Xref "RD_NODATA"
7116 .IX Item "RD_NODATA"
7117 This symbol holds the return code from \f(CWread()\fR when no data is present
7118 on the non-blocking file descriptor. Be careful! If \f(CW\*(C`EOF_NONBLOCK\*(C'\fR is
7119 not defined, then you can't distinguish between no data and \f(CW\*(C`EOF\*(C'\fR by
7120 issuing a \f(CWread()\fR. You'll have to find another way to tell for sure!
7121 .ie n .IP """READDIR64_R_PROTO""" 4
7122 .el .IP \f(CWREADDIR64_R_PROTO\fR 4
7123 .IX Xref "READDIR64_R_PROTO"
7124 .IX Item "READDIR64_R_PROTO"
7125 This symbol encodes the prototype of \f(CW\*(C`readdir64_r\*(C'\fR.
7126 It is zero if \f(CW\*(C`d_readdir64_r\*(C'\fR is undef, and one of the
7127 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir64_r\*(C'\fR
7128 is defined.
7129 .ie n .IP """STDCHAR""" 4
7130 .el .IP \f(CWSTDCHAR\fR 4
7131 .IX Xref "STDCHAR"
7132 .IX Item "STDCHAR"
7133 This symbol is defined to be the type of char used in \fIstdio.h\fR.
7134 It has the values "unsigned char" or "char".
7135 .ie n .IP """STDIO_CNT_LVALUE""" 4
7136 .el .IP \f(CWSTDIO_CNT_LVALUE\fR 4
7137 .IX Xref "STDIO_CNT_LVALUE"
7138 .IX Item "STDIO_CNT_LVALUE"
7139 This symbol is defined if the \f(CW\*(C`FILE_cnt\*(C'\fR macro can be used as an
7140 lvalue.
7141 .ie n .IP """STDIO_PTR_LVAL_NOCHANGE_CNT""" 4
7142 .el .IP \f(CWSTDIO_PTR_LVAL_NOCHANGE_CNT\fR 4
7143 .IX Xref "STDIO_PTR_LVAL_NOCHANGE_CNT"
7144 .IX Item "STDIO_PTR_LVAL_NOCHANGE_CNT"
7145 This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue
7146 to increase the pointer by n leaves \f(CWFile_cnt(fp)\fR unchanged.
7147 .ie n .IP """STDIO_PTR_LVAL_SETS_CNT""" 4
7148 .el .IP \f(CWSTDIO_PTR_LVAL_SETS_CNT\fR 4
7149 .IX Xref "STDIO_PTR_LVAL_SETS_CNT"
7150 .IX Item "STDIO_PTR_LVAL_SETS_CNT"
7151 This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue
7152 to increase the pointer by n has the side effect of decreasing the
7153 value of \f(CWFile_cnt(fp)\fR by n.
7154 .ie n .IP """STDIO_PTR_LVALUE""" 4
7155 .el .IP \f(CWSTDIO_PTR_LVALUE\fR 4
7156 .IX Xref "STDIO_PTR_LVALUE"
7157 .IX Item "STDIO_PTR_LVALUE"
7158 This symbol is defined if the \f(CW\*(C`FILE_ptr\*(C'\fR macro can be used as an
7159 lvalue.
7160 .ie n .IP """STDIO_STREAM_ARRAY""" 4
7161 .el .IP \f(CWSTDIO_STREAM_ARRAY\fR 4
7162 .IX Xref "STDIO_STREAM_ARRAY"
7163 .IX Item "STDIO_STREAM_ARRAY"
7164 This symbol tells the name of the array holding the stdio streams.
7165 Usual values include \f(CW\*(C`_iob\*(C'\fR, \f(CW\*(C`_\|_iob\*(C'\fR, and \f(CW\*(C`_\|_sF\*(C'\fR.
7166 .ie n .IP """ST_INO_SIGN""" 4
7167 .el .IP \f(CWST_INO_SIGN\fR 4
7168 .IX Xref "ST_INO_SIGN"
7169 .IX Item "ST_INO_SIGN"
7170 This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_ino\*(C'\fR.
7171 1 for unsigned, \-1 for signed.
7172 .ie n .IP """ST_INO_SIZE""" 4
7173 .el .IP \f(CWST_INO_SIZE\fR 4
7174 .IX Xref "ST_INO_SIZE"
7175 .IX Item "ST_INO_SIZE"
7176 This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_ino\*(C'\fR in bytes.
7177 .ie n .IP """VAL_EAGAIN""" 4
7178 .el .IP \f(CWVAL_EAGAIN\fR 4
7179 .IX Xref "VAL_EAGAIN"
7180 .IX Item "VAL_EAGAIN"
7181 This symbol holds the errno error code set by \f(CWread()\fR when no data was
7182 present on the non-blocking file descriptor.
7183 .ie n .IP """VAL_O_NONBLOCK""" 4
7184 .el .IP \f(CWVAL_O_NONBLOCK\fR 4
7185 .IX Xref "VAL_O_NONBLOCK"
7186 .IX Item "VAL_O_NONBLOCK"
7187 This symbol is to be used during \f(CWopen()\fR or \f(CWfcntl(F_SETFL)\fR to turn on
7188 non-blocking I/O for the file descriptor. Note that there is no way
7189 back, i.e. you cannot turn it blocking again this way. If you wish to
7190 alternatively switch between blocking and non-blocking, use the
7191 \&\f(CWioctl(FIOSNBIO)\fR call instead, but that is not supported by all devices.
7192 .ie n .IP """VOID_CLOSEDIR""" 4
7193 .el .IP \f(CWVOID_CLOSEDIR\fR 4
7194 .IX Xref "VOID_CLOSEDIR"
7195 .IX Item "VOID_CLOSEDIR"
7196 This symbol, if defined, indicates that the \f(CWclosedir()\fR routine
7197 does not return a value.
7198 .SH "Floating point"
7199 .IX Header "Floating point"
7200 Also "List of capability HAS_foo symbols" lists capabilities
7201 that arent in this section. For example \f(CW\*(C`HAS_ASINH\*(C'\fR, for the
7202 hyperbolic sine function.
7203 .ie n .IP """CASTFLAGS""" 4
7204 .el .IP \f(CWCASTFLAGS\fR 4
7205 .IX Xref "CASTFLAGS"
7206 .IX Item "CASTFLAGS"
7207 This symbol contains flags that say what difficulties the compiler
7208 has casting odd floating values to unsigned long:
7209 .Sp
7210 .Vb 4
7211 \& 0 = ok
7212 \& 1 = couldn\*(Aqt cast < 0
7213 \& 2 = couldn\*(Aqt cast >= 0x80000000
7214 \& 4 = couldn\*(Aqt cast in argument expression list
7215 .Ve
7216 .ie n .IP """CASTNEGFLOAT""" 4
7217 .el .IP \f(CWCASTNEGFLOAT\fR 4
7218 .IX Xref "CASTNEGFLOAT"
7219 .IX Item "CASTNEGFLOAT"
7220 This symbol is defined if the C compiler can cast negative
7221 numbers to unsigned longs, ints and shorts.
7222 .ie n .IP """DOUBLE_HAS_INF""" 4
7223 .el .IP \f(CWDOUBLE_HAS_INF\fR 4
7224 .IX Xref "DOUBLE_HAS_INF"
7225 .IX Item "DOUBLE_HAS_INF"
7226 This symbol, if defined, indicates that the double has
7227 the infinity.
7228 .ie n .IP """DOUBLE_HAS_NAN""" 4
7229 .el .IP \f(CWDOUBLE_HAS_NAN\fR 4
7230 .IX Xref "DOUBLE_HAS_NAN"
7231 .IX Item "DOUBLE_HAS_NAN"
7232 This symbol, if defined, indicates that the double has
7233 the not-a-number.
7234 .ie n .IP """DOUBLE_HAS_NEGATIVE_ZERO""" 4
7235 .el .IP \f(CWDOUBLE_HAS_NEGATIVE_ZERO\fR 4
7236 .IX Xref "DOUBLE_HAS_NEGATIVE_ZERO"
7237 .IX Item "DOUBLE_HAS_NEGATIVE_ZERO"
7238 This symbol, if defined, indicates that the double has
7239 the \f(CW\*(C`negative_zero\*(C'\fR.
7240 .ie n .IP """DOUBLE_HAS_SUBNORMALS""" 4
7241 .el .IP \f(CWDOUBLE_HAS_SUBNORMALS\fR 4
7242 .IX Xref "DOUBLE_HAS_SUBNORMALS"
7243 .IX Item "DOUBLE_HAS_SUBNORMALS"
7244 This symbol, if defined, indicates that the double has
7245 the subnormals (denormals).
7246 .ie n .IP """DOUBLEINFBYTES""" 4
7247 .el .IP \f(CWDOUBLEINFBYTES\fR 4
7248 .IX Xref "DOUBLEINFBYTES"
7249 .IX Item "DOUBLEINFBYTES"
7250 This symbol, if defined, is a comma-separated list of
7251 hexadecimal bytes for the double precision infinity.
7252 .ie n .IP """DOUBLEKIND""" 4
7253 .el .IP \f(CWDOUBLEKIND\fR 4
7254 .IX Xref "DOUBLEKIND"
7255 .IX Item "DOUBLEKIND"
7256 \&\f(CW\*(C`DOUBLEKIND\*(C'\fR will be one of
7257 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN\*(C'\fR
7258 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN\*(C'\fR
7259 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN\*(C'\fR
7260 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN\*(C'\fR
7261 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR
7262 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR
7263 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE\*(C'\fR
7264 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE\*(C'\fR
7265 \&\f(CW\*(C`DOUBLE_IS_VAX_F_FLOAT\*(C'\fR
7266 \&\f(CW\*(C`DOUBLE_IS_VAX_D_FLOAT\*(C'\fR
7267 \&\f(CW\*(C`DOUBLE_IS_VAX_G_FLOAT\*(C'\fR
7268 \&\f(CW\*(C`DOUBLE_IS_IBM_SINGLE_32_BIT\*(C'\fR
7269 \&\f(CW\*(C`DOUBLE_IS_IBM_DOUBLE_64_BIT\*(C'\fR
7270 \&\f(CW\*(C`DOUBLE_IS_CRAY_SINGLE_64_BIT\*(C'\fR
7271 \&\f(CW\*(C`DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR
7272 .ie n .IP """DOUBLEMANTBITS""" 4
7273 .el .IP \f(CWDOUBLEMANTBITS\fR 4
7274 .IX Xref "DOUBLEMANTBITS"
7275 .IX Item "DOUBLEMANTBITS"
7276 This symbol, if defined, tells how many mantissa bits
7277 there are in double precision floating point format.
7278 Note that this is usually \f(CW\*(C`DBL_MANT_DIG\*(C'\fR minus one, since
7279 with the standard \f(CW\*(C`IEEE\*(C'\fR 754 formats \f(CW\*(C`DBL_MANT_DIG\*(C'\fR includes
7280 the implicit bit, which doesn't really exist.
7281 .ie n .IP """DOUBLENANBYTES""" 4
7282 .el .IP \f(CWDOUBLENANBYTES\fR 4
7283 .IX Xref "DOUBLENANBYTES"
7284 .IX Item "DOUBLENANBYTES"
7285 This symbol, if defined, is a comma-separated list of
7286 hexadecimal bytes (0xHH) for the double precision not-a-number.
7287 .ie n .IP """DOUBLESIZE""" 4
7288 .el .IP \f(CWDOUBLESIZE\fR 4
7289 .IX Xref "DOUBLESIZE"
7290 .IX Item "DOUBLESIZE"
7291 This symbol contains the size of a double, so that the C preprocessor
7292 can make decisions based on it.
7293 .ie n .IP """DOUBLE_STYLE_CRAY""" 4
7294 .el .IP \f(CWDOUBLE_STYLE_CRAY\fR 4
7295 .IX Xref "DOUBLE_STYLE_CRAY"
7296 .IX Item "DOUBLE_STYLE_CRAY"
7297 This symbol, if defined, indicates that the double is
7298 the 64\-bit \f(CW\*(C`CRAY\*(C'\fR mainframe format.
7299 .ie n .IP """DOUBLE_STYLE_IBM""" 4
7300 .el .IP \f(CWDOUBLE_STYLE_IBM\fR 4
7301 .IX Xref "DOUBLE_STYLE_IBM"
7302 .IX Item "DOUBLE_STYLE_IBM"
7303 This symbol, if defined, indicates that the double is
7304 the 64\-bit \f(CW\*(C`IBM\*(C'\fR mainframe format.
7305 .ie n .IP """DOUBLE_STYLE_IEEE""" 4
7306 .el .IP \f(CWDOUBLE_STYLE_IEEE\fR 4
7307 .IX Xref "DOUBLE_STYLE_IEEE"
7308 .IX Item "DOUBLE_STYLE_IEEE"
7309 This symbol, if defined, indicates that the double is
7310 the 64\-bit \f(CW\*(C`IEEE\*(C'\fR 754.
7311 .ie n .IP """DOUBLE_STYLE_VAX""" 4
7312 .el .IP \f(CWDOUBLE_STYLE_VAX\fR 4
7313 .IX Xref "DOUBLE_STYLE_VAX"
7314 .IX Item "DOUBLE_STYLE_VAX"
7315 This symbol, if defined, indicates that the double is
7316 the 64\-bit \f(CW\*(C`VAX\*(C'\fR format D or G.
7317 .ie n .IP """HAS_ATOLF""" 4
7318 .el .IP \f(CWHAS_ATOLF\fR 4
7319 .IX Xref "HAS_ATOLF"
7320 .IX Item "HAS_ATOLF"
7321 This symbol, if defined, indicates that the \f(CW\*(C`atolf\*(C'\fR routine is
7322 available to convert strings into long doubles.
7323 .ie n .IP """HAS_CLASS""" 4
7324 .el .IP \f(CWHAS_CLASS\fR 4
7325 .IX Xref "HAS_CLASS"
7326 .IX Item "HAS_CLASS"
7327 This symbol, if defined, indicates that the \f(CW\*(C`class\*(C'\fR routine is
7328 available to classify doubles. Available for example in \f(CW\*(C`AIX\*(C'\fR.
7329 The returned values are defined in \fIfloat.h\fR and are:
7330 .Sp
7331 .Vb 10
7332 \& FP_PLUS_NORM Positive normalized, nonzero
7333 \& FP_MINUS_NORM Negative normalized, nonzero
7334 \& FP_PLUS_DENORM Positive denormalized, nonzero
7335 \& FP_MINUS_DENORM Negative denormalized, nonzero
7336 \& FP_PLUS_ZERO +0.0
7337 \& FP_MINUS_ZERO \-0.0
7338 \& FP_PLUS_INF +INF
7339 \& FP_MINUS_INF \-INF
7340 \& FP_NANS Signaling Not a Number (NaNS)
7341 \& FP_NANQ Quiet Not a Number (NaNQ)
7342 .Ve
7343 .ie n .IP """HAS_FINITE""" 4
7344 .el .IP \f(CWHAS_FINITE\fR 4
7345 .IX Xref "HAS_FINITE"
7346 .IX Item "HAS_FINITE"
7347 This symbol, if defined, indicates that the \f(CW\*(C`finite\*(C'\fR routine is
7348 available to check whether a double is \f(CW\*(C`finite\*(C'\fR (non-infinity non-NaN).
7349 .ie n .IP """HAS_FINITEL""" 4
7350 .el .IP \f(CWHAS_FINITEL\fR 4
7351 .IX Xref "HAS_FINITEL"
7352 .IX Item "HAS_FINITEL"
7353 This symbol, if defined, indicates that the \f(CW\*(C`finitel\*(C'\fR routine is
7354 available to check whether a long double is finite
7355 (non-infinity non-NaN).
7356 .ie n .IP """HAS_FPCLASS""" 4
7357 .el .IP \f(CWHAS_FPCLASS\fR 4
7358 .IX Xref "HAS_FPCLASS"
7359 .IX Item "HAS_FPCLASS"
7360 This symbol, if defined, indicates that the \f(CW\*(C`fpclass\*(C'\fR routine is
7361 available to classify doubles. Available for example in Solaris/\f(CW\*(C`SVR4\*(C'\fR.
7362 The returned values are defined in \fIieeefp.h\fR and are:
7363 .Sp
7364 .Vb 10
7365 \& FP_SNAN signaling NaN
7366 \& FP_QNAN quiet NaN
7367 \& FP_NINF negative infinity
7368 \& FP_PINF positive infinity
7369 \& FP_NDENORM negative denormalized non\-zero
7370 \& FP_PDENORM positive denormalized non\-zero
7371 \& FP_NZERO negative zero
7372 \& FP_PZERO positive zero
7373 \& FP_NNORM negative normalized non\-zero
7374 \& FP_PNORM positive normalized non\-zero
7375 .Ve
7376 .ie n .IP """HAS_FP_CLASS""" 4
7377 .el .IP \f(CWHAS_FP_CLASS\fR 4
7378 .IX Xref "HAS_FP_CLASS"
7379 .IX Item "HAS_FP_CLASS"
7380 This symbol, if defined, indicates that the \f(CW\*(C`fp_class\*(C'\fR routine is
7381 available to classify doubles. Available for example in Digital \f(CW\*(C`UNIX\*(C'\fR.
7382 The returned values are defined in \fImath.h\fR and are:
7383 .Sp
7384 .Vb 10
7385 \& FP_SNAN Signaling NaN (Not\-a\-Number)
7386 \& FP_QNAN Quiet NaN (Not\-a\-Number)
7387 \& FP_POS_INF +infinity
7388 \& FP_NEG_INF \-infinity
7389 \& FP_POS_NORM Positive normalized
7390 \& FP_NEG_NORM Negative normalized
7391 \& FP_POS_DENORM Positive denormalized
7392 \& FP_NEG_DENORM Negative denormalized
7393 \& FP_POS_ZERO +0.0 (positive zero)
7394 \& FP_NEG_ZERO \-0.0 (negative zero)
7395 .Ve
7396 .ie n .IP """HAS_FPCLASSIFY""" 4
7397 .el .IP \f(CWHAS_FPCLASSIFY\fR 4
7398 .IX Xref "HAS_FPCLASSIFY"
7399 .IX Item "HAS_FPCLASSIFY"
7400 This symbol, if defined, indicates that the \f(CW\*(C`fpclassify\*(C'\fR routine is
7401 available to classify doubles. Available for example in HP-UX.
7402 The returned values are defined in \fImath.h\fR and are
7403 .Sp
7404 .Vb 5
7405 \& FP_NORMAL Normalized
7406 \& FP_ZERO Zero
7407 \& FP_INFINITE Infinity
7408 \& FP_SUBNORMAL Denormalized
7409 \& FP_NAN NaN
7410 .Ve
7411 .ie n .IP """HAS_FP_CLASSIFY""" 4
7412 .el .IP \f(CWHAS_FP_CLASSIFY\fR 4
7413 .IX Xref "HAS_FP_CLASSIFY"
7414 .IX Item "HAS_FP_CLASSIFY"
7415 This symbol, if defined, indicates that the \f(CW\*(C`fp_classify\*(C'\fR routine is
7416 available to classify doubles. The values are defined in \fImath.h\fR
7417 .Sp
7418 .Vb 5
7419 \& FP_NORMAL Normalized
7420 \& FP_ZERO Zero
7421 \& FP_INFINITE Infinity
7422 \& FP_SUBNORMAL Denormalized
7423 \& FP_NAN NaN
7424 .Ve
7425 .ie n .IP """HAS_FPCLASSL""" 4
7426 .el .IP \f(CWHAS_FPCLASSL\fR 4
7427 .IX Xref "HAS_FPCLASSL"
7428 .IX Item "HAS_FPCLASSL"
7429 This symbol, if defined, indicates that the \f(CW\*(C`fpclassl\*(C'\fR routine is
7430 available to classify long doubles. Available for example in \f(CW\*(C`IRIX\*(C'\fR.
7431 The returned values are defined in \fIieeefp.h\fR and are:
7432 .Sp
7433 .Vb 10
7434 \& FP_SNAN signaling NaN
7435 \& FP_QNAN quiet NaN
7436 \& FP_NINF negative infinity
7437 \& FP_PINF positive infinity
7438 \& FP_NDENORM negative denormalized non\-zero
7439 \& FP_PDENORM positive denormalized non\-zero
7440 \& FP_NZERO negative zero
7441 \& FP_PZERO positive zero
7442 \& FP_NNORM negative normalized non\-zero
7443 \& FP_PNORM positive normalized non\-zero
7444 .Ve
7445 .ie n .IP """HAS_FP_CLASSL""" 4
7446 .el .IP \f(CWHAS_FP_CLASSL\fR 4
7447 .IX Xref "HAS_FP_CLASSL"
7448 .IX Item "HAS_FP_CLASSL"
7449 This symbol, if defined, indicates that the \f(CW\*(C`fp_classl\*(C'\fR routine is
7450 available to classify long doubles. Available for example in
7451 Digital \f(CW\*(C`UNIX\*(C'\fR. See for possible values \f(CW\*(C`HAS_FP_CLASS\*(C'\fR.
7452 .ie n .IP """HAS_FPGETROUND""" 4
7453 .el .IP \f(CWHAS_FPGETROUND\fR 4
7454 .IX Xref "HAS_FPGETROUND"
7455 .IX Item "HAS_FPGETROUND"
7456 This symbol, if defined, indicates that the \f(CW\*(C`fpgetround\*(C'\fR routine is
7457 available to get the floating point rounding mode.
7458 .ie n .IP """HAS_FREXPL""" 4
7459 .el .IP \f(CWHAS_FREXPL\fR 4
7460 .IX Xref "HAS_FREXPL"
7461 .IX Item "HAS_FREXPL"
7462 This symbol, if defined, indicates that the \f(CW\*(C`frexpl\*(C'\fR routine is
7463 available to break a long double floating-point number into
7464 a normalized fraction and an integral power of 2.
7465 .ie n .IP """HAS_ILOGB""" 4
7466 .el .IP \f(CWHAS_ILOGB\fR 4
7467 .IX Xref "HAS_ILOGB"
7468 .IX Item "HAS_ILOGB"
7469 This symbol, if defined, indicates that the \f(CW\*(C`ilogb\*(C'\fR routine is
7470 available to get integer exponent of a floating-point value.
7471 .ie n .IP """HAS_ISFINITE""" 4
7472 .el .IP \f(CWHAS_ISFINITE\fR 4
7473 .IX Xref "HAS_ISFINITE"
7474 .IX Item "HAS_ISFINITE"
7475 This symbol, if defined, indicates that the \f(CW\*(C`isfinite\*(C'\fR routine is
7476 available to check whether a double is finite (non-infinity non-NaN).
7477 .ie n .IP """HAS_ISFINITEL""" 4
7478 .el .IP \f(CWHAS_ISFINITEL\fR 4
7479 .IX Xref "HAS_ISFINITEL"
7480 .IX Item "HAS_ISFINITEL"
7481 This symbol, if defined, indicates that the \f(CW\*(C`isfinitel\*(C'\fR routine is
7482 available to check whether a long double is finite.
7483 (non-infinity non-NaN).
7484 .ie n .IP """HAS_ISINF""" 4
7485 .el .IP \f(CWHAS_ISINF\fR 4
7486 .IX Xref "HAS_ISINF"
7487 .IX Item "HAS_ISINF"
7488 This symbol, if defined, indicates that the \f(CW\*(C`isinf\*(C'\fR routine is
7489 available to check whether a double is an infinity.
7490 .ie n .IP """HAS_ISINFL""" 4
7491 .el .IP \f(CWHAS_ISINFL\fR 4
7492 .IX Xref "HAS_ISINFL"
7493 .IX Item "HAS_ISINFL"
7494 This symbol, if defined, indicates that the \f(CW\*(C`isinfl\*(C'\fR routine is
7495 available to check whether a long double is an infinity.
7496 .ie n .IP """HAS_ISNAN""" 4
7497 .el .IP \f(CWHAS_ISNAN\fR 4
7498 .IX Xref "HAS_ISNAN"
7499 .IX Item "HAS_ISNAN"
7500 This symbol, if defined, indicates that the \f(CW\*(C`isnan\*(C'\fR routine is
7501 available to check whether a double is a NaN.
7502 .ie n .IP """HAS_ISNANL""" 4
7503 .el .IP \f(CWHAS_ISNANL\fR 4
7504 .IX Xref "HAS_ISNANL"
7505 .IX Item "HAS_ISNANL"
7506 This symbol, if defined, indicates that the \f(CW\*(C`isnanl\*(C'\fR routine is
7507 available to check whether a long double is a NaN.
7508 .ie n .IP """HAS_ISNORMAL""" 4
7509 .el .IP \f(CWHAS_ISNORMAL\fR 4
7510 .IX Xref "HAS_ISNORMAL"
7511 .IX Item "HAS_ISNORMAL"
7512 This symbol, if defined, indicates that the \f(CW\*(C`isnormal\*(C'\fR routine is
7513 available to check whether a double is normal (non-zero normalized).
7514 .ie n .IP """HAS_J0L""" 4
7515 .el .IP \f(CWHAS_J0L\fR 4
7516 .IX Xref "HAS_J0L"
7517 .IX Item "HAS_J0L"
7518 This symbol, if defined, indicates to the C program that the
7519 \&\f(CWj0l()\fR function is available for Bessel functions of the first
7520 kind of the order zero, for long doubles.
7521 .ie n .IP """HAS_J0""" 4
7522 .el .IP \f(CWHAS_J0\fR 4
7523 .IX Xref "HAS_J0"
7524 .IX Item "HAS_J0"
7525 This symbol, if defined, indicates to the C program that the
7526 \&\f(CWj0()\fR function is available for Bessel functions of the first
7527 kind of the order zero, for doubles.
7528 .ie n .IP """HAS_LDBL_DIG""" 4
7529 .el .IP \f(CWHAS_LDBL_DIG\fR 4
7530 .IX Xref "HAS_LDBL_DIG"
7531 .IX Item "HAS_LDBL_DIG"
7532 This symbol, if defined, indicates that this system's \fIfloat.h\fR
7533 or \fIlimits.h\fR defines the symbol \f(CW\*(C`LDBL_DIG\*(C'\fR, which is the number
7534 of significant digits in a long double precision number. Unlike
7535 for \f(CW\*(C`DBL_DIG\*(C'\fR, there's no good guess for \f(CW\*(C`LDBL_DIG\*(C'\fR if it is undefined.
7536 .ie n .IP """HAS_LDEXPL""" 4
7537 .el .IP \f(CWHAS_LDEXPL\fR 4
7538 .IX Xref "HAS_LDEXPL"
7539 .IX Item "HAS_LDEXPL"
7540 This symbol, if defined, indicates that the \f(CW\*(C`ldexpl\*(C'\fR routine is
7541 available to shift a long double floating-point number
7542 by an integral power of 2.
7543 .ie n .IP """HAS_LLRINT""" 4
7544 .el .IP \f(CWHAS_LLRINT\fR 4
7545 .IX Xref "HAS_LLRINT"
7546 .IX Item "HAS_LLRINT"
7547 This symbol, if defined, indicates that the \f(CW\*(C`llrint\*(C'\fR routine is
7548 available to return the long long value closest to a double
7549 (according to the current rounding mode).
7550 .ie n .IP """HAS_LLRINTL""" 4
7551 .el .IP \f(CWHAS_LLRINTL\fR 4
7552 .IX Xref "HAS_LLRINTL"
7553 .IX Item "HAS_LLRINTL"
7554 This symbol, if defined, indicates that the \f(CW\*(C`llrintl\*(C'\fR routine is
7555 available to return the long long value closest to a long double
7556 (according to the current rounding mode).
7557 .ie n .IP """HAS_LLROUNDL""" 4
7558 .el .IP \f(CWHAS_LLROUNDL\fR 4
7559 .IX Xref "HAS_LLROUNDL"
7560 .IX Item "HAS_LLROUNDL"
7561 This symbol, if defined, indicates that the \f(CW\*(C`llroundl\*(C'\fR routine is
7562 available to return the nearest long long value away from zero of
7563 the long double argument value.
7564 .ie n .IP """HAS_LONG_DOUBLE""" 4
7565 .el .IP \f(CWHAS_LONG_DOUBLE\fR 4
7566 .IX Xref "HAS_LONG_DOUBLE"
7567 .IX Item "HAS_LONG_DOUBLE"
7568 This symbol will be defined if the C compiler supports long
7569 doubles.
7570 .ie n .IP """HAS_LRINT""" 4
7571 .el .IP \f(CWHAS_LRINT\fR 4
7572 .IX Xref "HAS_LRINT"
7573 .IX Item "HAS_LRINT"
7574 This symbol, if defined, indicates that the \f(CW\*(C`lrint\*(C'\fR routine is
7575 available to return the integral value closest to a double
7576 (according to the current rounding mode).
7577 .ie n .IP """HAS_LRINTL""" 4
7578 .el .IP \f(CWHAS_LRINTL\fR 4
7579 .IX Xref "HAS_LRINTL"
7580 .IX Item "HAS_LRINTL"
7581 This symbol, if defined, indicates that the \f(CW\*(C`lrintl\*(C'\fR routine is
7582 available to return the integral value closest to a long double
7583 (according to the current rounding mode).
7584 .ie n .IP """HAS_LROUNDL""" 4
7585 .el .IP \f(CWHAS_LROUNDL\fR 4
7586 .IX Xref "HAS_LROUNDL"
7587 .IX Item "HAS_LROUNDL"
7588 This symbol, if defined, indicates that the \f(CW\*(C`lroundl\*(C'\fR routine is
7589 available to return the nearest integral value away from zero of
7590 the long double argument value.
7591 .ie n .IP """HAS_MODFL""" 4
7592 .el .IP \f(CWHAS_MODFL\fR 4
7593 .IX Xref "HAS_MODFL"
7594 .IX Item "HAS_MODFL"
7595 This symbol, if defined, indicates that the \f(CW\*(C`modfl\*(C'\fR routine is
7596 available to split a long double x into a fractional part f and
7597 an integer part i such that |f| < 1.0 and (f + i) = x.
7598 .ie n .IP """HAS_NAN""" 4
7599 .el .IP \f(CWHAS_NAN\fR 4
7600 .IX Xref "HAS_NAN"
7601 .IX Item "HAS_NAN"
7602 This symbol, if defined, indicates that the \f(CW\*(C`nan\*(C'\fR routine is
7603 available to generate NaN.
7604 .ie n .IP """HAS_NEXTTOWARD""" 4
7605 .el .IP \f(CWHAS_NEXTTOWARD\fR 4
7606 .IX Xref "HAS_NEXTTOWARD"
7607 .IX Item "HAS_NEXTTOWARD"
7608 This symbol, if defined, indicates that the \f(CW\*(C`nexttoward\*(C'\fR routine is
7609 available to return the next machine representable long double from
7610 x in direction y.
7611 .ie n .IP """HAS_REMAINDER""" 4
7612 .el .IP \f(CWHAS_REMAINDER\fR 4
7613 .IX Xref "HAS_REMAINDER"
7614 .IX Item "HAS_REMAINDER"
7615 This symbol, if defined, indicates that the \f(CW\*(C`remainder\*(C'\fR routine is
7616 available to return the floating-point \f(CW\*(C`remainder\*(C'\fR.
7617 .ie n .IP """HAS_SCALBN""" 4
7618 .el .IP \f(CWHAS_SCALBN\fR 4
7619 .IX Xref "HAS_SCALBN"
7620 .IX Item "HAS_SCALBN"
7621 This symbol, if defined, indicates that the \f(CW\*(C`scalbn\*(C'\fR routine is
7622 available to multiply floating-point number by integral power
7623 of radix.
7624 .ie n .IP """HAS_SIGNBIT""" 4
7625 .el .IP \f(CWHAS_SIGNBIT\fR 4
7626 .IX Xref "HAS_SIGNBIT"
7627 .IX Item "HAS_SIGNBIT"
7628 This symbol, if defined, indicates that the \f(CW\*(C`signbit\*(C'\fR routine is
7629 available to check if the given number has the sign bit set.
7630 This should include correct testing of \-0.0. This will only be set
7631 if the \f(CWsignbit()\fR routine is safe to use with the NV type used internally
7632 in perl. Users should call \f(CWPerl_signbit()\fR, which will be #defined to
7633 the system's \f(CWsignbit()\fR function or macro if this symbol is defined.
7634 .ie n .IP """HAS_SQRTL""" 4
7635 .el .IP \f(CWHAS_SQRTL\fR 4
7636 .IX Xref "HAS_SQRTL"
7637 .IX Item "HAS_SQRTL"
7638 This symbol, if defined, indicates that the \f(CW\*(C`sqrtl\*(C'\fR routine is
7639 available to do long double square roots.
7640 .ie n .IP """HAS_STRTOD_L""" 4
7641 .el .IP \f(CWHAS_STRTOD_L\fR 4
7642 .IX Xref "HAS_STRTOD_L"
7643 .IX Item "HAS_STRTOD_L"
7644 This symbol, if defined, indicates that the \f(CW\*(C`strtod_l\*(C'\fR routine is
7645 available to convert strings to long doubles.
7646 .ie n .IP """HAS_STRTOLD""" 4
7647 .el .IP \f(CWHAS_STRTOLD\fR 4
7648 .IX Xref "HAS_STRTOLD"
7649 .IX Item "HAS_STRTOLD"
7650 This symbol, if defined, indicates that the \f(CW\*(C`strtold\*(C'\fR routine is
7651 available to convert strings to long doubles.
7652 .ie n .IP """HAS_STRTOLD_L""" 4
7653 .el .IP \f(CWHAS_STRTOLD_L\fR 4
7654 .IX Xref "HAS_STRTOLD_L"
7655 .IX Item "HAS_STRTOLD_L"
7656 This symbol, if defined, indicates that the \f(CW\*(C`strtold_l\*(C'\fR routine is
7657 available to convert strings to long doubles.
7658 .ie n .IP """HAS_TRUNC""" 4
7659 .el .IP \f(CWHAS_TRUNC\fR 4
7660 .IX Xref "HAS_TRUNC"
7661 .IX Item "HAS_TRUNC"
7662 This symbol, if defined, indicates that the \f(CW\*(C`trunc\*(C'\fR routine is
7663 available to round doubles towards zero.
7664 .ie n .IP """HAS_UNORDERED""" 4
7665 .el .IP \f(CWHAS_UNORDERED\fR 4
7666 .IX Xref "HAS_UNORDERED"
7667 .IX Item "HAS_UNORDERED"
7668 This symbol, if defined, indicates that the \f(CW\*(C`unordered\*(C'\fR routine is
7669 available to check whether two doubles are \f(CW\*(C`unordered\*(C'\fR
7670 (effectively: whether either of them is NaN)
7671 .ie n .IP """I_FENV""" 4
7672 .el .IP \f(CWI_FENV\fR 4
7673 .IX Xref "I_FENV"
7674 .IX Item "I_FENV"
7675 This symbol, if defined, indicates to the C program that it should
7676 include \fIfenv.h\fR to get the floating point environment definitions.
7677 .RS 4
7678 .Sp
7679 .Vb 3
7680 \& #ifdef I_FENV
7681 \& #include <fenv.h>
7682 \& #endif
7683 .Ve
7684 .RE
7685 .RS 4
7686 .RE
7687 .ie n .IP """I_QUADMATH""" 4
7688 .el .IP \f(CWI_QUADMATH\fR 4
7689 .IX Xref "I_QUADMATH"
7690 .IX Item "I_QUADMATH"
7691 This symbol, if defined, indicates that \fIquadmath.h\fR exists and
7692 should be included.
7693 .RS 4
7694 .Sp
7695 .Vb 3
7696 \& #ifdef I_QUADMATH
7697 \& #include <quadmath.h>
7698 \& #endif
7699 .Ve
7700 .RE
7701 .RS 4
7702 .RE
7703 .ie n .IP """LONGDBLINFBYTES""" 4
7704 .el .IP \f(CWLONGDBLINFBYTES\fR 4
7705 .IX Xref "LONGDBLINFBYTES"
7706 .IX Item "LONGDBLINFBYTES"
7707 This symbol, if defined, is a comma-separated list of
7708 hexadecimal bytes for the long double precision infinity.
7709 .ie n .IP """LONGDBLMANTBITS""" 4
7710 .el .IP \f(CWLONGDBLMANTBITS\fR 4
7711 .IX Xref "LONGDBLMANTBITS"
7712 .IX Item "LONGDBLMANTBITS"
7713 This symbol, if defined, tells how many mantissa bits
7714 there are in long double precision floating point format.
7715 Note that this can be \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR minus one,
7716 since \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR can include the \f(CW\*(C`IEEE\*(C'\fR 754 implicit bit.
7717 The common x86\-style 80\-bit long double does not have
7718 an implicit bit.
7719 .ie n .IP """LONGDBLNANBYTES""" 4
7720 .el .IP \f(CWLONGDBLNANBYTES\fR 4
7721 .IX Xref "LONGDBLNANBYTES"
7722 .IX Item "LONGDBLNANBYTES"
7723 This symbol, if defined, is a comma-separated list of
7724 hexadecimal bytes (0xHH) for the long double precision not-a-number.
7725 .ie n .IP """LONG_DOUBLEKIND""" 4
7726 .el .IP \f(CWLONG_DOUBLEKIND\fR 4
7727 .IX Xref "LONG_DOUBLEKIND"
7728 .IX Item "LONG_DOUBLEKIND"
7729 \&\f(CW\*(C`LONG_DOUBLEKIND\*(C'\fR will be one of
7730 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLE\*(C'\fR
7731 \&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR
7732 \&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR
7733 \&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN\*(C'\fR
7734 \&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN\*(C'\fR
7735 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE\*(C'\fR
7736 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE\*(C'\fR
7737 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE\*(C'\fR
7738 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE\*(C'\fR
7739 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN\*(C'\fR
7740 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN\*(C'\fR
7741 \&\f(CW\*(C`LONG_DOUBLE_IS_VAX_H_FLOAT\*(C'\fR
7742 \&\f(CW\*(C`LONG_DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR
7743 It is only defined if the system supports long doubles.
7744 .ie n .IP """LONG_DOUBLESIZE""" 4
7745 .el .IP \f(CWLONG_DOUBLESIZE\fR 4
7746 .IX Xref "LONG_DOUBLESIZE"
7747 .IX Item "LONG_DOUBLESIZE"
7748 This symbol contains the size of a long double, so that the
7749 C preprocessor can make decisions based on it. It is only
7750 defined if the system supports long doubles. Note that this
7751 is \f(CW\*(C`sizeof(long double)\*(C'\fR, which may include unused bytes.
7752 .ie n .IP """LONG_DOUBLE_STYLE_IEEE""" 4
7753 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE\fR 4
7754 .IX Xref "LONG_DOUBLE_STYLE_IEEE"
7755 .IX Item "LONG_DOUBLE_STYLE_IEEE"
7756 This symbol, if defined, indicates that the long double
7757 is any of the \f(CW\*(C`IEEE\*(C'\fR 754 style long doubles:
7758 \&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_STD\*(C'\fR, \f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_EXTENDED\*(C'\fR,
7759 \&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\*(C'\fR.
7760 .ie n .IP """LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE""" 4
7761 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\fR 4
7762 .IX Xref "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
7763 .IX Item "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
7764 This symbol, if defined, indicates that the long double is
7765 the 128\-bit double-double.
7766 .ie n .IP """LONG_DOUBLE_STYLE_IEEE_EXTENDED""" 4
7767 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_EXTENDED\fR 4
7768 .IX Xref "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
7769 .IX Item "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
7770 This symbol, if defined, indicates that the long double is
7771 the 80\-bit \f(CW\*(C`IEEE\*(C'\fR 754. Note that despite the 'extended' this
7772 is less than the 'std', since this is an extension of
7773 the double precision.
7774 .ie n .IP """LONG_DOUBLE_STYLE_IEEE_STD""" 4
7775 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_STD\fR 4
7776 .IX Xref "LONG_DOUBLE_STYLE_IEEE_STD"
7777 .IX Item "LONG_DOUBLE_STYLE_IEEE_STD"
7778 This symbol, if defined, indicates that the long double is
7779 the 128\-bit \f(CW\*(C`IEEE\*(C'\fR 754.
7780 .ie n .IP """LONG_DOUBLE_STYLE_VAX""" 4
7781 .el .IP \f(CWLONG_DOUBLE_STYLE_VAX\fR 4
7782 .IX Xref "LONG_DOUBLE_STYLE_VAX"
7783 .IX Item "LONG_DOUBLE_STYLE_VAX"
7784 This symbol, if defined, indicates that the long double is
7785 the 128\-bit \f(CW\*(C`VAX\*(C'\fR format H.
7786 .ie n .IP """NV""" 4
7787 .el .IP \f(CWNV\fR 4
7788 .IX Item "NV"
7789 Described in perlguts.
7790 .ie n .IP """NVMANTBITS""" 4
7791 .el .IP \f(CWNVMANTBITS\fR 4
7792 .IX Xref "NVMANTBITS"
7793 .IX Item "NVMANTBITS"
7794 This symbol, if defined, tells how many mantissa bits
7795 (not including implicit bit) there are in a Perl NV.
7796 This depends on which floating point type was chosen.
7797 .ie n .IP """NV_OVERFLOWS_INTEGERS_AT""" 4
7798 .el .IP \f(CWNV_OVERFLOWS_INTEGERS_AT\fR 4
7799 .IX Xref "NV_OVERFLOWS_INTEGERS_AT"
7800 .IX Item "NV_OVERFLOWS_INTEGERS_AT"
7801 This symbol gives the largest integer value that NVs can hold. This
7802 value + 1.0 cannot be stored accurately. It is expressed as constant
7803 floating point expression to reduce the chance of decimal/binary
7804 conversion issues. If it can not be determined, the value 0 is given.
7805 .ie n .IP """NV_PRESERVES_UV""" 4
7806 .el .IP \f(CWNV_PRESERVES_UV\fR 4
7807 .IX Xref "NV_PRESERVES_UV"
7808 .IX Item "NV_PRESERVES_UV"
7809 This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
7810 can preserve all the bits of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR.
7811 .ie n .IP """NV_PRESERVES_UV_BITS""" 4
7812 .el .IP \f(CWNV_PRESERVES_UV_BITS\fR 4
7813 .IX Xref "NV_PRESERVES_UV_BITS"
7814 .IX Item "NV_PRESERVES_UV_BITS"
7815 This symbol contains the number of bits a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
7816 can preserve of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR.
7817 .ie n .IP """NVSIZE""" 4
7818 .el .IP \f(CWNVSIZE\fR 4
7819 .IX Xref "NVSIZE"
7820 .IX Item "NVSIZE"
7821 This symbol contains the \f(CWsizeof(NV)\fR.
7822 Note that some floating point formats have unused bytes.
7823 The most notable example is the x86* 80\-bit extended precision
7824 which comes in byte sizes of 12 and 16 (for 32 and 64 bit
7825 platforms, respectively), but which only uses 10 bytes.
7826 Perl compiled with \f(CW\*(C`\-Duselongdouble\*(C'\fR on x86* is like this.
7827 .ie n .IP """NVTYPE""" 4
7828 .el .IP \f(CWNVTYPE\fR 4
7829 .IX Xref "NVTYPE"
7830 .IX Item "NVTYPE"
7831 This symbol defines the C type used for Perl's NV.
7832 .ie n .IP """NV_ZERO_IS_ALLBITS_ZERO""" 4
7833 .el .IP \f(CWNV_ZERO_IS_ALLBITS_ZERO\fR 4
7834 .IX Xref "NV_ZERO_IS_ALLBITS_ZERO"
7835 .IX Item "NV_ZERO_IS_ALLBITS_ZERO"
7836 This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
7837 stores 0.0 in memory as all bits zero.
7838 .SH "General Configuration"
7839 .IX Xref "PERL_GCC_BRACE_GROUPS_FORBIDDEN"
7840 .IX Header "General Configuration"
7841 This section contains configuration information not otherwise
7842 found in the more specialized sections of this document. At the
7843 end is a list of \f(CW\*(C`#defines\*(C'\fR whose name should be enough to tell
7844 you what they do, and a list of #defines which tell you if you
7845 need to \f(CW\*(C`#include\*(C'\fR files to get the corresponding functionality.
7846 .ie n .IP """ASCIIish""" 4
7847 .el .IP \f(CWASCIIish\fR 4
7848 .IX Xref "ASCIIish"
7849 .IX Item "ASCIIish"
7850 A preprocessor symbol that is defined iff the system is an ASCII platform; this
7851 symbol would not be defined on \f(CW"EBCDIC"\fR platforms.
7852 .RS 4
7853 .Sp
7854 .Vb 1
7855 \& #ifdef ASCIIish
7856 .Ve
7857 .RE
7858 .RS 4
7859 .RE
7860 .ie n .IP """BYTEORDER""" 4
7861 .el .IP \f(CWBYTEORDER\fR 4
7862 .IX Xref "BYTEORDER"
7863 .IX Item "BYTEORDER"
7864 This symbol holds the hexadecimal constant defined in byteorder,
7865 in a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc...
7866 If the compiler supports cross-compiling or multiple-architecture
7867 binaries, use compiler-defined macros to
7868 determine the byte order.
7869 .ie n .IP """CHARBITS""" 4
7870 .el .IP \f(CWCHARBITS\fR 4
7871 .IX Xref "CHARBITS"
7872 .IX Item "CHARBITS"
7873 This symbol contains the size of a char, so that the C preprocessor
7874 can make decisions based on it.
7875 .ie n .IP """DB_VERSION_MAJOR_CFG""" 4
7876 .el .IP \f(CWDB_VERSION_MAJOR_CFG\fR 4
7877 .IX Xref "DB_VERSION_MAJOR_CFG"
7878 .IX Item "DB_VERSION_MAJOR_CFG"
7879 This symbol, if defined, defines the major version number of
7880 Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
7881 .ie n .IP """DB_VERSION_MINOR_CFG""" 4
7882 .el .IP \f(CWDB_VERSION_MINOR_CFG\fR 4
7883 .IX Xref "DB_VERSION_MINOR_CFG"
7884 .IX Item "DB_VERSION_MINOR_CFG"
7885 This symbol, if defined, defines the minor version number of
7886 Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
7887 For DB version 1 this is always 0.
7888 .ie n .IP """DB_VERSION_PATCH_CFG""" 4
7889 .el .IP \f(CWDB_VERSION_PATCH_CFG\fR 4
7890 .IX Xref "DB_VERSION_PATCH_CFG"
7891 .IX Item "DB_VERSION_PATCH_CFG"
7892 This symbol, if defined, defines the patch version number of
7893 Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
7894 For DB version 1 this is always 0.
7895 .ie n .IP """DEFAULT_INC_EXCLUDES_DOT""" 4
7896 .el .IP \f(CWDEFAULT_INC_EXCLUDES_DOT\fR 4
7897 .IX Xref "DEFAULT_INC_EXCLUDES_DOT"
7898 .IX Item "DEFAULT_INC_EXCLUDES_DOT"
7899 This symbol, if defined, removes the legacy default behavior of
7900 including '.' at the end of @\f(CW\*(C`INC\*(C'\fR.
7901 .ie n .IP """DLSYM_NEEDS_UNDERSCORE""" 4
7902 .el .IP \f(CWDLSYM_NEEDS_UNDERSCORE\fR 4
7903 .IX Xref "DLSYM_NEEDS_UNDERSCORE"
7904 .IX Item "DLSYM_NEEDS_UNDERSCORE"
7905 This symbol, if defined, indicates that we need to prepend an
7906 underscore to the symbol name before calling \f(CWdlsym()\fR. This only
7907 makes sense if you *have* dlsym, which we will presume is the
7908 case if you're using \fIdl_dlopen.xs\fR.
7909 .ie n .IP """EBCDIC""" 4
7910 .el .IP \f(CWEBCDIC\fR 4
7911 .IX Xref "EBCDIC"
7912 .IX Item "EBCDIC"
7913 This symbol, if defined, indicates that this system uses
7914 \&\f(CW\*(C`EBCDIC\*(C'\fR encoding.
7915 .ie n .IP """HAS_CSH""" 4
7916 .el .IP \f(CWHAS_CSH\fR 4
7917 .IX Xref "HAS_CSH"
7918 .IX Item "HAS_CSH"
7919 This symbol, if defined, indicates that the C\-shell exists.
7920 .ie n .IP """HAS_GETHOSTNAME""" 4
7921 .el .IP \f(CWHAS_GETHOSTNAME\fR 4
7922 .IX Xref "HAS_GETHOSTNAME"
7923 .IX Item "HAS_GETHOSTNAME"
7924 This symbol, if defined, indicates that the C program may use the
7925 \&\f(CWgethostname()\fR routine to derive the host name. See also \f(CW"HAS_UNAME"\fR
7926 and \f(CW"PHOSTNAME"\fR.
7927 .ie n .IP """HAS_GNULIBC""" 4
7928 .el .IP \f(CWHAS_GNULIBC\fR 4
7929 .IX Xref "HAS_GNULIBC"
7930 .IX Item "HAS_GNULIBC"
7931 This symbol, if defined, indicates to the C program that
7932 the \f(CW\*(C`GNU\*(C'\fR C library is being used. A better check is to use
7933 the \f(CW\*(C`_\|_GLIBC_\|_\*(C'\fR and \f(CW\*(C`_\|_GLIBC_MINOR_\|_\*(C'\fR symbols supplied with glibc.
7934 .ie n .IP """HAS_LGAMMA""" 4
7935 .el .IP \f(CWHAS_LGAMMA\fR 4
7936 .IX Xref "HAS_LGAMMA"
7937 .IX Item "HAS_LGAMMA"
7938 This symbol, if defined, indicates that the \f(CW\*(C`lgamma\*(C'\fR routine is
7939 available to do the log gamma function. See also \f(CW"HAS_TGAMMA"\fR and
7940 \&\f(CW"HAS_LGAMMA_R"\fR.
7941 .ie n .IP """HAS_LGAMMA_R""" 4
7942 .el .IP \f(CWHAS_LGAMMA_R\fR 4
7943 .IX Xref "HAS_LGAMMA_R"
7944 .IX Item "HAS_LGAMMA_R"
7945 This symbol, if defined, indicates that the \f(CW\*(C`lgamma_r\*(C'\fR routine is
7946 available to do the log gamma function without using the global
7947 signgam variable.
7948 .ie n .IP """HAS_NON_INT_BITFIELDS""" 4
7949 .el .IP \f(CWHAS_NON_INT_BITFIELDS\fR 4
7950 .IX Xref "HAS_NON_INT_BITFIELDS"
7951 .IX Item "HAS_NON_INT_BITFIELDS"
7952 This symbol, if defined, indicates that the C compiler accepts, without
7953 error or warning, \f(CW\*(C`struct bitfields\*(C'\fR that are declared with sizes other
7954 than plain 'int'; for example 'unsigned char' is accepted.
7955 .ie n .IP """HAS_PRCTL_SET_NAME""" 4
7956 .el .IP \f(CWHAS_PRCTL_SET_NAME\fR 4
7957 .IX Xref "HAS_PRCTL_SET_NAME"
7958 .IX Item "HAS_PRCTL_SET_NAME"
7959 This symbol, if defined, indicates that the prctl routine is
7960 available to set process title and supports \f(CW\*(C`PR_SET_NAME\*(C'\fR.
7961 .ie n .IP """HAS_PROCSELFEXE""" 4
7962 .el .IP \f(CWHAS_PROCSELFEXE\fR 4
7963 .IX Xref "HAS_PROCSELFEXE"
7964 .IX Item "HAS_PROCSELFEXE"
7965 This symbol is defined if \f(CW\*(C`PROCSELFEXE_PATH\*(C'\fR is a symlink
7966 to the absolute pathname of the executing program.
7967 .ie n .IP """HAS_PSEUDOFORK""" 4
7968 .el .IP \f(CWHAS_PSEUDOFORK\fR 4
7969 .IX Xref "HAS_PSEUDOFORK"
7970 .IX Item "HAS_PSEUDOFORK"
7971 This symbol, if defined, indicates that an emulation of the
7972 fork routine is available.
7973 .ie n .IP """HAS_REGCOMP""" 4
7974 .el .IP \f(CWHAS_REGCOMP\fR 4
7975 .IX Xref "HAS_REGCOMP"
7976 .IX Item "HAS_REGCOMP"
7977 This symbol, if defined, indicates that the \f(CWregcomp()\fR routine is
7978 available to do some regular pattern matching (usually on \f(CW\*(C`POSIX\*(C'\fR.2
7979 conforming systems).
7980 .ie n .IP """HAS_SETPGID""" 4
7981 .el .IP \f(CWHAS_SETPGID\fR 4
7982 .IX Xref "HAS_SETPGID"
7983 .IX Item "HAS_SETPGID"
7984 This symbol, if defined, indicates that the \f(CW\*(C`setpgid(pid, gpid)\*(C'\fR
7985 routine is available to set process group ID.
7986 .ie n .IP """HAS_SIGSETJMP""" 4
7987 .el .IP \f(CWHAS_SIGSETJMP\fR 4
7988 .IX Xref "HAS_SIGSETJMP"
7989 .IX Item "HAS_SIGSETJMP"
7990 This variable indicates to the C program that the \f(CWsigsetjmp()\fR
7991 routine is available to save the calling process's registers
7992 and stack environment for later use by \f(CWsiglongjmp()\fR, and
7993 to optionally save the process's signal mask. See
7994 \&\f(CW"Sigjmp_buf"\fR, \f(CW"Sigsetjmp"\fR, and \f(CW"Siglongjmp"\fR.
7995 .ie n .IP """HAS_STRUCT_CMSGHDR""" 4
7996 .el .IP \f(CWHAS_STRUCT_CMSGHDR\fR 4
7997 .IX Xref "HAS_STRUCT_CMSGHDR"
7998 .IX Item "HAS_STRUCT_CMSGHDR"
7999 This symbol, if defined, indicates that the \f(CW\*(C`struct cmsghdr\*(C'\fR
8000 is supported.
8001 .ie n .IP """HAS_STRUCT_MSGHDR""" 4
8002 .el .IP \f(CWHAS_STRUCT_MSGHDR\fR 4
8003 .IX Xref "HAS_STRUCT_MSGHDR"
8004 .IX Item "HAS_STRUCT_MSGHDR"
8005 This symbol, if defined, indicates that the \f(CW\*(C`struct msghdr\*(C'\fR
8006 is supported.
8007 .ie n .IP """HAS_TGAMMA""" 4
8008 .el .IP \f(CWHAS_TGAMMA\fR 4
8009 .IX Xref "HAS_TGAMMA"
8010 .IX Item "HAS_TGAMMA"
8011 This symbol, if defined, indicates that the \f(CW\*(C`tgamma\*(C'\fR routine is
8012 available to do the gamma function. See also \f(CW"HAS_LGAMMA"\fR.
8013 .ie n .IP """HAS_UNAME""" 4
8014 .el .IP \f(CWHAS_UNAME\fR 4
8015 .IX Xref "HAS_UNAME"
8016 .IX Item "HAS_UNAME"
8017 This symbol, if defined, indicates that the C program may use the
8018 \&\f(CWuname()\fR routine to derive the host name. See also \f(CW"HAS_GETHOSTNAME"\fR
8019 and \f(CW"PHOSTNAME"\fR.
8020 .ie n .IP """HAS_UNION_SEMUN""" 4
8021 .el .IP \f(CWHAS_UNION_SEMUN\fR 4
8022 .IX Xref "HAS_UNION_SEMUN"
8023 .IX Item "HAS_UNION_SEMUN"
8024 This symbol, if defined, indicates that the \f(CW\*(C`union semun\*(C'\fR is
8025 defined by including \fIsys/sem.h\fR. If not, the user code
8026 probably needs to define it as:
8027 .Sp
8028 .Vb 5
8029 \& union semun {
8030 \& int val;
8031 \& struct semid_ds *buf;
8032 \& unsigned short *array;
8033 \& }
8034 .Ve
8035 .ie n .IP """I_DIRENT""" 4
8036 .el .IP \f(CWI_DIRENT\fR 4
8037 .IX Xref "I_DIRENT"
8038 .IX Item "I_DIRENT"
8039 This symbol, if defined, indicates to the C program that it should
8040 include \fIdirent.h\fR. Using this symbol also triggers the definition
8041 of the \f(CW\*(C`Direntry_t\*(C'\fR define which ends up being '\f(CW\*(C`struct dirent\*(C'\fR' or
8042 \&'\f(CW\*(C`struct direct\*(C'\fR' depending on the availability of \fIdirent.h\fR.
8043 .RS 4
8044 .Sp
8045 .Vb 3
8046 \& #ifdef I_DIRENT
8047 \& #include <dirent.h>
8048 \& #endif
8049 .Ve
8050 .RE
8051 .RS 4
8052 .RE
8053 .ie n .IP """I_POLL""" 4
8054 .el .IP \f(CWI_POLL\fR 4
8055 .IX Xref "I_POLL"
8056 .IX Item "I_POLL"
8057 This symbol, if defined, indicates that \fIpoll.h\fR exists and
8058 should be included. (see also \f(CW"HAS_POLL"\fR)
8059 .RS 4
8060 .Sp
8061 .Vb 3
8062 \& #ifdef I_POLL
8063 \& #include <poll.h>
8064 \& #endif
8065 .Ve
8066 .RE
8067 .RS 4
8068 .RE
8069 .ie n .IP """I_SYS_RESOURCE""" 4
8070 .el .IP \f(CWI_SYS_RESOURCE\fR 4
8071 .IX Xref "I_SYS_RESOURCE"
8072 .IX Item "I_SYS_RESOURCE"
8073 This symbol, if defined, indicates to the C program that it should
8074 include \fIsys/resource.h\fR.
8075 .RS 4
8076 .Sp
8077 .Vb 3
8078 \& #ifdef I_SYS_RESOURCE
8079 \& #include <sys_resource.h>
8080 \& #endif
8081 .Ve
8082 .RE
8083 .RS 4
8084 .RE
8085 .ie n .IP """LIBM_LIB_VERSION""" 4
8086 .el .IP \f(CWLIBM_LIB_VERSION\fR 4
8087 .IX Xref "LIBM_LIB_VERSION"
8088 .IX Item "LIBM_LIB_VERSION"
8089 This symbol, if defined, indicates that libm exports \f(CW\*(C`_LIB_VERSION\*(C'\fR
8090 and that \fImath.h\fR defines the enum to manipulate it.
8091 .ie n .IP """NEED_VA_COPY""" 4
8092 .el .IP \f(CWNEED_VA_COPY\fR 4
8093 .IX Item "NEED_VA_COPY"
8094 This symbol, if defined, indicates that the system stores
8095 the variable argument list datatype, \f(CW\*(C`va_list\*(C'\fR, in a format
8096 that cannot be copied by simple assignment, so that some
8097 other means must be used when copying is required.
8098 As such systems vary in their provision (or non-provision)
8099 of copying mechanisms, \fIhandy.h\fR defines a platform\-
8100 independent macro, \f(CW\*(C`Perl_va_copy(src, dst)\*(C'\fR, to do the job.
8101 .ie n .IP """OSNAME""" 4
8102 .el .IP \f(CWOSNAME\fR 4
8103 .IX Xref "OSNAME"
8104 .IX Item "OSNAME"
8105 This symbol contains the name of the operating system, as determined
8106 by Configure. You shouldn't rely on it too much; the specific
8107 feature tests from Configure are generally more reliable.
8108 .ie n .IP """OSVERS""" 4
8109 .el .IP \f(CWOSVERS\fR 4
8110 .IX Xref "OSVERS"
8111 .IX Item "OSVERS"
8112 This symbol contains the version of the operating system, as determined
8113 by Configure. You shouldn't rely on it too much; the specific
8114 feature tests from Configure are generally more reliable.
8115 .ie n .IP """PERL_USE_GCC_BRACE_GROUPS""" 4
8116 .el .IP \f(CWPERL_USE_GCC_BRACE_GROUPS\fR 4
8117 .IX Xref "PERL_USE_GCC_BRACE_GROUPS"
8118 .IX Item "PERL_USE_GCC_BRACE_GROUPS"
8119 This C pre-processor value, if defined, indicates that it is permissible to use
8120 the GCC brace groups extension. However, use of this extension is DISCOURAGED.
8121 Use a \f(CW\*(C`static inline\*(C'\fR function instead.
8122 .Sp
8123 The extension, of the form
8124 .Sp
8125 .Vb 1
8126 \& ({ statement ... })
8127 .Ve
8128 .Sp
8129 turns the block consisting of \fIstatement ...\fR into an expression with a
8130 value, unlike plain C language blocks. This can present optimization
8131 possibilities, \fBBUT\fR, unless you know for sure that this will never be
8132 compiled without this extension being available and not forbidden, you need to
8133 specify an alternative. Thus two code paths have to be maintained, which can
8134 get out-of-sync. All these issues are solved by using a \f(CW\*(C`static inline\*(C'\fR
8135 function instead.
8136 .Sp
8137 Perl can be configured to not use this feature by passing the parameter
8138 \&\f(CW\*(C`\-Accflags=\-DPERL_GCC_BRACE_GROUPS_FORBIDDEN\*(C'\fR to \fIConfigure\fR.
8139 .RS 4
8140 .Sp
8141 .Vb 1
8142 \& #ifdef PERL_USE_GCC_BRACE_GROUPS
8143 .Ve
8144 .RE
8145 .RS 4
8146 .RE
8147 .ie n .IP """PHOSTNAME""" 4
8148 .el .IP \f(CWPHOSTNAME\fR 4
8149 .IX Xref "PHOSTNAME"
8150 .IX Item "PHOSTNAME"
8151 This symbol, if defined, indicates the command to feed to the
8152 \&\f(CWpopen()\fR routine to derive the host name. See also \f(CW"HAS_GETHOSTNAME"\fR
8153 and \f(CW"HAS_UNAME"\fR. Note that the command uses a fully qualified path,
8154 so that it is safe even if used by a process with super-user
8155 privileges.
8156 .ie n .IP """PROCSELFEXE_PATH""" 4
8157 .el .IP \f(CWPROCSELFEXE_PATH\fR 4
8158 .IX Xref "PROCSELFEXE_PATH"
8159 .IX Item "PROCSELFEXE_PATH"
8160 If \f(CW\*(C`HAS_PROCSELFEXE\*(C'\fR is defined this symbol is the filename
8161 of the symbolic link pointing to the absolute pathname of
8162 the executing program.
8163 .ie n .IP """PTRSIZE""" 4
8164 .el .IP \f(CWPTRSIZE\fR 4
8165 .IX Xref "PTRSIZE"
8166 .IX Item "PTRSIZE"
8167 This symbol contains the size of a pointer, so that the C preprocessor
8168 can make decisions based on it. It will be \f(CW\*(C`sizeof(void *)\*(C'\fR if
8169 the compiler supports (void *); otherwise it will be
8170 \&\f(CW\*(C`sizeof(char *)\*(C'\fR.
8171 .ie n .IP """RANDBITS""" 4
8172 .el .IP \f(CWRANDBITS\fR 4
8173 .IX Xref "RANDBITS"
8174 .IX Item "RANDBITS"
8175 This symbol indicates how many bits are produced by the
8176 function used to generate normalized random numbers.
8177 Values include 15, 16, 31, and 48.
8178 .ie n .IP """SELECT_MIN_BITS""" 4
8179 .el .IP \f(CWSELECT_MIN_BITS\fR 4
8180 .IX Xref "SELECT_MIN_BITS"
8181 .IX Item "SELECT_MIN_BITS"
8182 This symbol holds the minimum number of bits operated by select.
8183 That is, if you do \f(CW\*(C`select(n, ...)\*(C'\fR, how many bits at least will be
8184 cleared in the masks if some activity is detected. Usually this
8185 is either n or 32*\f(CWceil(n/32)\fR, especially many little-endians do
8186 the latter. This is only useful if you have \f(CWselect()\fR, naturally.
8187 .ie n .IP """SETUID_SCRIPTS_ARE_SECURE_NOW""" 4
8188 .el .IP \f(CWSETUID_SCRIPTS_ARE_SECURE_NOW\fR 4
8189 .IX Xref "SETUID_SCRIPTS_ARE_SECURE_NOW"
8190 .IX Item "SETUID_SCRIPTS_ARE_SECURE_NOW"
8191 This symbol, if defined, indicates that the bug that prevents
8192 setuid scripts from being secure is not present in this kernel.
8193 .ie n .IP """ST_DEV_SIGN""" 4
8194 .el .IP \f(CWST_DEV_SIGN\fR 4
8195 .IX Xref "ST_DEV_SIGN"
8196 .IX Item "ST_DEV_SIGN"
8197 This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_dev\*(C'\fR.
8198 1 for unsigned, \-1 for signed.
8199 .ie n .IP """ST_DEV_SIZE""" 4
8200 .el .IP \f(CWST_DEV_SIZE\fR 4
8201 .IX Xref "ST_DEV_SIZE"
8202 .IX Item "ST_DEV_SIZE"
8203 This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR's \f(CW\*(C`st_dev\*(C'\fR in bytes.
8204 .ie n .SS "List of capability ""HAS_\fIfoo\fP"" symbols"
8205 .el .SS "List of capability \f(CWHAS_\fP\f(CIfoo\fP\f(CW\fP symbols"
8206 .IX Subsection "List of capability HAS_foo symbols"
8207 This is a list of those symbols that dont appear elsewhere in ths
8208 document that indicate if the current platform has a certain
8209 capability. Their names all begin with \f(CW\*(C`HAS_\*(C'\fR. Only those
8210 symbols whose capability is directly derived from the name are
8211 listed here. All others have their meaning expanded out elsewhere
8212 in this document. This (relatively) compact list is because we
8213 think that the expansion would add little or no value and take up
8214 a lot of space (because there are so many). If you think certain
8215 ones should be expanded, send email to
8216 perl5\[email protected] <mailto:[email protected]>.
8217 .PP
8218 Each symbol here will be \f(CW\*(C`#define\*(C'\fRd if and only if the platform
8219 has the capability. If you need more detail, see the
8220 corresponding entry in \fIconfig.h\fR. For convenience, the list is
8221 split so that the ones that indicate there is a reentrant version
8222 of a capability are listed separately
8223 .PP
8224 \&\f(CW\*(C`HAS_ACCEPT4\*(C'\fR,\ \f(CW\*(C`HAS_ACCESS\*(C'\fR,\ \f(CW\*(C`HAS_ACCESSX\*(C'\fR,\ \f(CW\*(C`HAS_ACOSH\*(C'\fR,\ \f(CW\*(C`HAS_AINTL\*(C'\fR,\ \f(CW\*(C`HAS_ALARM\*(C'\fR,\ \f(CW\*(C`HAS_ASINH\*(C'\fR,\ \f(CW\*(C`HAS_ATANH\*(C'\fR,\ \f(CW\*(C`HAS_ATOLL\*(C'\fR,\ \f(CW\*(C`HAS_CBRT\*(C'\fR,\ \f(CW\*(C`HAS_CHOWN\*(C'\fR,\ \f(CW\*(C`HAS_CHROOT\*(C'\fR,\ \f(CW\*(C`HAS_CHSIZE\*(C'\fR,\ \f(CW\*(C`HAS_CLEARENV\*(C'\fR,\ \f(CW\*(C`HAS_COPYSIGN\*(C'\fR,\ \f(CW\*(C`HAS_COPYSIGNL\*(C'\fR,\ \f(CW\*(C`HAS_CRYPT\*(C'\fR,\ \f(CW\*(C`HAS_CTERMID\*(C'\fR,\ \f(CW\*(C`HAS_CUSERID\*(C'\fR,\ \f(CW\*(C`HAS_DIRFD\*(C'\fR,\ \f(CW\*(C`HAS_DLADDR\*(C'\fR,\ \f(CW\*(C`HAS_DLERROR\*(C'\fR,\ \f(CW\*(C`HAS_EACCESS\*(C'\fR,\ \f(CW\*(C`HAS_ENDHOSTENT\*(C'\fR,\ \f(CW\*(C`HAS_ENDNETENT\*(C'\fR,\ \f(CW\*(C`HAS_ENDPROTOENT\*(C'\fR,\ \f(CW\*(C`HAS_ENDSERVENT\*(C'\fR,\ \f(CW\*(C`HAS_ERF\*(C'\fR,\ \f(CW\*(C`HAS_ERFC\*(C'\fR,\ \f(CW\*(C`HAS_EXPM1\*(C'\fR,\ \f(CW\*(C`HAS_EXP2\*(C'\fR,\ \f(CW\*(C`HAS_FCHMOD\*(C'\fR,\ \f(CW\*(C`HAS_FCHMODAT\*(C'\fR,\ \f(CW\*(C`HAS_FCHOWN\*(C'\fR,\ \f(CW\*(C`HAS_FDIM\*(C'\fR,\ \f(CW\*(C`HAS_FD_SET\*(C'\fR,\ \f(CW\*(C`HAS_FEGETROUND\*(C'\fR,\ \f(CW\*(C`HAS_FFS\*(C'\fR,\ \f(CW\*(C`HAS_FFSL\*(C'\fR,\ \f(CW\*(C`HAS_FGETPOS\*(C'\fR,\ \f(CW\*(C`HAS_FLOCK\*(C'\fR,\ \f(CW\*(C`HAS_FMA\*(C'\fR,\ \f(CW\*(C`HAS_FMAX\*(C'\fR,\ \f(CW\*(C`HAS_FMIN\*(C'\fR,\ \f(CW\*(C`HAS_FORK\*(C'\fR,\ \f(CW\*(C`HAS_FSEEKO\*(C'\fR,\ \f(CW\*(C`HAS_FSETPOS\*(C'\fR,\ \f(CW\*(C`HAS_FSYNC\*(C'\fR,\ \f(CW\*(C`HAS_FTELLO\*(C'\fR,\ \f(CW\*(C`HAS_\|_FWALK\*(C'\fR,\ \f(CW\*(C`HAS_GAI_STRERROR\*(C'\fR,\ \f(CW\*(C`HAS_GETADDRINFO\*(C'\fR,\ \f(CW\*(C`HAS_GETCWD\*(C'\fR,\ \f(CW\*(C`HAS_GETESPWNAM\*(C'\fR,\ \f(CW\*(C`HAS_GETGROUPS\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYADDR\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTENT\*(C'\fR,\ \f(CW\*(C`HAS_GETLOGIN\*(C'\fR,\ \f(CW\*(C`HAS_GETNAMEINFO\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYADDR\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETNETENT\*(C'\fR,\ \f(CW\*(C`HAS_GETPAGESIZE\*(C'\fR,\ \f(CW\*(C`HAS_GETPGID\*(C'\fR,\ \f(CW\*(C`HAS_GETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_GETPGRP2\*(C'\fR,\ \f(CW\*(C`HAS_GETPPID\*(C'\fR,\ \f(CW\*(C`HAS_GETPRIORITY\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNUMBER\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOENT\*(C'\fR,\ \f(CW\*(C`HAS_GETPRPWNAM\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYNAME\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYPORT\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVENT\*(C'\fR,\ \f(CW\*(C`HAS_GETSPNAM\*(C'\fR,\ \f(CW\*(C`HAS_HTONL\*(C'\fR,\ \f(CW\*(C`HAS_HTONS\*(C'\fR,\ \f(CW\*(C`HAS_HYPOT\*(C'\fR,\ \f(CW\*(C`HAS_ILOGBL\*(C'\fR,\ \f(CW\*(C`HAS_INET_ATON\*(C'\fR,\ \f(CW\*(C`HAS_INETNTOP\*(C'\fR,\ \f(CW\*(C`HAS_INETPTON\*(C'\fR,\ \f(CW\*(C`HAS_IP_MREQ\*(C'\fR,\ \f(CW\*(C`HAS_IP_MREQ_SOURCE\*(C'\fR,\ \f(CW\*(C`HAS_IPV6_MREQ\*(C'\fR,\ \f(CW\*(C`HAS_IPV6_MREQ_SOURCE\*(C'\fR,\ \f(CW\*(C`HAS_ISASCII\*(C'\fR,\ \f(CW\*(C`HAS_ISBLANK\*(C'\fR,\ \f(CW\*(C`HAS_ISLESS\*(C'\fR,\ \f(CW\*(C`HAS_KILLPG\*(C'\fR,\ \f(CW\*(C`HAS_LCHOWN\*(C'\fR,\ \f(CW\*(C`HAS_LINK\*(C'\fR,\ \f(CW\*(C`HAS_LINKAT\*(C'\fR,\ \f(CW\*(C`HAS_LLROUND\*(C'\fR,\ \f(CW\*(C`HAS_LOCKF\*(C'\fR,\ \f(CW\*(C`HAS_LOGB\*(C'\fR,\ \f(CW\*(C`HAS_LOG1P\*(C'\fR,\ \f(CW\*(C`HAS_LOG2\*(C'\fR,\ \f(CW\*(C`HAS_LROUND\*(C'\fR,\ \f(CW\*(C`HAS_LSTAT\*(C'\fR,\ \f(CW\*(C`HAS_MADVISE\*(C'\fR,\ \f(CW\*(C`HAS_MBLEN\*(C'\fR,\ \f(CW\*(C`HAS_MBRLEN\*(C'\fR,\ \f(CW\*(C`HAS_MBRTOWC\*(C'\fR,\ \f(CW\*(C`HAS_MBSTOWCS\*(C'\fR,\ \f(CW\*(C`HAS_MBTOWC\*(C'\fR,\ \f(CW\*(C`HAS_MEMMEM\*(C'\fR,\ \f(CW\*(C`HAS_MEMRCHR\*(C'\fR,\ \f(CW\*(C`HAS_MKDTEMP\*(C'\fR,\ \f(CW\*(C`HAS_MKFIFO\*(C'\fR,\ \f(CW\*(C`HAS_MKOSTEMP\*(C'\fR,\ \f(CW\*(C`HAS_MKSTEMP\*(C'\fR,\ \f(CW\*(C`HAS_MKSTEMPS\*(C'\fR,\ \f(CW\*(C`HAS_MMAP\*(C'\fR,\ \f(CW\*(C`HAS_MPROTECT\*(C'\fR,\ \f(CW\*(C`HAS_MSG\*(C'\fR,\ \f(CW\*(C`HAS_MSYNC\*(C'\fR,\ \f(CW\*(C`HAS_MUNMAP\*(C'\fR,\ \f(CW\*(C`HAS_NEARBYINT\*(C'\fR,\ \f(CW\*(C`HAS_NEXTAFTER\*(C'\fR,\ \f(CW\*(C`HAS_NICE\*(C'\fR,\ \f(CW\*(C`HAS_NTOHL\*(C'\fR,\ \f(CW\*(C`HAS_NTOHS\*(C'\fR,\ \f(CW\*(C`HAS_PATHCONF\*(C'\fR,\ \f(CW\*(C`HAS_PAUSE\*(C'\fR,\ \f(CW\*(C`HAS_PHOSTNAME\*(C'\fR,\ \f(CW\*(C`HAS_PIPE\*(C'\fR,\ \f(CW\*(C`HAS_PIPE2\*(C'\fR,\ \f(CW\*(C`HAS_PRCTL\*(C'\fR,\ \f(CW\*(C`HAS_PTRDIFF_T\*(C'\fR,\ \f(CW\*(C`HAS_READLINK\*(C'\fR,\ \f(CW\*(C`HAS_READV\*(C'\fR,\ \f(CW\*(C`HAS_RECVMSG\*(C'\fR,\ \f(CW\*(C`HAS_REMQUO\*(C'\fR,\ \f(CW\*(C`HAS_RENAME\*(C'\fR,\ \f(CW\*(C`HAS_RENAMEAT\*(C'\fR,\ \f(CW\*(C`HAS_RINT\*(C'\fR,\ \f(CW\*(C`HAS_ROUND\*(C'\fR,\ \f(CW\*(C`HAS_SCALBNL\*(C'\fR,\ \f(CW\*(C`HAS_SEM\*(C'\fR,\ \f(CW\*(C`HAS_SENDMSG\*(C'\fR,\ \f(CW\*(C`HAS_SETEGID\*(C'\fR,\ \f(CW\*(C`HAS_SETENV\*(C'\fR,\ \f(CW\*(C`HAS_SETEUID\*(C'\fR,\ \f(CW\*(C`HAS_SETGROUPS\*(C'\fR,\ \f(CW\*(C`HAS_SETHOSTENT\*(C'\fR,\ \f(CW\*(C`HAS_SETLINEBUF\*(C'\fR,\ \f(CW\*(C`HAS_SETNETENT\*(C'\fR,\ \f(CW\*(C`HAS_SETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_SETPGRP2\*(C'\fR,\ \f(CW\*(C`HAS_SETPRIORITY\*(C'\fR,\ \f(CW\*(C`HAS_SETPROCTITLE\*(C'\fR,\ \f(CW\*(C`HAS_SETPROTOENT\*(C'\fR,\ \f(CW\*(C`HAS_SETREGID\*(C'\fR,\ \f(CW\*(C`HAS_SETRESGID\*(C'\fR,\ \f(CW\*(C`HAS_SETRESUID\*(C'\fR,\ \f(CW\*(C`HAS_SETREUID\*(C'\fR,\ \f(CW\*(C`HAS_SETRGID\*(C'\fR,\ \f(CW\*(C`HAS_SETRUID\*(C'\fR,\ \f(CW\*(C`HAS_SETSERVENT\*(C'\fR,\ \f(CW\*(C`HAS_SETSID\*(C'\fR,\ \f(CW\*(C`HAS_SHM\*(C'\fR,\ \f(CW\*(C`HAS_SIGACTION\*(C'\fR,\ \f(CW\*(C`HAS_SIGPROCMASK\*(C'\fR,\ \f(CW\*(C`HAS_SIN6_SCOPE_ID\*(C'\fR,\ \f(CW\*(C`HAS_SNPRINTF\*(C'\fR,\ \f(CW\*(C`HAS_STAT\*(C'\fR,\ \f(CW\*(C`HAS_STRCOLL\*(C'\fR,\ \f(CW\*(C`HAS_STRERROR_L\*(C'\fR,\ \f(CW\*(C`HAS_STRLCAT\*(C'\fR,\ \f(CW\*(C`HAS_STRLCPY\*(C'\fR,\ \f(CW\*(C`HAS_STRNLEN\*(C'\fR,\ \f(CW\*(C`HAS_STRTOD\*(C'\fR,\ \f(CW\*(C`HAS_STRTOL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOLL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOQ\*(C'\fR,\ \f(CW\*(C`HAS_STRTOUL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOULL\*(C'\fR,\ \f(CW\*(C`HAS_STRTOUQ\*(C'\fR,\ \f(CW\*(C`HAS_STRXFRM\*(C'\fR,\ \f(CW\*(C`HAS_STRXFRM_L\*(C'\fR,\ \f(CW\*(C`HAS_SYMLINK\*(C'\fR,\ \f(CW\*(C`HAS_SYSCALL\*(C'\fR,\ \f(CW\*(C`HAS_SYSCONF\*(C'\fR,\ \f(CW\*(C`HAS_SYS_ERRLIST\*(C'\fR,\ \f(CW\*(C`HAS_SYSTEM\*(C'\fR,\ \f(CW\*(C`HAS_TCGETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_TCSETPGRP\*(C'\fR,\ \f(CW\*(C`HAS_TOWLOWER\*(C'\fR,\ \f(CW\*(C`HAS_TOWUPPER\*(C'\fR,\ \f(CW\*(C`HAS_TRUNCATE\*(C'\fR,\ \f(CW\*(C`HAS_TRUNCL\*(C'\fR,\ \f(CW\*(C`HAS_UALARM\*(C'\fR,\ \f(CW\*(C`HAS_UMASK\*(C'\fR,\ \f(CW\*(C`HAS_UNLINKAT\*(C'\fR,\ \f(CW\*(C`HAS_UNSETENV\*(C'\fR,\ \f(CW\*(C`HAS_VFORK\*(C'\fR,\ \f(CW\*(C`HAS_VSNPRINTF\*(C'\fR,\ \f(CW\*(C`HAS_WAITPID\*(C'\fR,\ \f(CW\*(C`HAS_WAIT4\*(C'\fR,\ \f(CW\*(C`HAS_WCRTOMB\*(C'\fR,\ \f(CW\*(C`HAS_WCSCMP\*(C'\fR,\ \f(CW\*(C`HAS_WCSTOMBS\*(C'\fR,\ \f(CW\*(C`HAS_WCSXFRM\*(C'\fR,\ \f(CW\*(C`HAS_WCTOMB\*(C'\fR,\ \f(CW\*(C`HAS_WRITEV\*(C'\fR
8225 .PP
8226 And, the reentrant capabilities:
8227 .PP
8228 \&\f(CW\*(C`HAS_CRYPT_R\*(C'\fR,\ \f(CW\*(C`HAS_CTERMID_R\*(C'\fR,\ \f(CW\*(C`HAS_DRAND48_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDHOSTENT_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDNETENT_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDPROTOENT_R\*(C'\fR,\ \f(CW\*(C`HAS_ENDSERVENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETGRGID_R\*(C'\fR,\ \f(CW\*(C`HAS_GETGRNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYADDR_R\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETHOSTENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETLOGIN_R\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYADDR_R\*(C'\fR,\ \f(CW\*(C`HAS_GETNETBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETNETENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOBYNUMBER_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPROTOENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPWNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_GETPWUID_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYNAME_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVBYPORT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSERVENT_R\*(C'\fR,\ \f(CW\*(C`HAS_GETSPNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_RANDOM_R\*(C'\fR,\ \f(CW\*(C`HAS_READDIR_R\*(C'\fR,\ \f(CW\*(C`HAS_SETHOSTENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SETNETENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SETPROTOENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SETSERVENT_R\*(C'\fR,\ \f(CW\*(C`HAS_SRANDOM_R\*(C'\fR,\ \f(CW\*(C`HAS_SRAND48_R\*(C'\fR,\ \f(CW\*(C`HAS_STRERROR_R\*(C'\fR,\ \f(CW\*(C`HAS_TMPNAM_R\*(C'\fR,\ \f(CW\*(C`HAS_TTYNAME_R\*(C'\fR
8229 .PP
8230 Example usage:
8231 .Sp
8232 .Vb 5
8233 \& #ifdef HAS_STRNLEN
8234 \& use strnlen()
8235 \& #else
8236 \& use an alternative implementation
8237 \& #endif
8238 .Ve
8239 .ie n .SS "List of ""#include"" needed symbols"
8240 .el .SS "List of \f(CW#include\fP needed symbols"
8241 .IX Subsection "List of #include needed symbols"
8242 This list contains symbols that indicate if certain \f(CW\*(C`#include\*(C'\fR
8243 files are present on the platform. If your code accesses the
8244 functionality that one of these is for, you will need to
8245 \&\f(CW\*(C`#include\*(C'\fR it if the symbol on this list is \f(CW\*(C`#define\*(C'\fRd. For
8246 more detail, see the corresponding entry in \fIconfig.h\fR.
8247 .PP
8248 \&\f(CW\*(C`I_ARPA_INET\*(C'\fR,\ \f(CW\*(C`I_BFD\*(C'\fR,\ \f(CW\*(C`I_CRYPT\*(C'\fR,\ \f(CW\*(C`I_DBM\*(C'\fR,\ \f(CW\*(C`I_DLFCN\*(C'\fR,\ \f(CW\*(C`I_EXECINFO\*(C'\fR,\ \f(CW\*(C`I_FP\*(C'\fR,\ \f(CW\*(C`I_FP_CLASS\*(C'\fR,\ \f(CW\*(C`I_GDBM\*(C'\fR,\ \f(CW\*(C`I_GDBMNDBM\*(C'\fR,\ \f(CW\*(C`I_GDBM_NDBM\*(C'\fR,\ \f(CW\*(C`I_GRP\*(C'\fR,\ \f(CW\*(C`I_IEEEFP\*(C'\fR,\ \f(CW\*(C`I_INTTYPES\*(C'\fR,\ \f(CW\*(C`I_LIBUTIL\*(C'\fR,\ \f(CW\*(C`I_MNTENT\*(C'\fR,\ \f(CW\*(C`I_NDBM\*(C'\fR,\ \f(CW\*(C`I_NETDB\*(C'\fR,\ \f(CW\*(C`I_NET_ERRNO\*(C'\fR,\ \f(CW\*(C`I_NETINET_IN\*(C'\fR,\ \f(CW\*(C`I_NETINET_TCP\*(C'\fR,\ \f(CW\*(C`I_PROT\*(C'\fR,\ \f(CW\*(C`I_PWD\*(C'\fR,\ \f(CW\*(C`I_RPCSVC_DBM\*(C'\fR,\ \f(CW\*(C`I_SGTTY\*(C'\fR,\ \f(CW\*(C`I_SHADOW\*(C'\fR,\ \f(CW\*(C`I_STDBOOL\*(C'\fR,\ \f(CW\*(C`I_STDINT\*(C'\fR,\ \f(CW\*(C`I_SUNMATH\*(C'\fR,\ \f(CW\*(C`I_SYS_ACCESS\*(C'\fR,\ \f(CW\*(C`I_SYS_IOCTL\*(C'\fR,\ \f(CW\*(C`I_SYSLOG\*(C'\fR,\ \f(CW\*(C`I_SYSMODE\*(C'\fR,\ \f(CW\*(C`I_SYS_MOUNT\*(C'\fR,\ \f(CW\*(C`I_SYS_PARAM\*(C'\fR,\ \f(CW\*(C`I_SYS_POLL\*(C'\fR,\ \f(CW\*(C`I_SYS_SECURITY\*(C'\fR,\ \f(CW\*(C`I_SYS_SELECT\*(C'\fR,\ \f(CW\*(C`I_SYS_STAT\*(C'\fR,\ \f(CW\*(C`I_SYS_STATVFS\*(C'\fR,\ \f(CW\*(C`I_SYS_SYSCALL\*(C'\fR,\ \f(CW\*(C`I_SYS_TIME\*(C'\fR,\ \f(CW\*(C`I_SYS_TIME_KERNEL\*(C'\fR,\ \f(CW\*(C`I_SYS_TIMES\*(C'\fR,\ \f(CW\*(C`I_SYS_TYPES\*(C'\fR,\ \f(CW\*(C`I_SYSUIO\*(C'\fR,\ \f(CW\*(C`I_SYS_UN\*(C'\fR,\ \f(CW\*(C`I_SYSUTSNAME\*(C'\fR,\ \f(CW\*(C`I_SYS_VFS\*(C'\fR,\ \f(CW\*(C`I_SYS_WAIT\*(C'\fR,\ \f(CW\*(C`I_TERMIO\*(C'\fR,\ \f(CW\*(C`I_TERMIOS\*(C'\fR,\ \f(CW\*(C`I_UNISTD\*(C'\fR,\ \f(CW\*(C`I_USTAT\*(C'\fR,\ \f(CW\*(C`I_VFORK\*(C'\fR,\ \f(CW\*(C`I_WCHAR\*(C'\fR,\ \f(CW\*(C`I_WCTYPE\*(C'\fR
8249 .PP
8250 Example usage:
8251 .Sp
8252 .Vb 3
8253 \& #ifdef I_WCHAR
8254 \& #include <wchar.h>
8255 \& #endif
8256 .Ve
8257 .SH "Global Variables"
8258 .IX Header "Global Variables"
8259 These variables are global to an entire process. They are shared between
8260 all interpreters and all threads in a process. Any variables not documented
8261 here may be changed or removed without notice, so don't use them!
8262 If you feel you really do need to use an unlisted variable, first send email to
8263 perl5\[email protected] <mailto:[email protected]>. It may be that
8264 someone there will point out a way to accomplish what you need without using an
8265 internal variable. But if not, you should get a go-ahead to document and then
8266 use the variable.
8267 .ie n .IP """PL_check""" 4
8268 .el .IP \f(CWPL_check\fR 4
8269 .IX Xref "PL_check"
8270 .IX Item "PL_check"
8271 Array, indexed by opcode, of functions that will be called for the "check"
8272 phase of optree building during compilation of Perl code. For most (but
8273 not all) types of op, once the op has been initially built and populated
8274 with child ops it will be filtered through the check function referenced
8275 by the appropriate element of this array. The new op is passed in as the
8276 sole argument to the check function, and the check function returns the
8277 completed op. The check function may (as the name suggests) check the op
8278 for validity and signal errors. It may also initialise or modify parts of
8279 the ops, or perform more radical surgery such as adding or removing child
8280 ops, or even throw the op away and return a different op in its place.
8281 .Sp
8282 This array of function pointers is a convenient place to hook into the
8283 compilation process. An XS module can put its own custom check function
8284 in place of any of the standard ones, to influence the compilation of a
8285 particular type of op. However, a custom check function must never fully
8286 replace a standard check function (or even a custom check function from
8287 another module). A module modifying checking must instead \fBwrap\fR the
8288 preexisting check function. A custom check function must be selective
8289 about when to apply its custom behaviour. In the usual case where
8290 it decides not to do anything special with an op, it must chain the
8291 preexisting op function. Check functions are thus linked in a chain,
8292 with the core's base checker at the end.
8293 .Sp
8294 For thread safety, modules should not write directly to this array.
8295 Instead, use the function "wrap_op_checker".
8296 .ie n .IP """PL_infix_plugin""" 4
8297 .el .IP \f(CWPL_infix_plugin\fR 4
8298 .IX Xref "PL_infix_plugin"
8299 .IX Item "PL_infix_plugin"
8300 NOTE: \f(CW\*(C`PL_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be
8301 removed without notice.
8302 .Sp
8303 \&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module
8304 \&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make
8305 use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing
8306 of new infix operators.
8307 .Sp
8308 Function pointer, pointing at a function used to handle extended infix
8309 operators. The function should be declared as
8310 .Sp
8311 .Vb 3
8312 \& int infix_plugin_function(pTHX_
8313 \& char *opname, STRLEN oplen,
8314 \& struct Perl_custom_infix **infix_ptr)
8315 .Ve
8316 .Sp
8317 The function is called from the tokenizer whenever a possible infix operator
8318 is seen. \f(CW\*(C`opname\*(C'\fR points to the operator name in the parser's input buffer,
8319 and \f(CW\*(C`oplen\*(C'\fR gives the \fImaximum\fR number of bytes of it that should be
8320 consumed; it is not null-terminated. The function is expected to examine the
8321 operator name and possibly other state such as %^H, to
8322 determine whether it wants to handle the operator name.
8323 .Sp
8324 As compared to the single stage of \f(CW\*(C`PL_keyword_plugin\*(C'\fR, parsing of additional
8325 infix operators occurs in three separate stages. This is because of the more
8326 complex interactions it has with the parser, to ensure that operator
8327 precedence rules work correctly. These stages are co-ordinated by the use of
8328 an additional information structure.
8329 .Sp
8330 If the function wants to handle the infix operator, it must set the variable
8331 pointed to by \f(CW\*(C`infix_ptr\*(C'\fR to the address of a structure that provides this
8332 additional information about the subsequent parsing stages. If it does not,
8333 it should make a call to the next function in the chain.
8334 .Sp
8335 This structure has the following definition:
8336 .Sp
8337 .Vb 7
8338 \& struct Perl_custom_infix {
8339 \& enum Perl_custom_infix_precedence prec;
8340 \& void (*parse)(pTHX_ SV **opdata,
8341 \& struct Perl_custom_infix *);
8342 \& OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs,
8343 \& struct Perl_custom_infix *);
8344 \& };
8345 .Ve
8346 .Sp
8347 The function must then return an integer giving the number of bytes consumed
8348 by the name of this operator. In the case of an operator whose name is
8349 composed of identifier characters, this must be equal to \f(CW\*(C`oplen\*(C'\fR. In the case
8350 of an operator named by non-identifier characters, this is permitted to be
8351 shorter than \f(CW\*(C`oplen\*(C'\fR, and any additional characters after it will not be
8352 claimed by the infix operator but instead will be consumed by the tokenizer
8353 and parser as normal.
8354 .Sp
8355 If the optional \f(CW\*(C`parse\*(C'\fR function is provided, it is called immediately by the
8356 parser to let the operator's definition consume any additional syntax from the
8357 source code. This should \fInot\fR be used for normal operand parsing, but it may
8358 be useful when implementing things like parametric operators or meta-operators
8359 that consume more syntax themselves. This function may use the variable
8360 pointed to by \f(CW\*(C`opdata\*(C'\fR to provide an SV containing additional data to be
8361 passed into the \f(CW\*(C`build_op\*(C'\fR function later on.
8362 .Sp
8363 The information structure gives the operator precedence level in the \f(CW\*(C`prec\*(C'\fR
8364 field. This is used to tell the parser how much of the surrounding syntax
8365 before and after should be considered as operands to the operator.
8366 .Sp
8367 The tokenizer and parser will then continue to operate as normal until enough
8368 additional input has been parsed to form both the left\- and right-hand side
8369 operands to the operator, according to the precedence level. At this point the
8370 \&\f(CW\*(C`build_op\*(C'\fR function is called, being passed the left\- and right-hand operands
8371 as optree fragments. It is expected to combine them into the resulting optree
8372 fragment, which it should return.
8373 .Sp
8374 After the \f(CW\*(C`build_op\*(C'\fR function has returned, if the variable pointed to by
8375 \&\f(CW\*(C`opdata\*(C'\fR was set to a non\-\f(CW\*(C`NULL\*(C'\fR value, it will then be destroyed by calling
8376 \&\f(CWSvREFCNT_dec()\fR.
8377 .Sp
8378 For thread safety, modules should not set this variable directly.
8379 Instead, use the function "wrap_infix_plugin".
8380 .Sp
8381 However, that all said, the introductory note above still applies. This
8382 variable is provided in core perl only for the benefit of the
8383 \&\f(CW\*(C`XS::Parse::Infix\*(C'\fR module. That module acts as a central registry for infix
8384 operators, automatically handling things like deparse support and
8385 discovery/reflection, and these abilities only work because it knows all the
8386 registered operators. Other modules should not use this interpreter variable
8387 directly to implement them because then those central features would no longer
8388 work properly.
8389 .Sp
8390 Furthermore, it is likely that this (experimental) API will be replaced in a
8391 future Perl version by a more complete API that fully implements the central
8392 registry and other semantics currently provided by \f(CW\*(C`XS::Parse::Infix\*(C'\fR, once
8393 the module has had sufficient experimental testing time. This current
8394 mechanism exists only as an interim measure to get to that stage.
8395 .ie n .IP """PL_keyword_plugin""" 4
8396 .el .IP \f(CWPL_keyword_plugin\fR 4
8397 .IX Xref "PL_keyword_plugin"
8398 .IX Item "PL_keyword_plugin"
8399 NOTE: \f(CW\*(C`PL_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be
8400 removed without notice.
8401 .Sp
8402 Function pointer, pointing at a function used to handle extended keywords.
8403 The function should be declared as
8404 .Sp
8405 .Vb 3
8406 \& int keyword_plugin_function(pTHX_
8407 \& char *keyword_ptr, STRLEN keyword_len,
8408 \& OP **op_ptr)
8409 .Ve
8410 .Sp
8411 The function is called from the tokeniser, whenever a possible keyword
8412 is seen. \f(CW\*(C`keyword_ptr\*(C'\fR points at the word in the parser's input
8413 buffer, and \f(CW\*(C`keyword_len\*(C'\fR gives its length; it is not null-terminated.
8414 The function is expected to examine the word, and possibly other state
8415 such as %^H, to decide whether it wants to handle it
8416 as an extended keyword. If it does not, the function should return
8417 \&\f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR, and the normal parser process will continue.
8418 .Sp
8419 If the function wants to handle the keyword, it first must
8420 parse anything following the keyword that is part of the syntax
8421 introduced by the keyword. See "Lexer interface" for details.
8422 .Sp
8423 When a keyword is being handled, the plugin function must build
8424 a tree of \f(CW\*(C`OP\*(C'\fR structures, representing the code that was parsed.
8425 The root of the tree must be stored in \f(CW*op_ptr\fR. The function then
8426 returns a constant indicating the syntactic role of the construct that
8427 it has parsed: \f(CW\*(C`KEYWORD_PLUGIN_STMT\*(C'\fR if it is a complete statement, or
8428 \&\f(CW\*(C`KEYWORD_PLUGIN_EXPR\*(C'\fR if it is an expression. Note that a statement
8429 construct cannot be used inside an expression (except via \f(CW\*(C`do BLOCK\*(C'\fR
8430 and similar), and an expression is not a complete statement (it requires
8431 at least a terminating semicolon).
8432 .Sp
8433 When a keyword is handled, the plugin function may also have
8434 (compile-time) side effects. It may modify \f(CW\*(C`%^H\*(C'\fR, define functions, and
8435 so on. Typically, if side effects are the main purpose of a handler,
8436 it does not wish to generate any ops to be included in the normal
8437 compilation. In this case it is still required to supply an op tree,
8438 but it suffices to generate a single null op.
8439 .Sp
8440 That's how the \f(CW*PL_keyword_plugin\fR function needs to behave overall.
8441 Conventionally, however, one does not completely replace the existing
8442 handler function. Instead, take a copy of \f(CW\*(C`PL_keyword_plugin\*(C'\fR before
8443 assigning your own function pointer to it. Your handler function should
8444 look for keywords that it is interested in and handle those. Where it
8445 is not interested, it should call the saved plugin function, passing on
8446 the arguments it received. Thus \f(CW\*(C`PL_keyword_plugin\*(C'\fR actually points
8447 at a chain of handler functions, all of which have an opportunity to
8448 handle keywords, and only the last function in the chain (built into
8449 the Perl core) will normally return \f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR.
8450 .Sp
8451 For thread safety, modules should not set this variable directly.
8452 Instead, use the function "wrap_keyword_plugin".
8453 .ie n .IP """PL_phase""" 4
8454 .el .IP \f(CWPL_phase\fR 4
8455 .IX Xref "PL_phase"
8456 .IX Item "PL_phase"
8457 A value that indicates the current Perl interpreter's phase. Possible values
8458 include \f(CW\*(C`PERL_PHASE_CONSTRUCT\*(C'\fR, \f(CW\*(C`PERL_PHASE_START\*(C'\fR, \f(CW\*(C`PERL_PHASE_CHECK\*(C'\fR,
8459 \&\f(CW\*(C`PERL_PHASE_INIT\*(C'\fR, \f(CW\*(C`PERL_PHASE_RUN\*(C'\fR, \f(CW\*(C`PERL_PHASE_END\*(C'\fR, and
8460 \&\f(CW\*(C`PERL_PHASE_DESTRUCT\*(C'\fR.
8461 .Sp
8462 For example, the following determines whether the interpreter is in
8463 global destruction:
8464 .Sp
8465 .Vb 3
8466 \& if (PL_phase == PERL_PHASE_DESTRUCT) {
8467 \& // we are in global destruction
8468 \& }
8469 .Ve
8470 .Sp
8471 \&\f(CW\*(C`PL_phase\*(C'\fR was introduced in Perl 5.14; in prior perls you can use
8472 \&\f(CW\*(C`PL_dirty\*(C'\fR (boolean) to determine whether the interpreter is in global
8473 destruction. (Use of \f(CW\*(C`PL_dirty\*(C'\fR is discouraged since 5.14.)
8474 .RS 4
8475 .Sp
8476 .Vb 1
8477 \& enum perl_phase PL_phase
8478 .Ve
8479 .RE
8480 .RS 4
8481 .RE
8482 .SH "GV Handling and Stashes"
8483 .IX Xref "GV GV_ADD GV_ADDMG GV_ADDMULTI GV_ADDWARN GV_NOADD_NOINIT GV_NOEXPAND GV_NOINIT GV_NOTQUAL GV_NO_SVGMAGIC GV_SUPER SVf_UTF8"
8484 .IX Header "GV Handling and Stashes"
8485 A GV is a structure which corresponds to a Perl typeglob, ie *foo.
8486 It is a structure that holds a pointer to a scalar, an array, a hash etc,
8487 corresponding to \f(CW$foo\fR, \f(CW@foo\fR, \f(CW%foo\fR.
8488 .PP
8489 GVs are usually found as values in stashes (symbol table hashes) where
8490 Perl stores its global variables.
8491 .PP
8492 A \fBstash\fR is a hash that contains all variables that are defined
8493 within a package. See "Stashes and Globs" in perlguts
8494 .ie n .IP """amagic_call""" 4
8495 .el .IP \f(CWamagic_call\fR 4
8496 .IX Xref "amagic_call"
8497 .IX Item "amagic_call"
8498 Perform the overloaded (active magic) operation given by \f(CW\*(C`method\*(C'\fR.
8499 \&\f(CW\*(C`method\*(C'\fR is one of the values found in \fIoverload.h\fR.
8500 .Sp
8501 \&\f(CW\*(C`flags\*(C'\fR affects how the operation is performed, as follows:
8502 .RS 4
8503 .ie n .IP """AMGf_noleft""" 4
8504 .el .IP \f(CWAMGf_noleft\fR 4
8505 .IX Item "AMGf_noleft"
8506 \&\f(CW\*(C`left\*(C'\fR is not to be used in this operation.
8507 .ie n .IP """AMGf_noright""" 4
8508 .el .IP \f(CWAMGf_noright\fR 4
8509 .IX Item "AMGf_noright"
8510 \&\f(CW\*(C`right\*(C'\fR is not to be used in this operation.
8511 .ie n .IP """AMGf_unary""" 4
8512 .el .IP \f(CWAMGf_unary\fR 4
8513 .IX Item "AMGf_unary"
8514 The operation is done only on just one operand.
8515 .ie n .IP """AMGf_assign""" 4
8516 .el .IP \f(CWAMGf_assign\fR 4
8517 .IX Item "AMGf_assign"
8518 The operation changes one of the operands, e.g., \f(CW$x\fR += 1
8519 .RE
8520 .RS 4
8521 .Sp
8522 .Vb 1
8523 \& SV * amagic_call(SV *left, SV *right, int method, int dir)
8524 .Ve
8525 .RE
8526 .RS 4
8527 .RE
8528 .ie n .IP """amagic_deref_call""" 4
8529 .el .IP \f(CWamagic_deref_call\fR 4
8530 .IX Xref "amagic_deref_call"
8531 .IX Item "amagic_deref_call"
8532 Perform \f(CW\*(C`method\*(C'\fR overloading dereferencing on \f(CW\*(C`ref\*(C'\fR, returning the
8533 dereferenced result. \f(CW\*(C`method\*(C'\fR must be one of the dereference operations given
8534 in \fIoverload.h\fR.
8535 .Sp
8536 If overloading is inactive on \f(CW\*(C`ref\*(C'\fR, returns \f(CW\*(C`ref\*(C'\fR itself.
8537 .RS 4
8538 .Sp
8539 .Vb 1
8540 \& SV * amagic_deref_call(SV *ref, int method)
8541 .Ve
8542 .RE
8543 .RS 4
8544 .RE
8545 .ie n .IP """gv_add_by_type""" 4
8546 .el .IP \f(CWgv_add_by_type\fR 4
8547 .IX Xref "gv_add_by_type"
8548 .IX Item "gv_add_by_type"
8549 Make sure there is a slot of type \f(CW\*(C`type\*(C'\fR in the GV \f(CW\*(C`gv\*(C'\fR.
8550 .RS 4
8551 .Sp
8552 .Vb 1
8553 \& GV * gv_add_by_type(GV *gv, svtype type)
8554 .Ve
8555 .RE
8556 .RS 4
8557 .RE
8558 .ie n .IP """Gv_AMupdate""" 4
8559 .el .IP \f(CWGv_AMupdate\fR 4
8560 .IX Xref "Gv_AMupdate"
8561 .IX Item "Gv_AMupdate"
8562 Recalculates overload magic in the package given by \f(CW\*(C`stash\*(C'\fR.
8563 .Sp
8564 Returns:
8565 .RS 4
8566 .IP "1 on success and there is some overload" 4
8567 .IX Item "1 on success and there is some overload"
8568 .PD 0
8569 .IP "0 if there is no overload" 4
8570 .IX Item "0 if there is no overload"
8571 .ie n .IP "\-1 if some error occurred and it couldn't croak (because ""destructing"" is true)." 4
8572 .el .IP "\-1 if some error occurred and it couldn't croak (because \f(CWdestructing\fR is true)." 4
8573 .IX Item "-1 if some error occurred and it couldn't croak (because destructing is true)."
8574 .RE
8575 .RS 4
8576 .PD
8577 .Sp
8578 .Vb 1
8579 \& int Gv_AMupdate(HV *stash, bool destructing)
8580 .Ve
8581 .RE
8582 .RS 4
8583 .RE
8584 .ie n .IP """gv_autoload_pv""" 4
8585 .el .IP \f(CWgv_autoload_pv\fR 4
8586 .IX Item "gv_autoload_pv"
8587 .PD 0
8588 .ie n .IP """gv_autoload_pvn""" 4
8589 .el .IP \f(CWgv_autoload_pvn\fR 4
8590 .IX Item "gv_autoload_pvn"
8591 .ie n .IP """gv_autoload_sv""" 4
8592 .el .IP \f(CWgv_autoload_sv\fR 4
8593 .IX Xref "gv_autoload_pv gv_autoload_pvn gv_autoload_sv"
8594 .IX Item "gv_autoload_sv"
8595 .PD
8596 These each search for an \f(CW\*(C`AUTOLOAD\*(C'\fR method, returning NULL if not found, or
8597 else returning a pointer to its GV, while setting the package
8598 \&\f(CW$AUTOLOAD\fR variable to \f(CW\*(C`name\*(C'\fR (fully qualified). Also,
8599 if found and the GV's CV is an XSUB, the CV's PV will be set to \f(CW\*(C`name\*(C'\fR, and
8600 its stash will be set to the stash of the GV.
8601 .Sp
8602 Searching is done in \f(CW\*(C`MRO\*(C'\fR order, as specified in
8603 "\f(CW\*(C`gv_fetchmeth\*(C'\fR", beginning with \f(CW\*(C`stash\*(C'\fR if it isn't NULL.
8604 .Sp
8605 The forms differ only in how \f(CW\*(C`name\*(C'\fR is specified.
8606 .Sp
8607 In \f(CW\*(C`gv_autoload_pv\*(C'\fR, \f(CW\*(C`namepv\*(C'\fR is a C language NUL-terminated string.
8608 .Sp
8609 In \f(CW\*(C`gv_autoload_pvn\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an
8610 additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, \f(CW*name\fR
8611 may contain embedded-NUL characters.
8612 .Sp
8613 In \f(CW\*(C`gv_autoload_sv\*(C'\fR, \f(CW*namesv\fR is an SV, and the name is the PV extracted
8614 from that using "\f(CW\*(C`SvPV\*(C'\fR". If the SV is marked as being in UTF\-8, the
8615 extracted PV will also be.
8616 .RS 4
8617 .Sp
8618 .Vb 4
8619 \& GV * gv_autoload_pv (HV *stash, const char *namepv, U32 flags)
8620 \& GV * gv_autoload_pvn(HV *stash, const char *name, STRLEN len,
8621 \& U32 flags)
8622 \& GV * gv_autoload_sv (HV *stash, SV *namesv, U32 flags)
8623 .Ve
8624 .RE
8625 .RS 4
8626 .RE
8627 .ie n .IP """gv_autoload4""" 4
8628 .el .IP \f(CWgv_autoload4\fR 4
8629 .IX Xref "gv_autoload4"
8630 .IX Item "gv_autoload4"
8631 Equivalent to \f(CW"gv_autoload_pvn"\fR.
8632 .RS 4
8633 .Sp
8634 .Vb 2
8635 \& GV * gv_autoload4(HV *stash, const char *name, STRLEN len,
8636 \& I32 method)
8637 .Ve
8638 .RE
8639 .RS 4
8640 .RE
8641 .ie n .IP """GvAV""" 4
8642 .el .IP \f(CWGvAV\fR 4
8643 .IX Xref "GvAV"
8644 .IX Item "GvAV"
8645 Return the AV from the GV.
8646 .RS 4
8647 .Sp
8648 .Vb 1
8649 \& AV* GvAV(GV* gv)
8650 .Ve
8651 .RE
8652 .RS 4
8653 .RE
8654 .ie n .IP """gv_AVadd""" 4
8655 .el .IP \f(CWgv_AVadd\fR 4
8656 .IX Item "gv_AVadd"
8657 .PD 0
8658 .ie n .IP """gv_HVadd""" 4
8659 .el .IP \f(CWgv_HVadd\fR 4
8660 .IX Item "gv_HVadd"
8661 .ie n .IP """gv_IOadd""" 4
8662 .el .IP \f(CWgv_IOadd\fR 4
8663 .IX Item "gv_IOadd"
8664 .ie n .IP """gv_SVadd""" 4
8665 .el .IP \f(CWgv_SVadd\fR 4
8666 .IX Xref "gv_AVadd gv_HVadd gv_IOadd gv_SVadd"
8667 .IX Item "gv_SVadd"
8668 .PD
8669 Make sure there is a slot of the given type (AV, HV, IO, SV) in the GV \f(CW\*(C`gv\*(C'\fR.
8670 .RS 4
8671 .Sp
8672 .Vb 1
8673 \& GV * gv_AVadd(GV *gv)
8674 .Ve
8675 .RE
8676 .RS 4
8677 .RE
8678 .ie n .IP """gv_const_sv""" 4
8679 .el .IP \f(CWgv_const_sv\fR 4
8680 .IX Xref "gv_const_sv"
8681 .IX Item "gv_const_sv"
8682 If \f(CW\*(C`gv\*(C'\fR is a typeglob whose subroutine entry is a constant sub eligible for
8683 inlining, or \f(CW\*(C`gv\*(C'\fR is a placeholder reference that would be promoted to such
8684 a typeglob, then returns the value returned by the sub. Otherwise, returns
8685 \&\f(CW\*(C`NULL\*(C'\fR.
8686 .RS 4
8687 .Sp
8688 .Vb 1
8689 \& SV * gv_const_sv(GV *gv)
8690 .Ve
8691 .RE
8692 .RS 4
8693 .RE
8694 .ie n .IP """GvCV""" 4
8695 .el .IP \f(CWGvCV\fR 4
8696 .IX Xref "GvCV"
8697 .IX Item "GvCV"
8698 Return the CV from the GV.
8699 .RS 4
8700 .Sp
8701 .Vb 1
8702 \& CV* GvCV(GV* gv)
8703 .Ve
8704 .RE
8705 .RS 4
8706 .RE
8707 .ie n .IP """gv_efullname3""" 4
8708 .el .IP \f(CWgv_efullname3\fR 4
8709 .IX Item "gv_efullname3"
8710 .PD 0
8711 .ie n .IP """gv_efullname4""" 4
8712 .el .IP \f(CWgv_efullname4\fR 4
8713 .IX Item "gv_efullname4"
8714 .ie n .IP """gv_fullname3""" 4
8715 .el .IP \f(CWgv_fullname3\fR 4
8716 .IX Item "gv_fullname3"
8717 .ie n .IP """gv_fullname4""" 4
8718 .el .IP \f(CWgv_fullname4\fR 4
8719 .IX Xref "gv_efullname3 gv_efullname4 gv_fullname3 gv_fullname4"
8720 .IX Item "gv_fullname4"
8721 .PD
8722 Place the full package name of \f(CW\*(C`gv\*(C'\fR into \f(CW\*(C`sv\*(C'\fR. The \f(CW\*(C`gv_e*\*(C'\fR forms return
8723 instead the effective package name (see "HvENAME").
8724 .Sp
8725 If \f(CW\*(C`prefix\*(C'\fR is non-NULL, it is considered to be a C language NUL-terminated
8726 string, and the stored name will be prefaced with it.
8727 .Sp
8728 The other difference between the functions is that the \f(CW*4\fR forms have an
8729 extra parameter, \f(CW\*(C`keepmain\*(C'\fR. If \f(CW\*(C`true\*(C'\fR an initial \f(CW\*(C`main::\*(C'\fR in the name is
8730 kept; if \f(CW\*(C`false\*(C'\fR it is stripped. With the \f(CW*3\fR forms, it is always kept.
8731 .RS 4
8732 .Sp
8733 .Vb 6
8734 \& void gv_efullname3(SV *sv, const GV *gv, const char *prefix)
8735 \& void gv_efullname4(SV *sv, const GV *gv, const char *prefix,
8736 \& bool keepmain)
8737 \& void gv_fullname3 (SV *sv, const GV *gv, const char *prefix)
8738 \& void gv_fullname4 (SV *sv, const GV *gv, const char *prefix,
8739 \& bool keepmain)
8740 .Ve
8741 .RE
8742 .RS 4
8743 .RE
8744 .ie n .IP """gv_fetchfile""" 4
8745 .el .IP \f(CWgv_fetchfile\fR 4
8746 .IX Item "gv_fetchfile"
8747 .PD 0
8748 .ie n .IP """gv_fetchfile_flags""" 4
8749 .el .IP \f(CWgv_fetchfile_flags\fR 4
8750 .IX Xref "gv_fetchfile gv_fetchfile_flags"
8751 .IX Item "gv_fetchfile_flags"
8752 .PD
8753 These return the debugger glob for the file (compiled by Perl) whose name is
8754 given by the \f(CW\*(C`name\*(C'\fR parameter.
8755 .Sp
8756 There are currently exactly two differences between these functions.
8757 .Sp
8758 The \f(CW\*(C`name\*(C'\fR parameter to \f(CW\*(C`gv_fetchfile\*(C'\fR is a C string, meaning it is
8759 \&\f(CW\*(C`NUL\*(C'\fR\-terminated; whereas the \f(CW\*(C`name\*(C'\fR parameter to \f(CW\*(C`gv_fetchfile_flags\*(C'\fR is a
8760 Perl string, whose length (in bytes) is passed in via the \f(CW\*(C`namelen\*(C'\fR parameter
8761 This means the name may contain embedded \f(CW\*(C`NUL\*(C'\fR characters.
8762 \&\f(CW\*(C`namelen\*(C'\fR doesn't exist in plain \f(CW\*(C`gv_fetchfile\*(C'\fR).
8763 .Sp
8764 The other difference is that \f(CW\*(C`gv_fetchfile_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR
8765 parameter, which is currently completely ignored, but allows for possible
8766 future extensions.
8767 .RS 4
8768 .Sp
8769 .Vb 3
8770 \& GV * gv_fetchfile (const char *name)
8771 \& GV * gv_fetchfile_flags(const char * const name,
8772 \& const STRLEN len, const U32 flags)
8773 .Ve
8774 .RE
8775 .RS 4
8776 .RE
8777 .ie n .IP """gv_fetchmeth""" 4
8778 .el .IP \f(CWgv_fetchmeth\fR 4
8779 .IX Item "gv_fetchmeth"
8780 .PD 0
8781 .ie n .IP """gv_fetchmeth_pv""" 4
8782 .el .IP \f(CWgv_fetchmeth_pv\fR 4
8783 .IX Item "gv_fetchmeth_pv"
8784 .ie n .IP """gv_fetchmeth_pvn""" 4
8785 .el .IP \f(CWgv_fetchmeth_pvn\fR 4
8786 .IX Item "gv_fetchmeth_pvn"
8787 .ie n .IP """gv_fetchmeth_sv""" 4
8788 .el .IP \f(CWgv_fetchmeth_sv\fR 4
8789 .IX Xref "gv_fetchmeth gv_fetchmeth_pv gv_fetchmeth_pvn gv_fetchmeth_sv"
8790 .IX Item "gv_fetchmeth_sv"
8791 .PD
8792 These each look for a glob with name \f(CW\*(C`name\*(C'\fR, containing a defined subroutine,
8793 returning the GV of that glob if found, or \f(CW\*(C`NULL\*(C'\fR if not.
8794 .Sp
8795 \&\f(CW\*(C`stash\*(C'\fR is always searched (first), unless it is \f(CW\*(C`NULL\*(C'\fR.
8796 .Sp
8797 If \f(CW\*(C`stash\*(C'\fR is NULL, or was searched but nothing was found in it, and the
8798 \&\f(CW\*(C`GV_SUPER\*(C'\fR bit is set in \f(CW\*(C`flags\*(C'\fR, stashes accessible via \f(CW@ISA\fR are searched
8799 next. Searching is conducted according to \f(CW\*(C`MRO\*(C'\fR order.
8800 .Sp
8801 Finally, if no matches were found so far, and the \f(CW\*(C`GV_NOUNIVERSAL\*(C'\fR flag in
8802 \&\f(CW\*(C`flags\*(C'\fR is not set, \f(CW\*(C`UNIVERSAL::\*(C'\fR is searched.
8803 .Sp
8804 The argument \f(CW\*(C`level\*(C'\fR should be either 0 or \-1. If \-1, the function will
8805 return without any side effects or caching. If 0, the function makes sure
8806 there is a glob named \f(CW\*(C`name\*(C'\fR in \f(CW\*(C`stash\*(C'\fR, creating one if necessary.
8807 The subroutine slot in the glob will be set to any subroutine found in the
8808 \&\f(CW\*(C`stash\*(C'\fR and \f(CW\*(C`SUPER::\*(C'\fR search, hence caching any \f(CW\*(C`SUPER::\*(C'\fR result. Note that
8809 subroutines found in \f(CW\*(C`UNIVERSAL::\*(C'\fR are not cached.
8810 .Sp
8811 The GV returned from these may be a method cache entry, which is not visible to
8812 Perl code. So when calling \f(CW\*(C`call_sv\*(C'\fR, you should not use the GV directly;
8813 instead, you should use the method's CV, which can be obtained from the GV with
8814 the \f(CW\*(C`GvCV\*(C'\fR macro.
8815 .Sp
8816 The only other significant value for \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`SVf_UTF8\*(C'\fR, indicating that
8817 \&\f(CW\*(C`name\*(C'\fR is to be treated as being encoded in UTF\-8.
8818 .Sp
8819 Plain \f(CW\*(C`gv_fetchmeth\*(C'\fR lacks a \f(CW\*(C`flags\*(C'\fR parameter, hence always searches in
8820 \&\f(CW\*(C`stash\*(C'\fR, then \f(CW\*(C`UNIVERSAL::\*(C'\fR, and \f(CW\*(C`name\*(C'\fR is never UTF\-8. Otherwise it is
8821 exactly like \f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR.
8822 .Sp
8823 The other forms do have a \f(CW\*(C`flags\*(C'\fR parameter, and differ only in how the glob
8824 name is specified.
8825 .Sp
8826 In \f(CW\*(C`gv_fetchmeth_pv\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a C language NUL-terminated string.
8827 .Sp
8828 In \f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an
8829 additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, the name
8830 may contain embedded-NUL characters.
8831 .Sp
8832 In \f(CW\*(C`gv_fetchmeth_sv\*(C'\fR, \f(CW*name\fR is an SV, and the name is the PV extracted from
8833 that, using "\f(CW\*(C`SvPV\*(C'\fR". If the SV is marked as being in UTF\-8, the extracted
8834 PV will also be.
8835 .RS 4
8836 .Sp
8837 .Vb 8
8838 \& GV * gv_fetchmeth (HV *stash, const char *name, STRLEN len,
8839 \& I32 level)
8840 \& GV * gv_fetchmeth_pv (HV *stash, const char *name, I32 level,
8841 \& U32 flags)
8842 \& GV * gv_fetchmeth_pvn(HV *stash, const char *name, STRLEN len,
8843 \& I32 level, U32 flags)
8844 \& GV * gv_fetchmeth_sv (HV *stash, SV *namesv, I32 level,
8845 \& U32 flags)
8846 .Ve
8847 .RE
8848 .RS 4
8849 .RE
8850 .ie n .IP """gv_fetchmeth_autoload""" 4
8851 .el .IP \f(CWgv_fetchmeth_autoload\fR 4
8852 .IX Xref "gv_fetchmeth_autoload"
8853 .IX Item "gv_fetchmeth_autoload"
8854 This is the old form of "gv_fetchmeth_pvn_autoload", which has no flags
8855 parameter.
8856 .RS 4
8857 .Sp
8858 .Vb 2
8859 \& GV * gv_fetchmeth_autoload(HV *stash, const char *name,
8860 \& STRLEN len, I32 level)
8861 .Ve
8862 .RE
8863 .RS 4
8864 .RE
8865 .ie n .IP """gv_fetchmethod""" 4
8866 .el .IP \f(CWgv_fetchmethod\fR 4
8867 .IX Xref "gv_fetchmethod"
8868 .IX Item "gv_fetchmethod"
8869 See "gv_fetchmethod_autoload".
8870 .RS 4
8871 .Sp
8872 .Vb 1
8873 \& GV * gv_fetchmethod(HV *stash, const char *name)
8874 .Ve
8875 .RE
8876 .RS 4
8877 .RE
8878 .ie n .IP """gv_fetchmethod_autoload""" 4
8879 .el .IP \f(CWgv_fetchmethod_autoload\fR 4
8880 .IX Xref "gv_fetchmethod_autoload"
8881 .IX Item "gv_fetchmethod_autoload"
8882 Returns the glob which contains the subroutine to call to invoke the method
8883 on the \f(CW\*(C`stash\*(C'\fR. In fact in the presence of autoloading this may be the
8884 glob for "AUTOLOAD". In this case the corresponding variable \f(CW$AUTOLOAD\fR is
8885 already setup.
8886 .Sp
8887 The third parameter of \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR determines whether
8888 AUTOLOAD lookup is performed if the given method is not present: non-zero
8889 means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
8890 Calling \f(CW\*(C`gv_fetchmethod\*(C'\fR is equivalent to calling \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR
8891 with a non-zero \f(CW\*(C`autoload\*(C'\fR parameter.
8892 .Sp
8893 These functions grant \f(CW"SUPER"\fR token
8894 as a prefix of the method name. Note
8895 that if you want to keep the returned glob for a long time, you need to
8896 check for it being "AUTOLOAD", since at the later time the call may load a
8897 different subroutine due to \f(CW$AUTOLOAD\fR changing its value. Use the glob
8898 created as a side effect to do this.
8899 .Sp
8900 These functions have the same side-effects as \f(CW\*(C`gv_fetchmeth\*(C'\fR with
8901 \&\f(CW\*(C`level==0\*(C'\fR. The warning against passing the GV returned by
8902 \&\f(CW\*(C`gv_fetchmeth\*(C'\fR to \f(CW\*(C`call_sv\*(C'\fR applies equally to these functions.
8903 .RS 4
8904 .Sp
8905 .Vb 2
8906 \& GV * gv_fetchmethod_autoload(HV *stash, const char *name,
8907 \& I32 autoload)
8908 .Ve
8909 .RE
8910 .RS 4
8911 .RE
8912 .ie n .IP """gv_fetchmeth_pv_autoload""" 4
8913 .el .IP \f(CWgv_fetchmeth_pv_autoload\fR 4
8914 .IX Xref "gv_fetchmeth_pv_autoload"
8915 .IX Item "gv_fetchmeth_pv_autoload"
8916 Exactly like "gv_fetchmeth_pvn_autoload", but takes a nul-terminated string
8917 instead of a string/length pair.
8918 .RS 4
8919 .Sp
8920 .Vb 2
8921 \& GV * gv_fetchmeth_pv_autoload(HV *stash, const char *name,
8922 \& I32 level, U32 flags)
8923 .Ve
8924 .RE
8925 .RS 4
8926 .RE
8927 .ie n .IP """gv_fetchmeth_pvn_autoload""" 4
8928 .el .IP \f(CWgv_fetchmeth_pvn_autoload\fR 4
8929 .IX Xref "gv_fetchmeth_pvn_autoload"
8930 .IX Item "gv_fetchmeth_pvn_autoload"
8931 Same as \f(CWgv_fetchmeth_pvn()\fR, but looks for autoloaded subroutines too.
8932 Returns a glob for the subroutine.
8933 .Sp
8934 For an autoloaded subroutine without a GV, will create a GV even
8935 if \f(CW\*(C`level < 0\*(C'\fR. For an autoloaded subroutine without a stub, \f(CWGvCV()\fR
8936 of the result may be zero.
8937 .Sp
8938 Currently, the only significant value for \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`SVf_UTF8\*(C'\fR.
8939 .RS 4
8940 .Sp
8941 .Vb 2
8942 \& GV * gv_fetchmeth_pvn_autoload(HV *stash, const char *name,
8943 \& STRLEN len, I32 level, U32 flags)
8944 .Ve
8945 .RE
8946 .RS 4
8947 .RE
8948 .ie n .IP """gv_fetchmeth_sv_autoload""" 4
8949 .el .IP \f(CWgv_fetchmeth_sv_autoload\fR 4
8950 .IX Xref "gv_fetchmeth_sv_autoload"
8951 .IX Item "gv_fetchmeth_sv_autoload"
8952 Exactly like "gv_fetchmeth_pvn_autoload", but takes the name string in the form
8953 of an SV instead of a string/length pair.
8954 .RS 4
8955 .Sp
8956 .Vb 2
8957 \& GV * gv_fetchmeth_sv_autoload(HV *stash, SV *namesv, I32 level,
8958 \& U32 flags)
8959 .Ve
8960 .RE
8961 .RS 4
8962 .RE
8963 .ie n .IP """gv_fetchpv""" 4
8964 .el .IP \f(CWgv_fetchpv\fR 4
8965 .IX Item "gv_fetchpv"
8966 .PD 0
8967 .ie n .IP """gv_fetchpvn""" 4
8968 .el .IP \f(CWgv_fetchpvn\fR 4
8969 .IX Item "gv_fetchpvn"
8970 .ie n .IP """gv_fetchpvn_flags""" 4
8971 .el .IP \f(CWgv_fetchpvn_flags\fR 4
8972 .IX Item "gv_fetchpvn_flags"
8973 .ie n .IP """gv_fetchpvs""" 4
8974 .el .IP \f(CWgv_fetchpvs\fR 4
8975 .IX Item "gv_fetchpvs"
8976 .ie n .IP """gv_fetchsv""" 4
8977 .el .IP \f(CWgv_fetchsv\fR 4
8978 .IX Item "gv_fetchsv"
8979 .ie n .IP """gv_fetchsv_nomg""" 4
8980 .el .IP \f(CWgv_fetchsv_nomg\fR 4
8981 .IX Xref "gv_fetchpv gv_fetchpvn gv_fetchpvn_flags gv_fetchpvs gv_fetchsv gv_fetchsv_nomg"
8982 .IX Item "gv_fetchsv_nomg"
8983 .PD
8984 These all return the GV of type \f(CW\*(C`sv_type\*(C'\fR whose name is given by the inputs,
8985 or NULL if no GV of that name and type could be found. See "Stashes
8986 and Globs" in perlguts.
8987 .Sp
8988 The only differences are how the input name is specified, and if 'get' magic is
8989 normally used in getting that name.
8990 .Sp
8991 Don't be fooled by the fact that only one form has \f(CW\*(C`flags\*(C'\fR in its name. They
8992 all have a \f(CW\*(C`flags\*(C'\fR parameter in fact, and all the flag bits have the same
8993 meanings for all
8994 .Sp
8995 If any of the flags \f(CW\*(C`GV_ADD\*(C'\fR, \f(CW\*(C`GV_ADDMG\*(C'\fR, \f(CW\*(C`GV_ADDWARN\*(C'\fR, \f(CW\*(C`GV_ADDMULTI\*(C'\fR, or
8996 \&\f(CW\*(C`GV_NOINIT\*(C'\fR is set, a GV is created if none already exists for the input name
8997 and type. However, \f(CW\*(C`GV_ADDMG\*(C'\fR will only do the creation for magical GV's.
8998 For all of these flags except \f(CW\*(C`GV_NOINIT\*(C'\fR, \f(CW"gv_init_pvn"\fR is called after
8999 the addition. \f(CW\*(C`GV_ADDWARN\*(C'\fR is used when the caller expects that adding won't
9000 be necessary because the symbol should already exist; but if not, add it
9001 anyway, with a warning that it was unexpectedly absent. The \f(CW\*(C`GV_ADDMULTI\*(C'\fR
9002 flag means to pretend that the GV has been seen before (\fIi.e.\fR, suppress "Used
9003 once" warnings).
9004 .Sp
9005 The flag \f(CW\*(C`GV_NOADD_NOINIT\*(C'\fR causes \f(CW"gv_init_pvn"\fR not be to called if the
9006 GV existed but isn't PVGV.
9007 .Sp
9008 If the \f(CW\*(C`SVf_UTF8\*(C'\fR bit is set, the name is treated as being encoded in UTF\-8;
9009 otherwise the name won't be considered to be UTF\-8 in the \f(CW\*(C`pv\*(C'\fR\-named forms,
9010 and the UTF\-8ness of the underlying SVs will be used in the \f(CW\*(C`sv\*(C'\fR forms.
9011 .Sp
9012 If the flag \f(CW\*(C`GV_NOTQUAL\*(C'\fR is set, the caller warrants that the input name is a
9013 plain symbol name, not qualified with a package, otherwise the name is checked
9014 for being a qualified one.
9015 .Sp
9016 In \f(CW\*(C`gv_fetchpv\*(C'\fR, \f(CW\*(C`nambeg\*(C'\fR is a C string, NUL-terminated with no intermediate
9017 NULs.
9018 .Sp
9019 In \f(CW\*(C`gv_fetchpvs\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a literal C string, hence is enclosed in
9020 double quotes.
9021 .Sp
9022 \&\f(CW\*(C`gv_fetchpvn\*(C'\fR and \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR are identical. In these, <nambeg> is
9023 a Perl string whose byte length is given by \f(CW\*(C`full_len\*(C'\fR, and may contain
9024 embedded NULs.
9025 .Sp
9026 In \f(CW\*(C`gv_fetchsv\*(C'\fR and \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR, the name is extracted from the PV of
9027 the input \f(CW\*(C`name\*(C'\fR SV. The only difference between these two forms is that
9028 \&'get' magic is normally done on \f(CW\*(C`name\*(C'\fR in \f(CW\*(C`gv_fetchsv\*(C'\fR, and always skipped
9029 with \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR. Including \f(CW\*(C`GV_NO_SVGMAGIC\*(C'\fR in the \f(CW\*(C`flags\*(C'\fR parameter
9030 to \f(CW\*(C`gv_fetchsv\*(C'\fR makes it behave identically to \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR.
9031 .RS 4
9032 .Sp
9033 .Vb 9
9034 \& GV * gv_fetchpv (const char *nambeg, I32 flags,
9035 \& const svtype sv_type)
9036 \& GV * gv_fetchpvn (const char * nambeg, STRLEN full_len,
9037 \& I32 flags, const svtype sv_type)
9038 \& GV * gv_fetchpvn_flags(const char *name, STRLEN len, I32 flags,
9039 \& const svtype sv_type)
9040 \& GV * gv_fetchpvs ("name", I32 flags, const svtype sv_type)
9041 \& GV * gv_fetchsv (SV *name, I32 flags, const svtype sv_type)
9042 \& GV * gv_fetchsv_nomg (SV *name, I32 flags, const svtype sv_type)
9043 .Ve
9044 .RE
9045 .RS 4
9046 .RE
9047 .ie n .IP """GvHV""" 4
9048 .el .IP \f(CWGvHV\fR 4
9049 .IX Xref "GvHV"
9050 .IX Item "GvHV"
9051 Return the HV from the GV.
9052 .RS 4
9053 .Sp
9054 .Vb 1
9055 \& HV* GvHV(GV* gv)
9056 .Ve
9057 .RE
9058 .RS 4
9059 .RE
9060 .ie n .IP """gv_init""" 4
9061 .el .IP \f(CWgv_init\fR 4
9062 .IX Xref "gv_init"
9063 .IX Item "gv_init"
9064 The old form of \f(CWgv_init_pvn()\fR. It does not work with UTF\-8 strings, as it
9065 has no flags parameter. If the \f(CW\*(C`multi\*(C'\fR parameter is set, the
9066 \&\f(CW\*(C`GV_ADDMULTI\*(C'\fR flag will be passed to \f(CWgv_init_pvn()\fR.
9067 .RS 4
9068 .Sp
9069 .Vb 2
9070 \& void gv_init(GV *gv, HV *stash, const char *name, STRLEN len,
9071 \& int multi)
9072 .Ve
9073 .RE
9074 .RS 4
9075 .RE
9076 .ie n .IP """gv_init_pv""" 4
9077 .el .IP \f(CWgv_init_pv\fR 4
9078 .IX Xref "gv_init_pv"
9079 .IX Item "gv_init_pv"
9080 Same as \f(CWgv_init_pvn()\fR, but takes a nul-terminated string for the name
9081 instead of separate char * and length parameters.
9082 .RS 4
9083 .Sp
9084 .Vb 1
9085 \& void gv_init_pv(GV *gv, HV *stash, const char *name, U32 flags)
9086 .Ve
9087 .RE
9088 .RS 4
9089 .RE
9090 .ie n .IP """gv_init_pvn""" 4
9091 .el .IP \f(CWgv_init_pvn\fR 4
9092 .IX Xref "gv_init_pvn"
9093 .IX Item "gv_init_pvn"
9094 Converts a scalar into a typeglob. This is an incoercible typeglob;
9095 assigning a reference to it will assign to one of its slots, instead of
9096 overwriting it as happens with typeglobs created by \f(CW\*(C`SvSetSV\*(C'\fR. Converting
9097 any scalar that is \f(CWSvOK()\fR may produce unpredictable results and is reserved
9098 for perl's internal use.
9099 .Sp
9100 \&\f(CW\*(C`gv\*(C'\fR is the scalar to be converted.
9101 .Sp
9102 \&\f(CW\*(C`stash\*(C'\fR is the parent stash/package, if any.
9103 .Sp
9104 \&\f(CW\*(C`name\*(C'\fR and \f(CW\*(C`len\*(C'\fR give the name. The name must be unqualified;
9105 that is, it must not include the package name. If \f(CW\*(C`gv\*(C'\fR is a
9106 stash element, it is the caller's responsibility to ensure that the name
9107 passed to this function matches the name of the element. If it does not
9108 match, perl's internal bookkeeping will get out of sync.
9109 .Sp
9110 \&\f(CW\*(C`flags\*(C'\fR can be set to \f(CW\*(C`SVf_UTF8\*(C'\fR if \f(CW\*(C`name\*(C'\fR is a UTF\-8 string, or
9111 the return value of SvUTF8(sv). It can also take the
9112 \&\f(CW\*(C`GV_ADDMULTI\*(C'\fR flag, which means to pretend that the GV has been
9113 seen before (i.e., suppress "Used once" warnings).
9114 .RS 4
9115 .Sp
9116 .Vb 2
9117 \& void gv_init_pvn(GV *gv, HV *stash, const char *name, STRLEN len,
9118 \& U32 flags)
9119 .Ve
9120 .RE
9121 .RS 4
9122 .RE
9123 .ie n .IP """gv_init_sv""" 4
9124 .el .IP \f(CWgv_init_sv\fR 4
9125 .IX Xref "gv_init_sv"
9126 .IX Item "gv_init_sv"
9127 Same as \f(CWgv_init_pvn()\fR, but takes an SV * for the name instead of separate
9128 char * and length parameters. \f(CW\*(C`flags\*(C'\fR is currently unused.
9129 .RS 4
9130 .Sp
9131 .Vb 1
9132 \& void gv_init_sv(GV *gv, HV *stash, SV *namesv, U32 flags)
9133 .Ve
9134 .RE
9135 .RS 4
9136 .RE
9137 .ie n .IP """gv_name_set""" 4
9138 .el .IP \f(CWgv_name_set\fR 4
9139 .IX Xref "gv_name_set"
9140 .IX Item "gv_name_set"
9141 Set the name for GV \f(CW\*(C`gv\*(C'\fR to \f(CW\*(C`name\*(C'\fR which is \f(CW\*(C`len\*(C'\fR bytes long. Thus it may
9142 contain embedded NUL characters.
9143 .Sp
9144 If \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`SVf_UTF8\*(C'\fR, the name is treated as being encoded in
9145 UTF\-8; otherwise not.
9146 .RS 4
9147 .Sp
9148 .Vb 1
9149 \& void gv_name_set(GV *gv, const char *name, U32 len, U32 flags)
9150 .Ve
9151 .RE
9152 .RS 4
9153 .RE
9154 .ie n .IP """gv_stashpv""" 4
9155 .el .IP \f(CWgv_stashpv\fR 4
9156 .IX Xref "gv_stashpv"
9157 .IX Item "gv_stashpv"
9158 Returns a pointer to the stash for a specified package. Uses \f(CW\*(C`strlen\*(C'\fR to
9159 determine the length of \f(CW\*(C`name\*(C'\fR, then calls \f(CWgv_stashpvn()\fR.
9160 .RS 4
9161 .Sp
9162 .Vb 1
9163 \& HV * gv_stashpv(const char *name, I32 flags)
9164 .Ve
9165 .RE
9166 .RS 4
9167 .RE
9168 .ie n .IP """gv_stashpvn""" 4
9169 .el .IP \f(CWgv_stashpvn\fR 4
9170 .IX Xref "gv_stashpvn"
9171 .IX Item "gv_stashpvn"
9172 Returns a pointer to the stash for a specified package. The \f(CW\*(C`namelen\*(C'\fR
9173 parameter indicates the length of the \f(CW\*(C`name\*(C'\fR, in bytes. \f(CW\*(C`flags\*(C'\fR is passed
9174 to \f(CWgv_fetchpvn_flags()\fR, so if set to \f(CW\*(C`GV_ADD\*(C'\fR then the package will be
9175 created if it does not already exist. If the package does not exist and
9176 \&\f(CW\*(C`flags\*(C'\fR is 0 (or any other setting that does not create packages) then \f(CW\*(C`NULL\*(C'\fR
9177 is returned.
9178 .Sp
9179 Flags may be one of:
9180 .Sp
9181 .Vb 7
9182 \& GV_ADD Create and initialize the package if doesn\*(Aqt
9183 \& already exist
9184 \& GV_NOADD_NOINIT Don\*(Aqt create the package,
9185 \& GV_ADDMG GV_ADD iff the GV is magical
9186 \& GV_NOINIT GV_ADD, but don\*(Aqt initialize
9187 \& GV_NOEXPAND Don\*(Aqt expand SvOK() entries to PVGV
9188 \& SVf_UTF8 The name is in UTF\-8
9189 .Ve
9190 .Sp
9191 The most important of which are probably \f(CW\*(C`GV_ADD\*(C'\fR and \f(CW\*(C`SVf_UTF8\*(C'\fR.
9192 .Sp
9193 Note, use of \f(CW\*(C`gv_stashsv\*(C'\fR instead of \f(CW\*(C`gv_stashpvn\*(C'\fR where possible is strongly
9194 recommended for performance reasons.
9195 .RS 4
9196 .Sp
9197 .Vb 1
9198 \& HV * gv_stashpvn(const char *name, U32 namelen, I32 flags)
9199 .Ve
9200 .RE
9201 .RS 4
9202 .RE
9203 .ie n .IP """gv_stashpvs""" 4
9204 .el .IP \f(CWgv_stashpvs\fR 4
9205 .IX Xref "gv_stashpvs"
9206 .IX Item "gv_stashpvs"
9207 Like \f(CW\*(C`gv_stashpvn\*(C'\fR, but takes a literal string instead of a
9208 string/length pair.
9209 .RS 4
9210 .Sp
9211 .Vb 1
9212 \& HV* gv_stashpvs("name", I32 create)
9213 .Ve
9214 .RE
9215 .RS 4
9216 .RE
9217 .ie n .IP """gv_stashsv""" 4
9218 .el .IP \f(CWgv_stashsv\fR 4
9219 .IX Xref "gv_stashsv"
9220 .IX Item "gv_stashsv"
9221 Returns a pointer to the stash for a specified package. See
9222 \&\f(CW"gv_stashpvn"\fR.
9223 .Sp
9224 Note this interface is strongly preferred over \f(CW\*(C`gv_stashpvn\*(C'\fR for performance
9225 reasons.
9226 .RS 4
9227 .Sp
9228 .Vb 1
9229 \& HV * gv_stashsv(SV *sv, I32 flags)
9230 .Ve
9231 .RE
9232 .RS 4
9233 .RE
9234 .ie n .IP """GvSV""" 4
9235 .el .IP \f(CWGvSV\fR 4
9236 .IX Xref "GvSV"
9237 .IX Item "GvSV"
9238 Return the SV from the GV.
9239 .Sp
9240 Prior to Perl v5.9.3, this would add a scalar if none existed. Nowadays, use
9241 \&\f(CW"GvSVn"\fR for that, or compile perl with \f(CW\*(C`\-DPERL_CREATE_GVSV\*(C'\fR. See
9242 perl5100delta.
9243 .RS 4
9244 .Sp
9245 .Vb 1
9246 \& SV* GvSV(GV* gv)
9247 .Ve
9248 .RE
9249 .RS 4
9250 .RE
9251 .ie n .IP """GvSVn""" 4
9252 .el .IP \f(CWGvSVn\fR 4
9253 .IX Xref "GvSVn"
9254 .IX Item "GvSVn"
9255 Like \f(CW"GvSV"\fR, but creates an empty scalar if none already exists.
9256 .RS 4
9257 .Sp
9258 .Vb 1
9259 \& SV* GvSVn(GV* gv)
9260 .Ve
9261 .RE
9262 .RS 4
9263 .RE
9264 .ie n .IP """newGVgen""" 4
9265 .el .IP \f(CWnewGVgen\fR 4
9266 .IX Item "newGVgen"
9267 .PD 0
9268 .ie n .IP """newGVgen_flags""" 4
9269 .el .IP \f(CWnewGVgen_flags\fR 4
9270 .IX Xref "newGVgen newGVgen_flags"
9271 .IX Item "newGVgen_flags"
9272 .PD
9273 Create a new, guaranteed to be unique, GV in the package given by the
9274 NUL-terminated C language string \f(CW\*(C`pack\*(C'\fR, and return a pointer to it.
9275 .Sp
9276 For \f(CW\*(C`newGVgen\*(C'\fR or if \f(CW\*(C`flags\*(C'\fR in \f(CW\*(C`newGVgen_flags\*(C'\fR is 0, \f(CW\*(C`pack\*(C'\fR is to be
9277 considered to be encoded in Latin\-1. The only other legal \f(CW\*(C`flags\*(C'\fR value is
9278 \&\f(CW\*(C`SVf_UTF8\*(C'\fR, which indicates \f(CW\*(C`pack\*(C'\fR is to be considered to be encoded in
9279 UTF\-8.
9280 .RS 4
9281 .Sp
9282 .Vb 2
9283 \& GV * newGVgen (const char *pack)
9284 \& GV * newGVgen_flags(const char *pack, U32 flags)
9285 .Ve
9286 .RE
9287 .RS 4
9288 .RE
9289 .ie n .IP """PL_curstash""" 4
9290 .el .IP \f(CWPL_curstash\fR 4
9291 .IX Xref "PL_curstash"
9292 .IX Item "PL_curstash"
9293 The stash for the package code will be compiled into.
9294 .Sp
9295 On threaded perls, each thread has an independent copy of this variable;
9296 each initialized at creation time with the current value of the creating
9297 thread's copy.
9298 .RS 4
9299 .Sp
9300 .Vb 1
9301 \& HV* PL_curstash
9302 .Ve
9303 .RE
9304 .RS 4
9305 .RE
9306 .ie n .IP """PL_defgv""" 4
9307 .el .IP \f(CWPL_defgv\fR 4
9308 .IX Xref "PL_defgv"
9309 .IX Item "PL_defgv"
9310 The GV representing \f(CW*_\fR. Useful for access to \f(CW$_\fR.
9311 .Sp
9312 On threaded perls, each thread has an independent copy of this variable;
9313 each initialized at creation time with the current value of the creating
9314 thread's copy.
9315 .RS 4
9316 .Sp
9317 .Vb 1
9318 \& GV * PL_defgv
9319 .Ve
9320 .RE
9321 .RS 4
9322 .RE
9323 .ie n .IP """PL_defoutgv""" 4
9324 .el .IP \f(CWPL_defoutgv\fR 4
9325 .IX Xref "PL_defoutgv"
9326 .IX Item "PL_defoutgv"
9327 See \f(CW"setdefout"\fR.
9328 .ie n .IP """PL_defstash""" 4
9329 .el .IP \f(CWPL_defstash\fR 4
9330 .IX Item "PL_defstash"
9331 Described in perlguts.
9332 .ie n .IP """save_gp""" 4
9333 .el .IP \f(CWsave_gp\fR 4
9334 .IX Xref "save_gp"
9335 .IX Item "save_gp"
9336 Saves the current GP of gv on the save stack to be restored on scope exit.
9337 .Sp
9338 If \f(CW\*(C`empty\*(C'\fR is true, replace the GP with a new GP.
9339 .Sp
9340 If \f(CW\*(C`empty\*(C'\fR is false, mark \f(CW\*(C`gv\*(C'\fR with \f(CW\*(C`GVf_INTRO\*(C'\fR so the next reference
9341 assigned is localized, which is how \f(CW\*(C`\ local\ *foo\ =\ $someref;\ \*(C'\fR works.
9342 .RS 4
9343 .Sp
9344 .Vb 1
9345 \& void save_gp(GV *gv, I32 empty)
9346 .Ve
9347 .RE
9348 .RS 4
9349 .RE
9350 .ie n .IP """setdefout""" 4
9351 .el .IP \f(CWsetdefout\fR 4
9352 .IX Xref "setdefout"
9353 .IX Item "setdefout"
9354 Sets \f(CW\*(C`PL_defoutgv\*(C'\fR, the default file handle for output, to the passed in
9355 typeglob. As \f(CW\*(C`PL_defoutgv\*(C'\fR "owns" a reference on its typeglob, the reference
9356 count of the passed in typeglob is increased by one, and the reference count
9357 of the typeglob that \f(CW\*(C`PL_defoutgv\*(C'\fR points to is decreased by one.
9358 .RS 4
9359 .Sp
9360 .Vb 1
9361 \& void setdefout(GV *gv)
9362 .Ve
9363 .RE
9364 .RS 4
9365 .RE
9366 .SH "Hook manipulation"
9367 .IX Header "Hook manipulation"
9368 These functions provide convenient and thread-safe means of manipulating
9369 hook variables.
9370 .ie n .IP """rcpv_copy""" 4
9371 .el .IP \f(CWrcpv_copy\fR 4
9372 .IX Xref "rcpv_copy"
9373 .IX Item "rcpv_copy"
9374 refcount increment a shared memory refcounted string, and when
9375 the refcount goes to 0 free it using \fBPerlMemShared_free()\fR.
9376 .Sp
9377 It is the callers responsibility to ensure that the pv is the
9378 result of a \fBrcpv_new()\fR call.
9379 .Sp
9380 Returns the same pointer that was passed in.
9381 .Sp
9382 .Vb 1
9383 \& new = rcpv_copy(pv);
9384 .Ve
9385 .RS 4
9386 .Sp
9387 .Vb 1
9388 \& char * rcpv_copy(char * const pv)
9389 .Ve
9390 .RE
9391 .RS 4
9392 .RE
9393 .ie n .IP """rcpv_free""" 4
9394 .el .IP \f(CWrcpv_free\fR 4
9395 .IX Xref "rcpv_free"
9396 .IX Item "rcpv_free"
9397 refcount decrement a shared memory refcounted string, and when
9398 the refcount goes to 0 free it using \fBperlmemshared_free()\fR.
9399 .Sp
9400 it is the callers responsibility to ensure that the pv is the
9401 result of a \fBrcpv_new()\fR call.
9402 .Sp
9403 Always returns NULL so it can be used like this:
9404 .Sp
9405 .Vb 1
9406 \& thing = rcpv_free(thing);
9407 .Ve
9408 .RS 4
9409 .Sp
9410 .Vb 1
9411 \& char * rcpv_free(char * const pv)
9412 .Ve
9413 .RE
9414 .RS 4
9415 .RE
9416 .ie n .IP """rcpv_new""" 4
9417 .el .IP \f(CWrcpv_new\fR 4
9418 .IX Xref "rcpv_new"
9419 .IX Item "rcpv_new"
9420 Create a new shared memory refcounted string with the requested size, and
9421 with the requested initialization and a refcount of 1. The actual space
9422 allocated will be 1 byte more than requested and \fBrcpv_new()\fR will ensure that
9423 the extra byte is a null regardless of any flags settings.
9424 .Sp
9425 If the RCPVf_NO_COPY flag is set then the pv argument will be
9426 ignored, otherwise the contents of the pv pointer will be copied into
9427 the new buffer or if it is NULL the function will do nothing and return NULL.
9428 .Sp
9429 If the RCPVf_USE_STRLEN flag is set then the len argument is ignored and
9430 recomputed using \f(CWstrlen(pv)\fR. It is an error to combine RCPVf_USE_STRLEN
9431 and RCPVf_NO_COPY at the same time.
9432 .Sp
9433 Under DEBUGGING \fBrcpv_new()\fR will \fBassert()\fR if it is asked to create a 0 length
9434 shared string unless the RCPVf_ALLOW_EMPTY flag is set.
9435 .Sp
9436 The return value from the function is suitable for passing into \fBrcpv_copy()\fR and
9437 \&\fBrcpv_free()\fR. To access the RCPV * from the returned value use the \fBRCPVx()\fR macro.
9438 The 'len' member of the RCPV struct stores the allocated length (including the
9439 extra byte), but the \fBRCPV_LEN()\fR macro returns the requested length (not
9440 including the extra byte).
9441 .Sp
9442 Note that \fBrcpv_new()\fR does NOT use a hash table or anything like that to
9443 dedupe inputs given the same text content. Each call with a non-null pv
9444 parameter will produce a distinct pointer with its own refcount regardless of
9445 the input content.
9446 .RS 4
9447 .Sp
9448 .Vb 1
9449 \& char * rcpv_new(const char * const pv, STRLEN len, U32 flags)
9450 .Ve
9451 .RE
9452 .RS 4
9453 .RE
9454 .ie n .IP """wrap_op_checker""" 4
9455 .el .IP \f(CWwrap_op_checker\fR 4
9456 .IX Xref "wrap_op_checker"
9457 .IX Item "wrap_op_checker"
9458 Puts a C function into the chain of check functions for a specified op
9459 type. This is the preferred way to manipulate the "PL_check" array.
9460 \&\f(CW\*(C`opcode\*(C'\fR specifies which type of op is to be affected. \f(CW\*(C`new_checker\*(C'\fR
9461 is a pointer to the C function that is to be added to that opcode's
9462 check chain, and \f(CW\*(C`old_checker_p\*(C'\fR points to the storage location where a
9463 pointer to the next function in the chain will be stored. The value of
9464 \&\f(CW\*(C`new_checker\*(C'\fR is written into the "PL_check" array, while the value
9465 previously stored there is written to \f(CW*old_checker_p\fR.
9466 .Sp
9467 "PL_check" is global to an entire process, and a module wishing to
9468 hook op checking may find itself invoked more than once per process,
9469 typically in different threads. To handle that situation, this function
9470 is idempotent. The location \f(CW*old_checker_p\fR must initially (once
9471 per process) contain a null pointer. A C variable of static duration
9472 (declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give
9473 it internal linkage) will be implicitly initialised appropriately,
9474 if it does not have an explicit initialiser. This function will only
9475 actually modify the check chain if it finds \f(CW*old_checker_p\fR to be null.
9476 This function is also thread safe on the small scale. It uses appropriate
9477 locking to avoid race conditions in accessing "PL_check".
9478 .Sp
9479 When this function is called, the function referenced by \f(CW\*(C`new_checker\*(C'\fR
9480 must be ready to be called, except for \f(CW*old_checker_p\fR being unfilled.
9481 In a threading situation, \f(CW\*(C`new_checker\*(C'\fR may be called immediately,
9482 even before this function has returned. \f(CW*old_checker_p\fR will always
9483 be appropriately set before \f(CW\*(C`new_checker\*(C'\fR is called. If \f(CW\*(C`new_checker\*(C'\fR
9484 decides not to do anything special with an op that it is given (which
9485 is the usual case for most uses of op check hooking), it must chain the
9486 check function referenced by \f(CW*old_checker_p\fR.
9487 .Sp
9488 Taken all together, XS code to hook an op checker should typically look
9489 something like this:
9490 .Sp
9491 .Vb 9
9492 \& static Perl_check_t nxck_frob;
9493 \& static OP *myck_frob(pTHX_ OP *op) {
9494 \& ...
9495 \& op = nxck_frob(aTHX_ op);
9496 \& ...
9497 \& return op;
9498 \& }
9499 \& BOOT:
9500 \& wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
9501 .Ve
9502 .Sp
9503 If you want to influence compilation of calls to a specific subroutine,
9504 then use "cv_set_call_checker_flags" rather than hooking checking of
9505 all \f(CW\*(C`entersub\*(C'\fR ops.
9506 .RS 4
9507 .Sp
9508 .Vb 2
9509 \& void wrap_op_checker(Optype opcode, Perl_check_t new_checker,
9510 \& Perl_check_t *old_checker_p)
9511 .Ve
9512 .RE
9513 .RS 4
9514 .RE
9515 .SH "HV Handling"
9516 .IX Xref "HV_ITERNEXT_WANTPLACEHOLDERS HV_NAME_SETALL HvNAMELEN_get"
9517 .IX Header "HV Handling"
9518 A HV structure represents a Perl hash. It consists mainly of an array
9519 of pointers, each of which points to a linked list of HE structures. The
9520 array is indexed by the hash function of the key, so each linked list
9521 represents all the hash entries with the same hash value. Each HE contains
9522 a pointer to the actual value, plus a pointer to a HEK structure which
9523 holds the key and hash value.
9524 .ie n .IP """get_hv""" 4
9525 .el .IP \f(CWget_hv\fR 4
9526 .IX Xref "get_hv"
9527 .IX Item "get_hv"
9528 Returns the HV of the specified Perl hash. \f(CW\*(C`flags\*(C'\fR are passed to
9529 \&\f(CW\*(C`gv_fetchpv\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
9530 Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero
9531 (ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is
9532 returned.
9533 .Sp
9534 NOTE: the \f(CWperl_get_hv()\fR form is \fBdeprecated\fR.
9535 .RS 4
9536 .Sp
9537 .Vb 1
9538 \& HV * get_hv(const char *name, I32 flags)
9539 .Ve
9540 .RE
9541 .RS 4
9542 .RE
9543 .ie n .IP """HE""" 4
9544 .el .IP \f(CWHE\fR 4
9545 .IX Item "HE"
9546 Described in perlguts.
9547 .ie n .IP """HEf_SVKEY""" 4
9548 .el .IP \f(CWHEf_SVKEY\fR 4
9549 .IX Xref "HEf_SVKEY"
9550 .IX Item "HEf_SVKEY"
9551 This flag, used in the length slot of hash entries and magic structures,
9552 specifies the structure contains an \f(CW\*(C`SV*\*(C'\fR pointer where a \f(CW\*(C`char*\*(C'\fR pointer
9553 is to be expected. (For information only\-\-not to be used).
9554 .ie n .IP """HeHASH""" 4
9555 .el .IP \f(CWHeHASH\fR 4
9556 .IX Xref "HeHASH"
9557 .IX Item "HeHASH"
9558 Returns the computed hash stored in the hash entry.
9559 .RS 4
9560 .Sp
9561 .Vb 1
9562 \& U32 HeHASH(HE* he)
9563 .Ve
9564 .RE
9565 .RS 4
9566 .RE
9567 .ie n .IP """HeKEY""" 4
9568 .el .IP \f(CWHeKEY\fR 4
9569 .IX Xref "HeKEY"
9570 .IX Item "HeKEY"
9571 Returns the actual pointer stored in the key slot of the hash entry. The
9572 pointer may be either \f(CW\*(C`char*\*(C'\fR or \f(CW\*(C`SV*\*(C'\fR, depending on the value of
9573 \&\f(CWHeKLEN()\fR. Can be assigned to. The \f(CWHePV()\fR or \f(CWHeSVKEY()\fR macros are
9574 usually preferable for finding the value of a key.
9575 .RS 4
9576 .Sp
9577 .Vb 1
9578 \& void* HeKEY(HE* he)
9579 .Ve
9580 .RE
9581 .RS 4
9582 .RE
9583 .ie n .IP """HeKLEN""" 4
9584 .el .IP \f(CWHeKLEN\fR 4
9585 .IX Xref "HeKLEN"
9586 .IX Item "HeKLEN"
9587 If this is negative, and amounts to \f(CW\*(C`HEf_SVKEY\*(C'\fR, it indicates the entry
9588 holds an \f(CW\*(C`SV*\*(C'\fR key. Otherwise, holds the actual length of the key. Can
9589 be assigned to. The \f(CWHePV()\fR macro is usually preferable for finding key
9590 lengths.
9591 .RS 4
9592 .Sp
9593 .Vb 1
9594 \& STRLEN HeKLEN(HE* he)
9595 .Ve
9596 .RE
9597 .RS 4
9598 .RE
9599 .ie n .IP """HePV""" 4
9600 .el .IP \f(CWHePV\fR 4
9601 .IX Xref "HePV"
9602 .IX Item "HePV"
9603 Returns the key slot of the hash entry as a \f(CW\*(C`char*\*(C'\fR value, doing any
9604 necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The length of the string
9605 is placed in \f(CW\*(C`len\*(C'\fR (this is a macro, so do \fInot\fR use \f(CW&len\fR). If you do
9606 not care about what the length of the key is, you may use the global
9607 variable \f(CW\*(C`PL_na\*(C'\fR, though this is rather less efficient than using a local
9608 variable. Remember though, that hash keys in perl are free to contain
9609 embedded nulls, so using \f(CWstrlen()\fR or similar is not a good way to find
9610 the length of hash keys. This is very similar to the \f(CWSvPV()\fR macro
9611 described elsewhere in this document. See also \f(CW"HeUTF8"\fR.
9612 .Sp
9613 If you are using \f(CW\*(C`HePV\*(C'\fR to get values to pass to \f(CWnewSVpvn()\fR to create a
9614 new SV, you should consider using \f(CW\*(C`newSVhek(HeKEY_hek(he))\*(C'\fR as it is more
9615 efficient.
9616 .RS 4
9617 .Sp
9618 .Vb 1
9619 \& char* HePV(HE* he, STRLEN len)
9620 .Ve
9621 .RE
9622 .RS 4
9623 .RE
9624 .ie n .IP """HeSVKEY""" 4
9625 .el .IP \f(CWHeSVKEY\fR 4
9626 .IX Xref "HeSVKEY"
9627 .IX Item "HeSVKEY"
9628 Returns the key as an \f(CW\*(C`SV*\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if the hash entry does not
9629 contain an \f(CW\*(C`SV*\*(C'\fR key.
9630 .RS 4
9631 .Sp
9632 .Vb 1
9633 \& SV* HeSVKEY(HE* he)
9634 .Ve
9635 .RE
9636 .RS 4
9637 .RE
9638 .ie n .IP """HeSVKEY_force""" 4
9639 .el .IP \f(CWHeSVKEY_force\fR 4
9640 .IX Xref "HeSVKEY_force"
9641 .IX Item "HeSVKEY_force"
9642 Returns the key as an \f(CW\*(C`SV*\*(C'\fR. Will create and return a temporary mortal
9643 \&\f(CW\*(C`SV*\*(C'\fR if the hash entry contains only a \f(CW\*(C`char*\*(C'\fR key.
9644 .RS 4
9645 .Sp
9646 .Vb 1
9647 \& SV* HeSVKEY_force(HE* he)
9648 .Ve
9649 .RE
9650 .RS 4
9651 .RE
9652 .ie n .IP """HeSVKEY_set""" 4
9653 .el .IP \f(CWHeSVKEY_set\fR 4
9654 .IX Xref "HeSVKEY_set"
9655 .IX Item "HeSVKEY_set"
9656 Sets the key to a given \f(CW\*(C`SV*\*(C'\fR, taking care to set the appropriate flags to
9657 indicate the presence of an \f(CW\*(C`SV*\*(C'\fR key, and returns the same
9658 \&\f(CW\*(C`SV*\*(C'\fR.
9659 .RS 4
9660 .Sp
9661 .Vb 1
9662 \& SV* HeSVKEY_set(HE* he, SV* sv)
9663 .Ve
9664 .RE
9665 .RS 4
9666 .RE
9667 .ie n .IP """HeUTF8""" 4
9668 .el .IP \f(CWHeUTF8\fR 4
9669 .IX Xref "HeUTF8"
9670 .IX Item "HeUTF8"
9671 Returns whether the \f(CW\*(C`char *\*(C'\fR value returned by \f(CW\*(C`HePV\*(C'\fR is encoded in UTF\-8,
9672 doing any necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The value returned
9673 will be 0 or non\-0, not necessarily 1 (or even a value with any low bits set),
9674 so \fBdo not\fR blindly assign this to a \f(CW\*(C`bool\*(C'\fR variable, as \f(CW\*(C`bool\*(C'\fR may be a
9675 typedef for \f(CW\*(C`char\*(C'\fR.
9676 .RS 4
9677 .Sp
9678 .Vb 1
9679 \& U32 HeUTF8(HE* he)
9680 .Ve
9681 .RE
9682 .RS 4
9683 .RE
9684 .ie n .IP """HeVAL""" 4
9685 .el .IP \f(CWHeVAL\fR 4
9686 .IX Xref "HeVAL"
9687 .IX Item "HeVAL"
9688 Returns the value slot (type \f(CW\*(C`SV*\*(C'\fR)
9689 stored in the hash entry. Can be assigned
9690 to.
9691 .Sp
9692 .Vb 2
9693 \& SV *foo= HeVAL(hv);
9694 \& HeVAL(hv)= sv;
9695 .Ve
9696 .RS 4
9697 .Sp
9698 .Vb 1
9699 \& SV* HeVAL(HE* he)
9700 .Ve
9701 .RE
9702 .RS 4
9703 .RE
9704 .ie n .IP """HV""" 4
9705 .el .IP \f(CWHV\fR 4
9706 .IX Item "HV"
9707 Described in perlguts.
9708 .ie n .IP """hv_assert""" 4
9709 .el .IP \f(CWhv_assert\fR 4
9710 .IX Xref "hv_assert"
9711 .IX Item "hv_assert"
9712 Check that a hash is in an internally consistent state.
9713 .Sp
9714 NOTE: \f(CW\*(C`hv_assert\*(C'\fR must be explicitly called as
9715 \&\f(CW\*(C`Perl_hv_assert\*(C'\fR
9716 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
9717 .RS 4
9718 .Sp
9719 .Vb 1
9720 \& void Perl_hv_assert(pTHX_ HV *hv)
9721 .Ve
9722 .RE
9723 .RS 4
9724 .RE
9725 .ie n .IP """hv_bucket_ratio""" 4
9726 .el .IP \f(CWhv_bucket_ratio\fR 4
9727 .IX Xref "hv_bucket_ratio"
9728 .IX Item "hv_bucket_ratio"
9729 NOTE: \f(CW\*(C`hv_bucket_ratio\*(C'\fR is \fBexperimental\fR and may change or be
9730 removed without notice.
9731 .Sp
9732 If the hash is tied dispatches through to the SCALAR tied method,
9733 otherwise if the hash contains no keys returns 0, otherwise returns
9734 a mortal sv containing a string specifying the number of used buckets,
9735 followed by a slash, followed by the number of available buckets.
9736 .Sp
9737 This function is expensive, it must scan all of the buckets
9738 to determine which are used, and the count is NOT cached.
9739 In a large hash this could be a lot of buckets.
9740 .RS 4
9741 .Sp
9742 .Vb 1
9743 \& SV * hv_bucket_ratio(HV *hv)
9744 .Ve
9745 .RE
9746 .RS 4
9747 .RE
9748 .ie n .IP """hv_clear""" 4
9749 .el .IP \f(CWhv_clear\fR 4
9750 .IX Xref "hv_clear"
9751 .IX Item "hv_clear"
9752 Frees all the elements of a hash, leaving it empty.
9753 The XS equivalent of \f(CW\*(C`%hash = ()\*(C'\fR. See also "hv_undef".
9754 .Sp
9755 See "av_clear" for a note about the hash possibly being invalid on
9756 return.
9757 .RS 4
9758 .Sp
9759 .Vb 1
9760 \& void hv_clear(HV *hv)
9761 .Ve
9762 .RE
9763 .RS 4
9764 .RE
9765 .ie n .IP """hv_clear_placeholders""" 4
9766 .el .IP \f(CWhv_clear_placeholders\fR 4
9767 .IX Xref "hv_clear_placeholders"
9768 .IX Item "hv_clear_placeholders"
9769 Clears any placeholders from a hash. If a restricted hash has any of its keys
9770 marked as readonly and the key is subsequently deleted, the key is not actually
9771 deleted but is marked by assigning it a value of \f(CW&PL_sv_placeholder\fR. This tags
9772 it so it will be ignored by future operations such as iterating over the hash,
9773 but will still allow the hash to have a value reassigned to the key at some
9774 future point. This function clears any such placeholder keys from the hash.
9775 See \f(CWHash::Util::lock_keys()\fR for an example of its
9776 use.
9777 .RS 4
9778 .Sp
9779 .Vb 1
9780 \& void hv_clear_placeholders(HV *hv)
9781 .Ve
9782 .RE
9783 .RS 4
9784 .RE
9785 .ie n .IP """hv_copy_hints_hv""" 4
9786 .el .IP \f(CWhv_copy_hints_hv\fR 4
9787 .IX Xref "hv_copy_hints_hv"
9788 .IX Item "hv_copy_hints_hv"
9789 A specialised version of "newHVhv" for copying \f(CW\*(C`%^H\*(C'\fR. \f(CW\*(C`ohv\*(C'\fR must be
9790 a pointer to a hash (which may have \f(CW\*(C`%^H\*(C'\fR magic, but should be generally
9791 non-magical), or \f(CW\*(C`NULL\*(C'\fR (interpreted as an empty hash). The content
9792 of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash, which has the \f(CW\*(C`%^H\*(C'\fR\-specific magic
9793 added to it. A pointer to the new hash is returned.
9794 .RS 4
9795 .Sp
9796 .Vb 1
9797 \& HV * hv_copy_hints_hv(HV * const ohv)
9798 .Ve
9799 .RE
9800 .RS 4
9801 .RE
9802 .ie n .IP """hv_delete""" 4
9803 .el .IP \f(CWhv_delete\fR 4
9804 .IX Item "hv_delete"
9805 .PD 0
9806 .ie n .IP """hv_deletes""" 4
9807 .el .IP \f(CWhv_deletes\fR 4
9808 .IX Xref "hv_delete hv_deletes"
9809 .IX Item "hv_deletes"
9810 .PD
9811 These delete a key/value pair in the hash. The value's SV is removed from
9812 the hash, made mortal, and returned to the caller.
9813 .Sp
9814 In \f(CW\*(C`hv_deletes\*(C'\fR, the key must be a C language string literal, enclosed in
9815 double quotes. It is never treated as being in UTF\-8. There is no
9816 length_parameter.
9817 .Sp
9818 In \f(CW\*(C`hv_delete\*(C'\fR, the absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key. If
9819 \&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode.
9820 .Sp
9821 In both, the \f(CW\*(C`flags\*(C'\fR value will normally be zero; if set to \f(CW\*(C`G_DISCARD\*(C'\fR then
9822 \&\f(CW\*(C`NULL\*(C'\fR will be returned. \f(CW\*(C`NULL\*(C'\fR will also be returned if the key is not
9823 found.
9824 .RS 4
9825 .Sp
9826 .Vb 2
9827 \& SV * hv_delete (HV *hv, const char *key, I32 klen, I32 flags)
9828 \& SV * hv_deletes(HV *hv, "key", U32 flags)
9829 .Ve
9830 .RE
9831 .RS 4
9832 .RE
9833 .ie n .IP """hv_delete_ent""" 4
9834 .el .IP \f(CWhv_delete_ent\fR 4
9835 .IX Xref "hv_delete_ent"
9836 .IX Item "hv_delete_ent"
9837 Deletes a key/value pair in the hash. The value SV is removed from the hash,
9838 made mortal, and returned to the caller. The \f(CW\*(C`flags\*(C'\fR value will normally be
9839 zero; if set to \f(CW\*(C`G_DISCARD\*(C'\fR then \f(CW\*(C`NULL\*(C'\fR will be returned. \f(CW\*(C`NULL\*(C'\fR will also
9840 be returned if the key is not found. \f(CW\*(C`hash\*(C'\fR can be a valid precomputed hash
9841 value, or 0 to ask for it to be computed.
9842 .RS 4
9843 .Sp
9844 .Vb 1
9845 \& SV * hv_delete_ent(HV *hv, SV *keysv, I32 flags, U32 hash)
9846 .Ve
9847 .RE
9848 .RS 4
9849 .RE
9850 .ie n .IP """HvENAME""" 4
9851 .el .IP \f(CWHvENAME\fR 4
9852 .IX Xref "HvENAME"
9853 .IX Item "HvENAME"
9854 Returns the effective name of a stash, or NULL if there is none. The
9855 effective name represents a location in the symbol table where this stash
9856 resides. It is updated automatically when packages are aliased or deleted.
9857 A stash that is no longer in the symbol table has no effective name. This
9858 name is preferable to \f(CW\*(C`HvNAME\*(C'\fR for use in MRO linearisations and isa
9859 caches.
9860 .RS 4
9861 .Sp
9862 .Vb 1
9863 \& char* HvENAME(HV* stash)
9864 .Ve
9865 .RE
9866 .RS 4
9867 .RE
9868 .ie n .IP """HvENAMELEN""" 4
9869 .el .IP \f(CWHvENAMELEN\fR 4
9870 .IX Xref "HvENAMELEN"
9871 .IX Item "HvENAMELEN"
9872 Returns the length of the stash's effective name.
9873 .RS 4
9874 .Sp
9875 .Vb 1
9876 \& STRLEN HvENAMELEN(HV *stash)
9877 .Ve
9878 .RE
9879 .RS 4
9880 .RE
9881 .ie n .IP """HvENAMEUTF8""" 4
9882 .el .IP \f(CWHvENAMEUTF8\fR 4
9883 .IX Xref "HvENAMEUTF8"
9884 .IX Item "HvENAMEUTF8"
9885 Returns true if the effective name is in UTF\-8 encoding.
9886 .RS 4
9887 .Sp
9888 .Vb 1
9889 \& unsigned char HvENAMEUTF8(HV *stash)
9890 .Ve
9891 .RE
9892 .RS 4
9893 .RE
9894 .ie n .IP """hv_exists""" 4
9895 .el .IP \f(CWhv_exists\fR 4
9896 .IX Item "hv_exists"
9897 .PD 0
9898 .ie n .IP """hv_existss""" 4
9899 .el .IP \f(CWhv_existss\fR 4
9900 .IX Xref "hv_exists hv_existss"
9901 .IX Item "hv_existss"
9902 .PD
9903 These return a boolean indicating whether the specified hash key exists.
9904 .Sp
9905 In \f(CW\*(C`hv_existss\*(C'\fR, the key must be a C language string literal, enclosed in
9906 double quotes. It is never treated as being in UTF\-8. There is no
9907 length_parameter.
9908 .Sp
9909 In \f(CW\*(C`hv_exists\*(C'\fR, the absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key. If
9910 \&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode.
9911 .RS 4
9912 .Sp
9913 .Vb 2
9914 \& bool hv_exists (HV *hv, const char *key, I32 klen)
9915 \& bool hv_existss(HV *hv, "key")
9916 .Ve
9917 .RE
9918 .RS 4
9919 .RE
9920 .ie n .IP """hv_exists_ent""" 4
9921 .el .IP \f(CWhv_exists_ent\fR 4
9922 .IX Xref "hv_exists_ent"
9923 .IX Item "hv_exists_ent"
9924 Returns a boolean indicating whether
9925 the specified hash key exists. \f(CW\*(C`hash\*(C'\fR
9926 can be a valid precomputed hash value, or 0 to ask for it to be
9927 computed.
9928 .RS 4
9929 .Sp
9930 .Vb 1
9931 \& bool hv_exists_ent(HV *hv, SV *keysv, U32 hash)
9932 .Ve
9933 .RE
9934 .RS 4
9935 .RE
9936 .ie n .IP """hv_fetch""" 4
9937 .el .IP \f(CWhv_fetch\fR 4
9938 .IX Item "hv_fetch"
9939 .PD 0
9940 .ie n .IP """hv_fetchs""" 4
9941 .el .IP \f(CWhv_fetchs\fR 4
9942 .IX Xref "hv_fetch hv_fetchs"
9943 .IX Item "hv_fetchs"
9944 .PD
9945 These return the SV which corresponds to the specified key in the hash.
9946 .Sp
9947 In \f(CW\*(C`hv_fetchs\*(C'\fR, the key must be a C language string literal, enclosed in
9948 double quotes. It is never treated as being in UTF\-8. There is no
9949 length_parameter.
9950 .Sp
9951 In \f(CW\*(C`hv_fetch\*(C'\fR, the absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key. If
9952 \&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode.
9953 .Sp
9954 In both, if \f(CW\*(C`lval\*(C'\fR is set, then the fetch will be part of a store. This means
9955 that if there is no value in the hash associated with the given key, then one
9956 is created and a pointer to it is returned. The \f(CW\*(C`SV*\*(C'\fR it points to can be
9957 assigned to. But always check that the return value is non-null before
9958 dereferencing it to an \f(CW\*(C`SV*\*(C'\fR.
9959 .Sp
9960 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
9961 information on how to use this function on tied hashes.
9962 .RS 4
9963 .Sp
9964 .Vb 2
9965 \& SV ** hv_fetch (HV *hv, const char *key, I32 klen, I32 lval)
9966 \& SV ** hv_fetchs(HV *hv, "key", I32 lval)
9967 .Ve
9968 .RE
9969 .RS 4
9970 .RE
9971 .ie n .IP """hv_fetch_ent""" 4
9972 .el .IP \f(CWhv_fetch_ent\fR 4
9973 .IX Xref "hv_fetch_ent"
9974 .IX Item "hv_fetch_ent"
9975 Returns the hash entry which corresponds to the specified key in the hash.
9976 \&\f(CW\*(C`hash\*(C'\fR must be a valid precomputed hash number for the given \f(CW\*(C`key\*(C'\fR, or 0
9977 if you want the function to compute it. IF \f(CW\*(C`lval\*(C'\fR is set then the fetch
9978 will be part of a store. Make sure the return value is non-null before
9979 accessing it. The return value when \f(CW\*(C`hv\*(C'\fR is a tied hash is a pointer to a
9980 static location, so be sure to make a copy of the structure if you need to
9981 store it somewhere.
9982 .Sp
9983 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
9984 information on how to use this function on tied hashes.
9985 .RS 4
9986 .Sp
9987 .Vb 1
9988 \& HE * hv_fetch_ent(HV *hv, SV *keysv, I32 lval, U32 hash)
9989 .Ve
9990 .RE
9991 .RS 4
9992 .RE
9993 .ie n .IP """hv_fetchs""" 4
9994 .el .IP \f(CWhv_fetchs\fR 4
9995 .IX Xref "hv_fetchs"
9996 .IX Item "hv_fetchs"
9997 Like \f(CW\*(C`hv_fetch\*(C'\fR, but takes a literal string instead of a
9998 string/length pair.
9999 .RS 4
10000 .Sp
10001 .Vb 1
10002 \& SV** hv_fetchs(HV* tb, "key", I32 lval)
10003 .Ve
10004 .RE
10005 .RS 4
10006 .RE
10007 .ie n .IP """HvFILL""" 4
10008 .el .IP \f(CWHvFILL\fR 4
10009 .IX Xref "HvFILL"
10010 .IX Item "HvFILL"
10011 Returns the number of hash buckets that happen to be in use.
10012 .Sp
10013 As of perl 5.25 this function is used only for debugging
10014 purposes, and the number of used hash buckets is not
10015 in any way cached, thus this function can be costly
10016 to execute as it must iterate over all the buckets in the
10017 hash.
10018 .RS 4
10019 .Sp
10020 .Vb 1
10021 \& STRLEN HvFILL(HV *const hv)
10022 .Ve
10023 .RE
10024 .RS 4
10025 .RE
10026 .ie n .IP """HvHasAUX""" 4
10027 .el .IP \f(CWHvHasAUX\fR 4
10028 .IX Xref "HvHasAUX"
10029 .IX Item "HvHasAUX"
10030 Returns true if the HV has a \f(CW\*(C`struct xpvhv_aux\*(C'\fR extension. Use this to check
10031 whether it is valid to call \f(CWHvAUX()\fR.
10032 .RS 4
10033 .Sp
10034 .Vb 1
10035 \& bool HvHasAUX(HV *const hv)
10036 .Ve
10037 .RE
10038 .RS 4
10039 .RE
10040 .ie n .IP """hv_iterinit""" 4
10041 .el .IP \f(CWhv_iterinit\fR 4
10042 .IX Xref "hv_iterinit"
10043 .IX Item "hv_iterinit"
10044 Prepares a starting point to traverse a hash table. Returns the number of
10045 keys in the hash, including placeholders (i.e. the same as \f(CWHvTOTALKEYS(hv)\fR).
10046 The return value is currently only meaningful for hashes without tie magic.
10047 .Sp
10048 NOTE: Before version 5.004_65, \f(CW\*(C`hv_iterinit\*(C'\fR used to return the number of
10049 hash buckets that happen to be in use. If you still need that esoteric
10050 value, you can get it through the macro \f(CWHvFILL(hv)\fR.
10051 .RS 4
10052 .Sp
10053 .Vb 1
10054 \& I32 hv_iterinit(HV *hv)
10055 .Ve
10056 .RE
10057 .RS 4
10058 .RE
10059 .ie n .IP """hv_iterkey""" 4
10060 .el .IP \f(CWhv_iterkey\fR 4
10061 .IX Xref "hv_iterkey"
10062 .IX Item "hv_iterkey"
10063 Returns the key from the current position of the hash iterator. See
10064 \&\f(CW"hv_iterinit"\fR.
10065 .RS 4
10066 .Sp
10067 .Vb 1
10068 \& char * hv_iterkey(HE *entry, I32 *retlen)
10069 .Ve
10070 .RE
10071 .RS 4
10072 .RE
10073 .ie n .IP """hv_iterkeysv""" 4
10074 .el .IP \f(CWhv_iterkeysv\fR 4
10075 .IX Xref "hv_iterkeysv"
10076 .IX Item "hv_iterkeysv"
10077 Returns the key as an \f(CW\*(C`SV*\*(C'\fR from the current position of the hash
10078 iterator. The return value will always be a mortal copy of the key. Also
10079 see \f(CW"hv_iterinit"\fR.
10080 .RS 4
10081 .Sp
10082 .Vb 1
10083 \& SV * hv_iterkeysv(HE *entry)
10084 .Ve
10085 .RE
10086 .RS 4
10087 .RE
10088 .ie n .IP """hv_iternext""" 4
10089 .el .IP \f(CWhv_iternext\fR 4
10090 .IX Xref "hv_iternext"
10091 .IX Item "hv_iternext"
10092 Returns entries from a hash iterator. See \f(CW"hv_iterinit"\fR.
10093 .Sp
10094 You may call \f(CW\*(C`hv_delete\*(C'\fR or \f(CW\*(C`hv_delete_ent\*(C'\fR on the hash entry that the
10095 iterator currently points to, without losing your place or invalidating your
10096 iterator. Note that in this case the current entry is deleted from the hash
10097 with your iterator holding the last reference to it. Your iterator is flagged
10098 to free the entry on the next call to \f(CW\*(C`hv_iternext\*(C'\fR, so you must not discard
10099 your iterator immediately else the entry will leak \- call \f(CW\*(C`hv_iternext\*(C'\fR to
10100 trigger the resource deallocation.
10101 .RS 4
10102 .Sp
10103 .Vb 1
10104 \& HE * hv_iternext(HV *hv)
10105 .Ve
10106 .RE
10107 .RS 4
10108 .RE
10109 .ie n .IP """hv_iternext_flags""" 4
10110 .el .IP \f(CWhv_iternext_flags\fR 4
10111 .IX Xref "hv_iternext_flags"
10112 .IX Item "hv_iternext_flags"
10113 NOTE: \f(CW\*(C`hv_iternext_flags\*(C'\fR is \fBexperimental\fR and may change or be
10114 removed without notice.
10115 .Sp
10116 Returns entries from a hash iterator. See \f(CW"hv_iterinit"\fR and
10117 \&\f(CW"hv_iternext"\fR.
10118 The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if \f(CW\*(C`HV_ITERNEXT_WANTPLACEHOLDERS\*(C'\fR is
10119 set the placeholders keys (for restricted hashes) will be returned in addition
10120 to normal keys. By default placeholders are automatically skipped over.
10121 Currently a placeholder is implemented with a value that is
10122 \&\f(CW&PL_sv_placeholder\fR. Note that the implementation of placeholders and
10123 restricted hashes may change, and the implementation currently is
10124 insufficiently abstracted for any change to be tidy.
10125 .RS 4
10126 .Sp
10127 .Vb 1
10128 \& HE * hv_iternext_flags(HV *hv, I32 flags)
10129 .Ve
10130 .RE
10131 .RS 4
10132 .RE
10133 .ie n .IP """hv_iternextsv""" 4
10134 .el .IP \f(CWhv_iternextsv\fR 4
10135 .IX Xref "hv_iternextsv"
10136 .IX Item "hv_iternextsv"
10137 Performs an \f(CW\*(C`hv_iternext\*(C'\fR, \f(CW\*(C`hv_iterkey\*(C'\fR, and \f(CW\*(C`hv_iterval\*(C'\fR in one
10138 operation.
10139 .RS 4
10140 .Sp
10141 .Vb 1
10142 \& SV * hv_iternextsv(HV *hv, char **key, I32 *retlen)
10143 .Ve
10144 .RE
10145 .RS 4
10146 .RE
10147 .ie n .IP """hv_iterval""" 4
10148 .el .IP \f(CWhv_iterval\fR 4
10149 .IX Xref "hv_iterval"
10150 .IX Item "hv_iterval"
10151 Returns the value from the current position of the hash iterator. See
10152 \&\f(CW"hv_iterkey"\fR.
10153 .RS 4
10154 .Sp
10155 .Vb 1
10156 \& SV * hv_iterval(HV *hv, HE *entry)
10157 .Ve
10158 .RE
10159 .RS 4
10160 .RE
10161 .ie n .IP """hv_ksplit""" 4
10162 .el .IP \f(CWhv_ksplit\fR 4
10163 .IX Xref "hv_ksplit"
10164 .IX Item "hv_ksplit"
10165 Attempt to grow the hash \f(CW\*(C`hv\*(C'\fR so it has at least \f(CW\*(C`newmax\*(C'\fR buckets available.
10166 Perl chooses the actual number for its convenience.
10167 .Sp
10168 This is the same as doing the following in Perl code:
10169 .Sp
10170 .Vb 1
10171 \& keys %hv = newmax;
10172 .Ve
10173 .RS 4
10174 .Sp
10175 .Vb 1
10176 \& void hv_ksplit(HV *hv, IV newmax)
10177 .Ve
10178 .RE
10179 .RS 4
10180 .RE
10181 .ie n .IP """hv_magic""" 4
10182 .el .IP \f(CWhv_magic\fR 4
10183 .IX Xref "hv_magic"
10184 .IX Item "hv_magic"
10185 Adds magic to a hash. See \f(CW"sv_magic"\fR.
10186 .RS 4
10187 .Sp
10188 .Vb 1
10189 \& void hv_magic(HV *hv, GV *gv, int how)
10190 .Ve
10191 .RE
10192 .RS 4
10193 .RE
10194 .ie n .IP """HvNAME""" 4
10195 .el .IP \f(CWHvNAME\fR 4
10196 .IX Xref "HvNAME"
10197 .IX Item "HvNAME"
10198 Returns the package name of a stash, or \f(CW\*(C`NULL\*(C'\fR if \f(CW\*(C`stash\*(C'\fR isn't a stash.
10199 See \f(CW"SvSTASH"\fR, \f(CW"CvSTASH"\fR.
10200 .RS 4
10201 .Sp
10202 .Vb 1
10203 \& char* HvNAME(HV* stash)
10204 .Ve
10205 .RE
10206 .RS 4
10207 .RE
10208 .ie n .IP """HvNAMELEN""" 4
10209 .el .IP \f(CWHvNAMELEN\fR 4
10210 .IX Xref "HvNAMELEN"
10211 .IX Item "HvNAMELEN"
10212 Returns the length of the stash's name.
10213 .Sp
10214 Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
10215 .RS 4
10216 .Sp
10217 .Vb 1
10218 \& STRLEN HvNAMELEN(HV *stash)
10219 .Ve
10220 .RE
10221 .RS 4
10222 .RE
10223 .ie n .IP """hv_name_set""" 4
10224 .el .IP \f(CWhv_name_set\fR 4
10225 .IX Item "hv_name_set"
10226 .PD 0
10227 .ie n .IP """hv_name_sets""" 4
10228 .el .IP \f(CWhv_name_sets\fR 4
10229 .IX Xref "hv_name_set hv_name_sets"
10230 .IX Item "hv_name_sets"
10231 .PD
10232 These each set the name of stash \f(CW\*(C`hv\*(C'\fR to the specified name.
10233 .Sp
10234 They differ only in how the name is specified.
10235 .Sp
10236 In \f(CW\*(C`hv_name_sets\*(C'\fR, the name is a literal C string, enclosed in double quotes.
10237 .Sp
10238 In \f(CW\*(C`hv_name_set\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and an
10239 additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, the name
10240 may contain embedded-NUL characters.
10241 .Sp
10242 If \f(CW\*(C`SVf_UTF8\*(C'\fR is set in \f(CW\*(C`flags\*(C'\fR, the name is treated as being in UTF\-8;
10243 otherwise not.
10244 .Sp
10245 If \f(CW\*(C`HV_NAME_SETALL\*(C'\fR is set in \f(CW\*(C`flags\*(C'\fR, both the name and the effective name
10246 are set.
10247 .RS 4
10248 .Sp
10249 .Vb 2
10250 \& void hv_name_set (HV *hv, const char *name, U32 len, U32 flags)
10251 \& void hv_name_sets(HV *hv, "name", U32 flags)
10252 .Ve
10253 .RE
10254 .RS 4
10255 .RE
10256 .ie n .IP """HvNAMEUTF8""" 4
10257 .el .IP \f(CWHvNAMEUTF8\fR 4
10258 .IX Xref "HvNAMEUTF8"
10259 .IX Item "HvNAMEUTF8"
10260 Returns true if the name is in UTF\-8 encoding.
10261 .RS 4
10262 .Sp
10263 .Vb 1
10264 \& unsigned char HvNAMEUTF8(HV *stash)
10265 .Ve
10266 .RE
10267 .RS 4
10268 .RE
10269 .ie n .IP """hv_scalar""" 4
10270 .el .IP \f(CWhv_scalar\fR 4
10271 .IX Xref "hv_scalar"
10272 .IX Item "hv_scalar"
10273 Evaluates the hash in scalar context and returns the result.
10274 .Sp
10275 When the hash is tied dispatches through to the SCALAR method,
10276 otherwise returns a mortal SV containing the number of keys
10277 in the hash.
10278 .Sp
10279 Note, prior to 5.25 this function returned what is now
10280 returned by the \fBhv_bucket_ratio()\fR function.
10281 .RS 4
10282 .Sp
10283 .Vb 1
10284 \& SV * hv_scalar(HV *hv)
10285 .Ve
10286 .RE
10287 .RS 4
10288 .RE
10289 .ie n .IP """hv_store""" 4
10290 .el .IP \f(CWhv_store\fR 4
10291 .IX Item "hv_store"
10292 .PD 0
10293 .ie n .IP """hv_stores""" 4
10294 .el .IP \f(CWhv_stores\fR 4
10295 .IX Xref "hv_store hv_stores"
10296 .IX Item "hv_stores"
10297 .PD
10298 These each store SV \f(CW\*(C`val\*(C'\fR with the specified key in hash \f(CW\*(C`hv\*(C'\fR, returning NULL
10299 if the operation failed or if the value did not need to be actually stored
10300 within the hash (as in the case of tied hashes). Otherwise it can be
10301 dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR.
10302 .Sp
10303 They differ only in how the hash key is specified.
10304 .Sp
10305 In \f(CW\*(C`hv_stores\*(C'\fR, the key must be a C language string literal, enclosed in
10306 double quotes. It is never treated as being in UTF\-8. There is no
10307 length_parameter.
10308 .Sp
10309 In \f(CW\*(C`hv_store\*(C'\fR, \f(CW\*(C`key\*(C'\fR is either NULL or points to the first byte of the string
10310 specifying the key, and its length in bytes is given by the absolute value of
10311 an additional parameter, \f(CW\*(C`klen\*(C'\fR. A NULL key indicates the key is to be
10312 treated as \f(CW\*(C`undef\*(C'\fR, and \f(CW\*(C`klen\*(C'\fR is ignored; otherwise the key string may
10313 contain embedded-NUL bytes. If \f(CW\*(C`klen\*(C'\fR is negative, the string is treated as
10314 being encoded in UTF\-8; otherwise not.
10315 .Sp
10316 \&\f(CW\*(C`hv_store\*(C'\fR has another extra parameter, \f(CW\*(C`hash\*(C'\fR, a precomputed hash of the key
10317 string, or zero if it has not been precomputed. This parameter is omitted from
10318 \&\f(CW\*(C`hv_stores\*(C'\fR, as it is computed automatically at compile time.
10319 .Sp
10320 If <hv> is NULL, NULL is returned and no action is taken.
10321 .Sp
10322 If \f(CW\*(C`val\*(C'\fR is NULL, it is treated as being \f(CW\*(C`undef\*(C'\fR; otherwise the caller is
10323 responsible for suitably incrementing the reference count of \f(CW\*(C`val\*(C'\fR before
10324 the call, and decrementing it if the function returned \f(CW\*(C`NULL\*(C'\fR. Effectively
10325 a successful \f(CW\*(C`hv_store\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is
10326 usually what you want; a newly created SV has a reference count of one, so
10327 if all your code does is create SVs then store them in a hash, \f(CW\*(C`hv_store\*(C'\fR
10328 will own the only reference to the new SV, and your code doesn't need to do
10329 anything further to tidy up.
10330 .Sp
10331 \&\f(CW\*(C`hv_store\*(C'\fR is not implemented as a call to "\f(CW\*(C`hv_store_ent\*(C'\fR", and does not
10332 create a temporary SV for the key, so if your key data is not already in SV
10333 form then use \f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR.
10334 .Sp
10335 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
10336 information on how to use this function on tied hashes.
10337 .RS 4
10338 .Sp
10339 .Vb 3
10340 \& SV ** hv_store (HV *hv, const char *key, I32 klen, SV *val,
10341 \& U32 hash)
10342 \& SV ** hv_stores(HV *hv, "key", SV *val)
10343 .Ve
10344 .RE
10345 .RS 4
10346 .RE
10347 .ie n .IP """hv_store_ent""" 4
10348 .el .IP \f(CWhv_store_ent\fR 4
10349 .IX Xref "hv_store_ent"
10350 .IX Item "hv_store_ent"
10351 Stores \f(CW\*(C`val\*(C'\fR in a hash. The hash key is specified as \f(CW\*(C`key\*(C'\fR. The \f(CW\*(C`hash\*(C'\fR
10352 parameter is the precomputed hash value; if it is zero then Perl will
10353 compute it. The return value is the new hash entry so created. It will be
10354 \&\f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not need to be actually
10355 stored within the hash (as in the case of tied hashes). Otherwise the
10356 contents of the return value can be accessed using the \f(CW\*(C`He?\*(C'\fR macros
10357 described here. Note that the caller is responsible for suitably
10358 incrementing the reference count of \f(CW\*(C`val\*(C'\fR before the call, and
10359 decrementing it if the function returned NULL. Effectively a successful
10360 \&\f(CW\*(C`hv_store_ent\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is
10361 usually what you want; a newly created SV has a reference count of one, so
10362 if all your code does is create SVs then store them in a hash, \f(CW\*(C`hv_store\*(C'\fR
10363 will own the only reference to the new SV, and your code doesn't need to do
10364 anything further to tidy up. Note that \f(CW\*(C`hv_store_ent\*(C'\fR only reads the \f(CW\*(C`key\*(C'\fR;
10365 unlike \f(CW\*(C`val\*(C'\fR it does not take ownership of it, so maintaining the correct
10366 reference count on \f(CW\*(C`key\*(C'\fR is entirely the caller's responsibility. The reason
10367 it does not take ownership, is that \f(CW\*(C`key\*(C'\fR is not used after this function
10368 returns, and so can be freed immediately. \f(CW\*(C`hv_store\*(C'\fR
10369 is not implemented as a call to \f(CW\*(C`hv_store_ent\*(C'\fR, and does not create a temporary
10370 SV for the key, so if your key data is not already in SV form then use
10371 \&\f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR.
10372 .Sp
10373 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
10374 information on how to use this function on tied hashes.
10375 .RS 4
10376 .Sp
10377 .Vb 1
10378 \& HE * hv_store_ent(HV *hv, SV *key, SV *val, U32 hash)
10379 .Ve
10380 .RE
10381 .RS 4
10382 .RE
10383 .ie n .IP """hv_undef""" 4
10384 .el .IP \f(CWhv_undef\fR 4
10385 .IX Xref "hv_undef"
10386 .IX Item "hv_undef"
10387 Undefines the hash. The XS equivalent of \f(CWundef(%hash)\fR.
10388 .Sp
10389 As well as freeing all the elements of the hash (like \f(CWhv_clear()\fR), this
10390 also frees any auxiliary data and storage associated with the hash.
10391 .Sp
10392 See "av_clear" for a note about the hash possibly being invalid on
10393 return.
10394 .RS 4
10395 .Sp
10396 .Vb 1
10397 \& void hv_undef(HV *hv)
10398 .Ve
10399 .RE
10400 .RS 4
10401 .RE
10402 .ie n .IP """newHV""" 4
10403 .el .IP \f(CWnewHV\fR 4
10404 .IX Xref "newHV"
10405 .IX Item "newHV"
10406 Creates a new HV. The reference count is set to 1.
10407 .RS 4
10408 .Sp
10409 .Vb 1
10410 \& HV * newHV()
10411 .Ve
10412 .RE
10413 .RS 4
10414 .RE
10415 .ie n .IP """newHVhv""" 4
10416 .el .IP \f(CWnewHVhv\fR 4
10417 .IX Xref "newHVhv"
10418 .IX Item "newHVhv"
10419 The content of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash. A pointer to the new hash is
10420 returned.
10421 .RS 4
10422 .Sp
10423 .Vb 1
10424 \& HV * newHVhv(HV *hv)
10425 .Ve
10426 .RE
10427 .RS 4
10428 .RE
10429 .ie n .IP """Nullhv""" 4
10430 .el .IP \f(CWNullhv\fR 4
10431 .IX Xref "Nullhv"
10432 .IX Item "Nullhv"
10433 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullhv\*(C'\fR
10434 from a future release of Perl. Do not use it for
10435 new code; remove it from existing code.
10436 .Sp
10437 Null HV pointer.
10438 .Sp
10439 (deprecated \- use \f(CW\*(C`(HV *)NULL\*(C'\fR instead)
10440 .ie n .IP """PERL_HASH""" 4
10441 .el .IP \f(CWPERL_HASH\fR 4
10442 .IX Item "PERL_HASH"
10443 Described in perlguts.
10444 .RS 4
10445 .Sp
10446 .Vb 1
10447 \& void PERL_HASH(U32 hash, char *key, STRLEN klen)
10448 .Ve
10449 .RE
10450 .RS 4
10451 .RE
10452 .ie n .IP """PL_modglobal""" 4
10453 .el .IP \f(CWPL_modglobal\fR 4
10454 .IX Xref "PL_modglobal"
10455 .IX Item "PL_modglobal"
10456 \&\f(CW\*(C`PL_modglobal\*(C'\fR is a general purpose, interpreter global HV for use by
10457 extensions that need to keep information on a per-interpreter basis.
10458 In a pinch, it can also be used as a symbol table for extensions
10459 to share data among each other. It is a good idea to use keys
10460 prefixed by the package name of the extension that owns the data.
10461 .Sp
10462 On threaded perls, each thread has an independent copy of this variable;
10463 each initialized at creation time with the current value of the creating
10464 thread's copy.
10465 .RS 4
10466 .Sp
10467 .Vb 1
10468 \& HV* PL_modglobal
10469 .Ve
10470 .RE
10471 .RS 4
10472 .RE
10473 .SH Input/Output
10474 .IX Header "Input/Output"
10475 .ie n .IP """do_close""" 4
10476 .el .IP \f(CWdo_close\fR 4
10477 .IX Xref "do_close"
10478 .IX Item "do_close"
10479 Close an I/O stream. This implements Perl "\f(CW\*(C`close\*(C'\fR" in perlfunc.
10480 .Sp
10481 \&\f(CW\*(C`gv\*(C'\fR is the glob associated with the stream.
10482 .Sp
10483 \&\f(CW\*(C`is_explict\*(C'\fR is \f(CW\*(C`true\*(C'\fR if this is an explicit close of the stream; \f(CW\*(C`false\*(C'\fR
10484 if it is part of another operation, such as closing a pipe (which involves
10485 implicitly closing both ends).
10486 .Sp
10487 Returns \f(CW\*(C`true\*(C'\fR if successful; otherwise returns \f(CW\*(C`false\*(C'\fR and sets \f(CW\*(C`errno\*(C'\fR to
10488 indicate the cause.
10489 .RS 4
10490 .Sp
10491 .Vb 1
10492 \& bool do_close(GV *gv, bool is_explicit)
10493 .Ve
10494 .RE
10495 .RS 4
10496 .RE
10497 .ie n .IP """IoDIRP""" 4
10498 .el .IP \f(CWIoDIRP\fR 4
10499 .IX Item "IoDIRP"
10500 Described in perlguts.
10501 .RS 4
10502 .Sp
10503 .Vb 1
10504 \& DIR * IoDIRP(IO *io)
10505 .Ve
10506 .RE
10507 .RS 4
10508 .RE
10509 .ie n .IP """IOf_FLUSH""" 4
10510 .el .IP \f(CWIOf_FLUSH\fR 4
10511 .IX Item "IOf_FLUSH"
10512 Described in perlguts.
10513 .ie n .IP """IoFLAGS""" 4
10514 .el .IP \f(CWIoFLAGS\fR 4
10515 .IX Item "IoFLAGS"
10516 Described in perlguts.
10517 .RS 4
10518 .Sp
10519 .Vb 1
10520 \& U8 IoFLAGS(IO *io)
10521 .Ve
10522 .RE
10523 .RS 4
10524 .RE
10525 .ie n .IP """IOf_UNTAINT""" 4
10526 .el .IP \f(CWIOf_UNTAINT\fR 4
10527 .IX Item "IOf_UNTAINT"
10528 Described in perlguts.
10529 .ie n .IP """IoIFP""" 4
10530 .el .IP \f(CWIoIFP\fR 4
10531 .IX Item "IoIFP"
10532 Described in perlguts.
10533 .RS 4
10534 .Sp
10535 .Vb 1
10536 \& PerlIO * IoIFP(IO *io)
10537 .Ve
10538 .RE
10539 .RS 4
10540 .RE
10541 .ie n .IP """IoOFP""" 4
10542 .el .IP \f(CWIoOFP\fR 4
10543 .IX Item "IoOFP"
10544 Described in perlguts.
10545 .RS 4
10546 .Sp
10547 .Vb 1
10548 \& PerlIO * IoOFP(IO *io)
10549 .Ve
10550 .RE
10551 .RS 4
10552 .RE
10553 .ie n .IP """IoTYPE""" 4
10554 .el .IP \f(CWIoTYPE\fR 4
10555 .IX Item "IoTYPE"
10556 Described in perlguts.
10557 .RS 4
10558 .Sp
10559 .Vb 1
10560 \& char IoTYPE(IO *io)
10561 .Ve
10562 .RE
10563 .RS 4
10564 .RE
10565 .ie n .IP """my_chsize""" 4
10566 .el .IP \f(CWmy_chsize\fR 4
10567 .IX Xref "my_chsize"
10568 .IX Item "my_chsize"
10569 The C library \fBchsize\fR\|(3) if available, or a Perl implementation of it.
10570 .RS 4
10571 .Sp
10572 .Vb 1
10573 \& I32 my_chsize(int fd, Off_t length)
10574 .Ve
10575 .RE
10576 .RS 4
10577 .RE
10578 .ie n .IP """my_dirfd""" 4
10579 .el .IP \f(CWmy_dirfd\fR 4
10580 .IX Xref "my_dirfd"
10581 .IX Item "my_dirfd"
10582 The C library \f(CWdirfd(3)\fR if available, or a Perl implementation of it, or die
10583 if not easily emulatable.
10584 .RS 4
10585 .Sp
10586 .Vb 1
10587 \& int my_dirfd(DIR *dir)
10588 .Ve
10589 .RE
10590 .RS 4
10591 .RE
10592 .ie n .IP """my_pclose""" 4
10593 .el .IP \f(CWmy_pclose\fR 4
10594 .IX Xref "my_pclose"
10595 .IX Item "my_pclose"
10596 A wrapper for the C library \fBpclose\fR\|(3). Don't use the latter, as the Perl
10597 version knows things that interact with the rest of the perl interpreter.
10598 .RS 4
10599 .Sp
10600 .Vb 1
10601 \& I32 my_pclose(PerlIO *ptr)
10602 .Ve
10603 .RE
10604 .RS 4
10605 .RE
10606 .ie n .IP """my_popen""" 4
10607 .el .IP \f(CWmy_popen\fR 4
10608 .IX Xref "my_popen"
10609 .IX Item "my_popen"
10610 A wrapper for the C library \fBpopen\fR\|(3). Don't use the latter, as the Perl
10611 version knows things that interact with the rest of the perl interpreter.
10612 .RS 4
10613 .Sp
10614 .Vb 1
10615 \& PerlIO * my_popen(const char *cmd, const char *mode)
10616 .Ve
10617 .RE
10618 .RS 4
10619 .RE
10620 .ie n .IP """newIO""" 4
10621 .el .IP \f(CWnewIO\fR 4
10622 .IX Xref "newIO"
10623 .IX Item "newIO"
10624 Create a new IO, setting the reference count to 1.
10625 .RS 4
10626 .Sp
10627 .Vb 1
10628 \& IO * newIO()
10629 .Ve
10630 .RE
10631 .RS 4
10632 .RE
10633 .ie n .IP """PERL_FLUSHALL_FOR_CHILD""" 4
10634 .el .IP \f(CWPERL_FLUSHALL_FOR_CHILD\fR 4
10635 .IX Xref "PERL_FLUSHALL_FOR_CHILD"
10636 .IX Item "PERL_FLUSHALL_FOR_CHILD"
10637 This defines a way to flush all output buffers. This may be a
10638 performance issue, so we allow people to disable it. Also, if
10639 we are using stdio, there are broken implementations of fflush(NULL)
10640 out there, Solaris being the most prominent.
10641 .RS 4
10642 .Sp
10643 .Vb 1
10644 \& void PERL_FLUSHALL_FOR_CHILD
10645 .Ve
10646 .RE
10647 .RS 4
10648 .RE
10649 .ie n .IP """PerlIO_apply_layers""" 4
10650 .el .IP \f(CWPerlIO_apply_layers\fR 4
10651 .IX Item "PerlIO_apply_layers"
10652 .PD 0
10653 .ie n .IP """PerlIO_binmode""" 4
10654 .el .IP \f(CWPerlIO_binmode\fR 4
10655 .IX Item "PerlIO_binmode"
10656 .ie n .IP """PerlIO_canset_cnt""" 4
10657 .el .IP \f(CWPerlIO_canset_cnt\fR 4
10658 .IX Item "PerlIO_canset_cnt"
10659 .ie n .IP """PerlIO_clearerr""" 4
10660 .el .IP \f(CWPerlIO_clearerr\fR 4
10661 .IX Item "PerlIO_clearerr"
10662 .ie n .IP """PerlIO_close""" 4
10663 .el .IP \f(CWPerlIO_close\fR 4
10664 .IX Item "PerlIO_close"
10665 .ie n .IP """PerlIO_debug""" 4
10666 .el .IP \f(CWPerlIO_debug\fR 4
10667 .IX Item "PerlIO_debug"
10668 .ie n .IP """PerlIO_eof""" 4
10669 .el .IP \f(CWPerlIO_eof\fR 4
10670 .IX Item "PerlIO_eof"
10671 .ie n .IP """PerlIO_error""" 4
10672 .el .IP \f(CWPerlIO_error\fR 4
10673 .IX Item "PerlIO_error"
10674 .ie n .IP """PerlIO_exportFILE""" 4
10675 .el .IP \f(CWPerlIO_exportFILE\fR 4
10676 .IX Item "PerlIO_exportFILE"
10677 .ie n .IP """PerlIO_fast_gets""" 4
10678 .el .IP \f(CWPerlIO_fast_gets\fR 4
10679 .IX Item "PerlIO_fast_gets"
10680 .ie n .IP """PerlIO_fdopen""" 4
10681 .el .IP \f(CWPerlIO_fdopen\fR 4
10682 .IX Item "PerlIO_fdopen"
10683 .ie n .IP """PerlIO_fileno""" 4
10684 .el .IP \f(CWPerlIO_fileno\fR 4
10685 .IX Item "PerlIO_fileno"
10686 .ie n .IP """PerlIO_fill""" 4
10687 .el .IP \f(CWPerlIO_fill\fR 4
10688 .IX Item "PerlIO_fill"
10689 .ie n .IP """PerlIO_findFILE""" 4
10690 .el .IP \f(CWPerlIO_findFILE\fR 4
10691 .IX Item "PerlIO_findFILE"
10692 .ie n .IP """PerlIO_flush""" 4
10693 .el .IP \f(CWPerlIO_flush\fR 4
10694 .IX Item "PerlIO_flush"
10695 .ie n .IP """PerlIO_get_base""" 4
10696 .el .IP \f(CWPerlIO_get_base\fR 4
10697 .IX Item "PerlIO_get_base"
10698 .ie n .IP """PerlIO_get_bufsiz""" 4
10699 .el .IP \f(CWPerlIO_get_bufsiz\fR 4
10700 .IX Item "PerlIO_get_bufsiz"
10701 .ie n .IP """PerlIO_get_cnt""" 4
10702 .el .IP \f(CWPerlIO_get_cnt\fR 4
10703 .IX Item "PerlIO_get_cnt"
10704 .ie n .IP """PerlIO_get_ptr""" 4
10705 .el .IP \f(CWPerlIO_get_ptr\fR 4
10706 .IX Item "PerlIO_get_ptr"
10707 .ie n .IP """PerlIO_getc""" 4
10708 .el .IP \f(CWPerlIO_getc\fR 4
10709 .IX Item "PerlIO_getc"
10710 .ie n .IP """PerlIO_getpos""" 4
10711 .el .IP \f(CWPerlIO_getpos\fR 4
10712 .IX Item "PerlIO_getpos"
10713 .ie n .IP """PerlIO_has_base""" 4
10714 .el .IP \f(CWPerlIO_has_base\fR 4
10715 .IX Item "PerlIO_has_base"
10716 .ie n .IP """PerlIO_has_cntptr""" 4
10717 .el .IP \f(CWPerlIO_has_cntptr\fR 4
10718 .IX Item "PerlIO_has_cntptr"
10719 .ie n .IP """PerlIO_importFILE""" 4
10720 .el .IP \f(CWPerlIO_importFILE\fR 4
10721 .IX Item "PerlIO_importFILE"
10722 .ie n .IP """PerlIO_open""" 4
10723 .el .IP \f(CWPerlIO_open\fR 4
10724 .IX Item "PerlIO_open"
10725 .ie n .IP """PerlIO_printf""" 4
10726 .el .IP \f(CWPerlIO_printf\fR 4
10727 .IX Item "PerlIO_printf"
10728 .ie n .IP """PerlIO_putc""" 4
10729 .el .IP \f(CWPerlIO_putc\fR 4
10730 .IX Item "PerlIO_putc"
10731 .ie n .IP """PerlIO_puts""" 4
10732 .el .IP \f(CWPerlIO_puts\fR 4
10733 .IX Item "PerlIO_puts"
10734 .ie n .IP """PerlIO_read""" 4
10735 .el .IP \f(CWPerlIO_read\fR 4
10736 .IX Item "PerlIO_read"
10737 .ie n .IP """PerlIO_releaseFILE""" 4
10738 .el .IP \f(CWPerlIO_releaseFILE\fR 4
10739 .IX Item "PerlIO_releaseFILE"
10740 .ie n .IP """PerlIO_reopen""" 4
10741 .el .IP \f(CWPerlIO_reopen\fR 4
10742 .IX Item "PerlIO_reopen"
10743 .ie n .IP """PerlIO_rewind""" 4
10744 .el .IP \f(CWPerlIO_rewind\fR 4
10745 .IX Item "PerlIO_rewind"
10746 .ie n .IP """PerlIO_seek""" 4
10747 .el .IP \f(CWPerlIO_seek\fR 4
10748 .IX Item "PerlIO_seek"
10749 .ie n .IP """PerlIO_set_cnt""" 4
10750 .el .IP \f(CWPerlIO_set_cnt\fR 4
10751 .IX Item "PerlIO_set_cnt"
10752 .ie n .IP """PerlIO_set_ptrcnt""" 4
10753 .el .IP \f(CWPerlIO_set_ptrcnt\fR 4
10754 .IX Item "PerlIO_set_ptrcnt"
10755 .ie n .IP """PerlIO_setlinebuf""" 4
10756 .el .IP \f(CWPerlIO_setlinebuf\fR 4
10757 .IX Item "PerlIO_setlinebuf"
10758 .ie n .IP """PerlIO_setpos""" 4
10759 .el .IP \f(CWPerlIO_setpos\fR 4
10760 .IX Item "PerlIO_setpos"
10761 .ie n .IP """PerlIO_stderr""" 4
10762 .el .IP \f(CWPerlIO_stderr\fR 4
10763 .IX Item "PerlIO_stderr"
10764 .ie n .IP """PerlIO_stdin""" 4
10765 .el .IP \f(CWPerlIO_stdin\fR 4
10766 .IX Item "PerlIO_stdin"
10767 .ie n .IP """PerlIO_stdout""" 4
10768 .el .IP \f(CWPerlIO_stdout\fR 4
10769 .IX Item "PerlIO_stdout"
10770 .ie n .IP """PerlIO_stdoutf""" 4
10771 .el .IP \f(CWPerlIO_stdoutf\fR 4
10772 .IX Item "PerlIO_stdoutf"
10773 .ie n .IP """PerlIO_tell""" 4
10774 .el .IP \f(CWPerlIO_tell\fR 4
10775 .IX Item "PerlIO_tell"
10776 .ie n .IP """PerlIO_ungetc""" 4
10777 .el .IP \f(CWPerlIO_ungetc\fR 4
10778 .IX Item "PerlIO_ungetc"
10779 .ie n .IP """PerlIO_unread""" 4
10780 .el .IP \f(CWPerlIO_unread\fR 4
10781 .IX Item "PerlIO_unread"
10782 .ie n .IP """PerlIO_vprintf""" 4
10783 .el .IP \f(CWPerlIO_vprintf\fR 4
10784 .IX Item "PerlIO_vprintf"
10785 .ie n .IP """PerlIO_write""" 4
10786 .el .IP \f(CWPerlIO_write\fR 4
10787 .IX Item "PerlIO_write"
10788 .PD
10789 Described in perlapio.
10790 .RS 4
10791 .Sp
10792 .Vb 10
10793 \& int PerlIO_apply_layers(PerlIO *f, const char *mode,
10794 \& const char *layers)
10795 \& int PerlIO_binmode (PerlIO *f, int ptype, int imode,
10796 \& const char *layers)
10797 \& int PerlIO_canset_cnt (PerlIO *f)
10798 \& void PerlIO_clearerr (PerlIO *f)
10799 \& int PerlIO_close (PerlIO *f)
10800 \& void PerlIO_debug (const char *fmt, ...)
10801 \& int PerlIO_eof (PerlIO *f)
10802 \& int PerlIO_error (PerlIO *f)
10803 \& FILE * PerlIO_exportFILE (PerlIO *f, const char *mode)
10804 \& int PerlIO_fast_gets (PerlIO *f)
10805 \& PerlIO * PerlIO_fdopen (int fd, const char *mode)
10806 \& int PerlIO_fileno (PerlIO *f)
10807 \& int PerlIO_fill (PerlIO *f)
10808 \& FILE * PerlIO_findFILE (PerlIO *f)
10809 \& int PerlIO_flush (PerlIO *f)
10810 \& STDCHAR * PerlIO_get_base (PerlIO *f)
10811 \& SSize_t PerlIO_get_bufsiz (PerlIO *f)
10812 \& SSize_t PerlIO_get_cnt (PerlIO *f)
10813 \& STDCHAR * PerlIO_get_ptr (PerlIO *f)
10814 \& int PerlIO_getc (PerlIO *d)
10815 \& int PerlIO_getpos (PerlIO *f, SV *save)
10816 \& int PerlIO_has_base (PerlIO *f)
10817 \& int PerlIO_has_cntptr (PerlIO *f)
10818 \& PerlIO * PerlIO_importFILE (FILE *stdio, const char *mode)
10819 \& PerlIO * PerlIO_open (const char *path, const char *mode)
10820 \& int PerlIO_printf (PerlIO *f, const char *fmt, ...)
10821 \& int PerlIO_putc (PerlIO *f, int ch)
10822 \& int PerlIO_puts (PerlIO *f, const char *string)
10823 \& SSize_t PerlIO_read (PerlIO *f, void *vbuf,
10824 \& Size_t count)
10825 \& void PerlIO_releaseFILE (PerlIO *f, FILE *stdio)
10826 \& PerlIO * PerlIO_reopen (const char *path, const char *mode,
10827 \& PerlIO *old)
10828 \& void PerlIO_rewind (PerlIO *f)
10829 \& int PerlIO_seek (PerlIO *f, Off_t offset,
10830 \& int whence)
10831 \& void PerlIO_set_cnt (PerlIO *f, SSize_t cnt)
10832 \& void PerlIO_set_ptrcnt (PerlIO *f, STDCHAR *ptr,
10833 \& SSize_t cnt)
10834 \& void PerlIO_setlinebuf (PerlIO *f)
10835 \& int PerlIO_setpos (PerlIO *f, SV *saved)
10836 \& PerlIO * PerlIO_stderr (PerlIO *f, const char *mode,
10837 \& const char *layers)
10838 \& PerlIO * PerlIO_stdin (PerlIO *f, const char *mode,
10839 \& const char *layers)
10840 \& PerlIO * PerlIO_stdout (PerlIO *f, const char *mode,
10841 \& const char *layers)
10842 \& int PerlIO_stdoutf (const char *fmt, ...)
10843 \& Off_t PerlIO_tell (PerlIO *f)
10844 \& int PerlIO_ungetc (PerlIO *f, int ch)
10845 \& SSize_t PerlIO_unread (PerlIO *f, const void *vbuf,
10846 \& Size_t count)
10847 \& int PerlIO_vprintf (PerlIO *f, const char *fmt,
10848 \& va_list args)
10849 \& SSize_t PerlIO_write (PerlIO *f, const void *vbuf,
10850 \& Size_t count)
10851 .Ve
10852 .RE
10853 .RS 4
10854 .RE
10855 .ie n .IP """PERLIO_F_APPEND""" 4
10856 .el .IP \f(CWPERLIO_F_APPEND\fR 4
10857 .IX Item "PERLIO_F_APPEND"
10858 .PD 0
10859 .ie n .IP """PERLIO_F_CANREAD""" 4
10860 .el .IP \f(CWPERLIO_F_CANREAD\fR 4
10861 .IX Item "PERLIO_F_CANREAD"
10862 .ie n .IP """PERLIO_F_CANWRITE""" 4
10863 .el .IP \f(CWPERLIO_F_CANWRITE\fR 4
10864 .IX Item "PERLIO_F_CANWRITE"
10865 .ie n .IP """PERLIO_F_CRLF""" 4
10866 .el .IP \f(CWPERLIO_F_CRLF\fR 4
10867 .IX Item "PERLIO_F_CRLF"
10868 .ie n .IP """PERLIO_F_EOF""" 4
10869 .el .IP \f(CWPERLIO_F_EOF\fR 4
10870 .IX Item "PERLIO_F_EOF"
10871 .ie n .IP """PERLIO_F_ERROR""" 4
10872 .el .IP \f(CWPERLIO_F_ERROR\fR 4
10873 .IX Item "PERLIO_F_ERROR"
10874 .ie n .IP """PERLIO_F_FASTGETS""" 4
10875 .el .IP \f(CWPERLIO_F_FASTGETS\fR 4
10876 .IX Item "PERLIO_F_FASTGETS"
10877 .ie n .IP """PERLIO_F_LINEBUF""" 4
10878 .el .IP \f(CWPERLIO_F_LINEBUF\fR 4
10879 .IX Item "PERLIO_F_LINEBUF"
10880 .ie n .IP """PERLIO_F_OPEN""" 4
10881 .el .IP \f(CWPERLIO_F_OPEN\fR 4
10882 .IX Item "PERLIO_F_OPEN"
10883 .ie n .IP """PERLIO_F_RDBUF""" 4
10884 .el .IP \f(CWPERLIO_F_RDBUF\fR 4
10885 .IX Item "PERLIO_F_RDBUF"
10886 .ie n .IP """PERLIO_F_TEMP""" 4
10887 .el .IP \f(CWPERLIO_F_TEMP\fR 4
10888 .IX Item "PERLIO_F_TEMP"
10889 .ie n .IP """PERLIO_F_TRUNCATE""" 4
10890 .el .IP \f(CWPERLIO_F_TRUNCATE\fR 4
10891 .IX Item "PERLIO_F_TRUNCATE"
10892 .ie n .IP """PERLIO_F_UNBUF""" 4
10893 .el .IP \f(CWPERLIO_F_UNBUF\fR 4
10894 .IX Item "PERLIO_F_UNBUF"
10895 .ie n .IP """PERLIO_F_UTF8""" 4
10896 .el .IP \f(CWPERLIO_F_UTF8\fR 4
10897 .IX Item "PERLIO_F_UTF8"
10898 .ie n .IP """PERLIO_F_WRBUF""" 4
10899 .el .IP \f(CWPERLIO_F_WRBUF\fR 4
10900 .IX Item "PERLIO_F_WRBUF"
10901 .PD
10902 Described in perliol.
10903 .ie n .IP """PERLIO_FUNCS_CAST""" 4
10904 .el .IP \f(CWPERLIO_FUNCS_CAST\fR 4
10905 .IX Xref "PERLIO_FUNCS_CAST"
10906 .IX Item "PERLIO_FUNCS_CAST"
10907 Cast the pointer \f(CW\*(C`func\*(C'\fR to be of type \f(CW\*(C`PerlIO_funcs\ *\*(C'\fR.
10908 .ie n .IP """PERLIO_FUNCS_DECL""" 4
10909 .el .IP \f(CWPERLIO_FUNCS_DECL\fR 4
10910 .IX Xref "PERLIO_FUNCS_DECL"
10911 .IX Item "PERLIO_FUNCS_DECL"
10912 Declare \f(CW\*(C`ftab\*(C'\fR to be a PerlIO function table, that is, of type
10913 \&\f(CW\*(C`PerlIO_funcs\*(C'\fR.
10914 .RS 4
10915 .Sp
10916 .Vb 1
10917 \& PERLIO_FUNCS_DECL(PerlIO * ftab)
10918 .Ve
10919 .RE
10920 .RS 4
10921 .RE
10922 .ie n .IP """PERLIO_K_BUFFERED""" 4
10923 .el .IP \f(CWPERLIO_K_BUFFERED\fR 4
10924 .IX Item "PERLIO_K_BUFFERED"
10925 .PD 0
10926 .ie n .IP """PERLIO_K_CANCRLF""" 4
10927 .el .IP \f(CWPERLIO_K_CANCRLF\fR 4
10928 .IX Item "PERLIO_K_CANCRLF"
10929 .ie n .IP """PERLIO_K_FASTGETS""" 4
10930 .el .IP \f(CWPERLIO_K_FASTGETS\fR 4
10931 .IX Item "PERLIO_K_FASTGETS"
10932 .ie n .IP """PERLIO_K_MULTIARG""" 4
10933 .el .IP \f(CWPERLIO_K_MULTIARG\fR 4
10934 .IX Item "PERLIO_K_MULTIARG"
10935 .ie n .IP """PERLIO_K_RAW""" 4
10936 .el .IP \f(CWPERLIO_K_RAW\fR 4
10937 .IX Item "PERLIO_K_RAW"
10938 .PD
10939 Described in perliol.
10940 .ie n .IP """PERLIO_NOT_STDIO""" 4
10941 .el .IP \f(CWPERLIO_NOT_STDIO\fR 4
10942 .IX Item "PERLIO_NOT_STDIO"
10943 Described in perlapio.
10944 .ie n .IP """PL_maxsysfd""" 4
10945 .el .IP \f(CWPL_maxsysfd\fR 4
10946 .IX Item "PL_maxsysfd"
10947 Described in perliol.
10948 .ie n .IP """repeatcpy""" 4
10949 .el .IP \f(CWrepeatcpy\fR 4
10950 .IX Xref "repeatcpy"
10951 .IX Item "repeatcpy"
10952 Make \f(CW\*(C`count\*(C'\fR copies of the \f(CW\*(C`len\*(C'\fR bytes beginning at \f(CW\*(C`from\*(C'\fR, placing them
10953 into memory beginning at \f(CW\*(C`to\*(C'\fR, which must be big enough to accommodate them
10954 all.
10955 .RS 4
10956 .Sp
10957 .Vb 1
10958 \& void repeatcpy(char *to, const char *from, SSize_t len, IV count)
10959 .Ve
10960 .RE
10961 .RS 4
10962 .RE
10963 .ie n .IP """USE_STDIO""" 4
10964 .el .IP \f(CWUSE_STDIO\fR 4
10965 .IX Item "USE_STDIO"
10966 Described in perlapio.
10967 .SH Integer
10968 .IX Header "Integer"
10969 .ie n .IP """CASTI32""" 4
10970 .el .IP \f(CWCASTI32\fR 4
10971 .IX Xref "CASTI32"
10972 .IX Item "CASTI32"
10973 This symbol is defined if the C compiler can cast negative
10974 or large floating point numbers to 32\-bit ints.
10975 .ie n .IP """HAS_INT64_T""" 4
10976 .el .IP \f(CWHAS_INT64_T\fR 4
10977 .IX Xref "HAS_INT64_T"
10978 .IX Item "HAS_INT64_T"
10979 This symbol will defined if the C compiler supports \f(CW\*(C`int64_t\*(C'\fR.
10980 Usually the \fIinttypes.h\fR needs to be included, but sometimes
10981 \&\fIsys/types.h\fR is enough.
10982 .ie n .IP """HAS_LONG_LONG""" 4
10983 .el .IP \f(CWHAS_LONG_LONG\fR 4
10984 .IX Xref "HAS_LONG_LONG"
10985 .IX Item "HAS_LONG_LONG"
10986 This symbol will be defined if the C compiler supports long long.
10987 .ie n .IP """HAS_QUAD""" 4
10988 .el .IP \f(CWHAS_QUAD\fR 4
10989 .IX Xref "HAS_QUAD"
10990 .IX Item "HAS_QUAD"
10991 This symbol, if defined, tells that there's a 64\-bit integer type,
10992 \&\f(CW\*(C`Quad_t\*(C'\fR, and its unsigned counterpart, \f(CW\*(C`Uquad_t\*(C'\fR. \f(CW\*(C`QUADKIND\*(C'\fR will be one
10993 of \f(CW\*(C`QUAD_IS_INT\*(C'\fR, \f(CW\*(C`QUAD_IS_LONG\*(C'\fR, \f(CW\*(C`QUAD_IS_LONG_LONG\*(C'\fR, \f(CW\*(C`QUAD_IS_INT64_T\*(C'\fR,
10994 or \f(CW\*(C`QUAD_IS_\|_\|_INT64\*(C'\fR.
10995 .ie n .IP """I32df""" 4
10996 .el .IP \f(CWI32df\fR 4
10997 .IX Xref "I32df"
10998 .IX Item "I32df"
10999 This symbol defines the format string used for printing a Perl I32
11000 as a signed decimal integer.
11001 .ie n .IP """INT16_C""" 4
11002 .el .IP \f(CWINT16_C\fR 4
11003 .IX Item "INT16_C"
11004 .PD 0
11005 .ie n .IP """INT32_C""" 4
11006 .el .IP \f(CWINT32_C\fR 4
11007 .IX Item "INT32_C"
11008 .ie n .IP """INT64_C""" 4
11009 .el .IP \f(CWINT64_C\fR 4
11010 .IX Xref "INT16_C INT32_C INT64_C"
11011 .IX Item "INT64_C"
11012 .PD
11013 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11014 corresponding integer type on the machine.
11015 .Sp
11016 If the machine does not have a 64\-bit type, \f(CW\*(C`INT64_C\*(C'\fR is undefined.
11017 Use \f(CW"INTMAX_C"\fR to get the largest type available on the platform.
11018 .RS 4
11019 .Sp
11020 .Vb 3
11021 \& I16 INT16_C(number)
11022 \& I32 INT32_C(number)
11023 \& I64 INT64_C(number)
11024 .Ve
11025 .RE
11026 .RS 4
11027 .RE
11028 .ie n .IP """INTMAX_C""" 4
11029 .el .IP \f(CWINTMAX_C\fR 4
11030 .IX Xref "INTMAX_C"
11031 .IX Item "INTMAX_C"
11032 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11033 widest integer type on the machine. For example, if the machine has \f(CW\*(C`long
11034 long\*(C'\fRs, \f(CWINTMAX_C(\-1)\fR would yield
11035 .Sp
11036 .Vb 1
11037 \& \-1LL
11038 .Ve
11039 .Sp
11040 See also, for example, \f(CW"INT32_C"\fR.
11041 .Sp
11042 Use "IV" to declare variables of the maximum usable size on this platform.
11043 .RS 4
11044 .Sp
11045 .Vb 1
11046 \& INTMAX_C(number)
11047 .Ve
11048 .RE
11049 .RS 4
11050 .RE
11051 .ie n .IP """INTSIZE""" 4
11052 .el .IP \f(CWINTSIZE\fR 4
11053 .IX Xref "INTSIZE"
11054 .IX Item "INTSIZE"
11055 This symbol contains the value of \f(CWsizeof(int)\fR so that the C
11056 preprocessor can make decisions based on it.
11057 .ie n .IP """I8SIZE""" 4
11058 .el .IP \f(CWI8SIZE\fR 4
11059 .IX Xref "I8SIZE"
11060 .IX Item "I8SIZE"
11061 This symbol contains the \f(CWsizeof(I8)\fR.
11062 .ie n .IP """I16SIZE""" 4
11063 .el .IP \f(CWI16SIZE\fR 4
11064 .IX Xref "I16SIZE"
11065 .IX Item "I16SIZE"
11066 This symbol contains the \f(CWsizeof(I16)\fR.
11067 .ie n .IP """I32SIZE""" 4
11068 .el .IP \f(CWI32SIZE\fR 4
11069 .IX Xref "I32SIZE"
11070 .IX Item "I32SIZE"
11071 This symbol contains the \f(CWsizeof(I32)\fR.
11072 .ie n .IP """I64SIZE""" 4
11073 .el .IP \f(CWI64SIZE\fR 4
11074 .IX Xref "I64SIZE"
11075 .IX Item "I64SIZE"
11076 This symbol contains the \f(CWsizeof(I64)\fR.
11077 .ie n .IP """I8TYPE""" 4
11078 .el .IP \f(CWI8TYPE\fR 4
11079 .IX Xref "I8TYPE"
11080 .IX Item "I8TYPE"
11081 This symbol defines the C type used for Perl's I8.
11082 .ie n .IP """I16TYPE""" 4
11083 .el .IP \f(CWI16TYPE\fR 4
11084 .IX Xref "I16TYPE"
11085 .IX Item "I16TYPE"
11086 This symbol defines the C type used for Perl's I16.
11087 .ie n .IP """I32TYPE""" 4
11088 .el .IP \f(CWI32TYPE\fR 4
11089 .IX Xref "I32TYPE"
11090 .IX Item "I32TYPE"
11091 This symbol defines the C type used for Perl's I32.
11092 .ie n .IP """I64TYPE""" 4
11093 .el .IP \f(CWI64TYPE\fR 4
11094 .IX Xref "I64TYPE"
11095 .IX Item "I64TYPE"
11096 This symbol defines the C type used for Perl's I64.
11097 .ie n .IP """IV""" 4
11098 .el .IP \f(CWIV\fR 4
11099 .IX Item "IV"
11100 .PD 0
11101 .ie n .IP """I8""" 4
11102 .el .IP \f(CWI8\fR 4
11103 .IX Item "I8"
11104 .ie n .IP """I16""" 4
11105 .el .IP \f(CWI16\fR 4
11106 .IX Item "I16"
11107 .ie n .IP """I32""" 4
11108 .el .IP \f(CWI32\fR 4
11109 .IX Item "I32"
11110 .ie n .IP """I64""" 4
11111 .el .IP \f(CWI64\fR 4
11112 .IX Item "I64"
11113 .PD
11114 Described in perlguts.
11115 .ie n .IP """IV_MAX""" 4
11116 .el .IP \f(CWIV_MAX\fR 4
11117 .IX Xref "IV_MAX"
11118 .IX Item "IV_MAX"
11119 The largest signed integer that fits in an IV on this platform.
11120 .RS 4
11121 .Sp
11122 .Vb 1
11123 \& IV IV_MAX
11124 .Ve
11125 .RE
11126 .RS 4
11127 .RE
11128 .ie n .IP """IV_MIN""" 4
11129 .el .IP \f(CWIV_MIN\fR 4
11130 .IX Xref "IV_MIN"
11131 .IX Item "IV_MIN"
11132 The negative signed integer furthest away from 0 that fits in an IV on this
11133 platform.
11134 .RS 4
11135 .Sp
11136 .Vb 1
11137 \& IV IV_MIN
11138 .Ve
11139 .RE
11140 .RS 4
11141 .RE
11142 .ie n .IP """IVSIZE""" 4
11143 .el .IP \f(CWIVSIZE\fR 4
11144 .IX Xref "IVSIZE"
11145 .IX Item "IVSIZE"
11146 This symbol contains the \f(CWsizeof(IV)\fR.
11147 .ie n .IP """IVTYPE""" 4
11148 .el .IP \f(CWIVTYPE\fR 4
11149 .IX Xref "IVTYPE"
11150 .IX Item "IVTYPE"
11151 This symbol defines the C type used for Perl's IV.
11152 .ie n .IP """line_t""" 4
11153 .el .IP \f(CWline_t\fR 4
11154 .IX Xref "line_t"
11155 .IX Item "line_t"
11156 The typedef to use to declare variables that are to hold line numbers.
11157 .ie n .IP """LONGLONGSIZE""" 4
11158 .el .IP \f(CWLONGLONGSIZE\fR 4
11159 .IX Xref "LONGLONGSIZE"
11160 .IX Item "LONGLONGSIZE"
11161 This symbol contains the size of a long long, so that the
11162 C preprocessor can make decisions based on it. It is only
11163 defined if the system supports long long.
11164 .ie n .IP """LONGSIZE""" 4
11165 .el .IP \f(CWLONGSIZE\fR 4
11166 .IX Xref "LONGSIZE"
11167 .IX Item "LONGSIZE"
11168 This symbol contains the value of \f(CWsizeof(long)\fR so that the C
11169 preprocessor can make decisions based on it.
11170 .ie n .IP """memzero""" 4
11171 .el .IP \f(CWmemzero\fR 4
11172 .IX Xref "memzero"
11173 .IX Item "memzero"
11174 Set the \f(CW\*(C`l\*(C'\fR bytes starting at \f(CW*d\fR to all zeroes.
11175 .RS 4
11176 .Sp
11177 .Vb 1
11178 \& void memzero(void * d, Size_t l)
11179 .Ve
11180 .RE
11181 .RS 4
11182 .RE
11183 .ie n .IP """PERL_INT_FAST8_T""" 4
11184 .el .IP \f(CWPERL_INT_FAST8_T\fR 4
11185 .IX Item "PERL_INT_FAST8_T"
11186 .PD 0
11187 .ie n .IP """PERL_INT_FAST16_T""" 4
11188 .el .IP \f(CWPERL_INT_FAST16_T\fR 4
11189 .IX Item "PERL_INT_FAST16_T"
11190 .ie n .IP """PERL_UINT_FAST8_T""" 4
11191 .el .IP \f(CWPERL_UINT_FAST8_T\fR 4
11192 .IX Item "PERL_UINT_FAST8_T"
11193 .ie n .IP """PERL_UINT_FAST16_T""" 4
11194 .el .IP \f(CWPERL_UINT_FAST16_T\fR 4
11195 .IX Xref "PERL_INT_FAST8_T PERL_INT_FAST16_T PERL_UINT_FAST8_T PERL_UINT_FAST16_T"
11196 .IX Item "PERL_UINT_FAST16_T"
11197 .PD
11198 These are equivalent to the correspondingly-named C99 typedefs on platforms
11199 that have those; they evaluate to \f(CW\*(C`int\*(C'\fR and \f(CW\*(C`unsigned int\*(C'\fR on platforms that
11200 don't, so that you can portably take advantage of this C99 feature.
11201 .ie n .IP """PERL_INT_MAX""" 4
11202 .el .IP \f(CWPERL_INT_MAX\fR 4
11203 .IX Item "PERL_INT_MAX"
11204 .PD 0
11205 .ie n .IP """PERL_INT_MIN""" 4
11206 .el .IP \f(CWPERL_INT_MIN\fR 4
11207 .IX Item "PERL_INT_MIN"
11208 .ie n .IP """PERL_LONG_MAX""" 4
11209 .el .IP \f(CWPERL_LONG_MAX\fR 4
11210 .IX Item "PERL_LONG_MAX"
11211 .ie n .IP """PERL_LONG_MIN""" 4
11212 .el .IP \f(CWPERL_LONG_MIN\fR 4
11213 .IX Item "PERL_LONG_MIN"
11214 .ie n .IP """PERL_QUAD_MAX""" 4
11215 .el .IP \f(CWPERL_QUAD_MAX\fR 4
11216 .IX Item "PERL_QUAD_MAX"
11217 .ie n .IP """PERL_QUAD_MIN""" 4
11218 .el .IP \f(CWPERL_QUAD_MIN\fR 4
11219 .IX Item "PERL_QUAD_MIN"
11220 .ie n .IP """PERL_SHORT_MAX""" 4
11221 .el .IP \f(CWPERL_SHORT_MAX\fR 4
11222 .IX Item "PERL_SHORT_MAX"
11223 .ie n .IP """PERL_SHORT_MIN""" 4
11224 .el .IP \f(CWPERL_SHORT_MIN\fR 4
11225 .IX Item "PERL_SHORT_MIN"
11226 .ie n .IP """PERL_UCHAR_MAX""" 4
11227 .el .IP \f(CWPERL_UCHAR_MAX\fR 4
11228 .IX Item "PERL_UCHAR_MAX"
11229 .ie n .IP """PERL_UCHAR_MIN""" 4
11230 .el .IP \f(CWPERL_UCHAR_MIN\fR 4
11231 .IX Item "PERL_UCHAR_MIN"
11232 .ie n .IP """PERL_UINT_MAX""" 4
11233 .el .IP \f(CWPERL_UINT_MAX\fR 4
11234 .IX Item "PERL_UINT_MAX"
11235 .ie n .IP """PERL_UINT_MIN""" 4
11236 .el .IP \f(CWPERL_UINT_MIN\fR 4
11237 .IX Item "PERL_UINT_MIN"
11238 .ie n .IP """PERL_ULONG_MAX""" 4
11239 .el .IP \f(CWPERL_ULONG_MAX\fR 4
11240 .IX Item "PERL_ULONG_MAX"
11241 .ie n .IP """PERL_ULONG_MIN""" 4
11242 .el .IP \f(CWPERL_ULONG_MIN\fR 4
11243 .IX Item "PERL_ULONG_MIN"
11244 .ie n .IP """PERL_UQUAD_MAX""" 4
11245 .el .IP \f(CWPERL_UQUAD_MAX\fR 4
11246 .IX Item "PERL_UQUAD_MAX"
11247 .ie n .IP """PERL_UQUAD_MIN""" 4
11248 .el .IP \f(CWPERL_UQUAD_MIN\fR 4
11249 .IX Item "PERL_UQUAD_MIN"
11250 .ie n .IP """PERL_USHORT_MAX""" 4
11251 .el .IP \f(CWPERL_USHORT_MAX\fR 4
11252 .IX Item "PERL_USHORT_MAX"
11253 .ie n .IP """PERL_USHORT_MIN""" 4
11254 .el .IP \f(CWPERL_USHORT_MIN\fR 4
11255 .IX Xref "PERL_INT_MAX PERL_INT_MIN PERL_LONG_MAX PERL_LONG_MIN PERL_QUAD_MAX PERL_QUAD_MIN PERL_SHORT_MAX PERL_SHORT_MIN PERL_UCHAR_MAX PERL_UCHAR_MIN PERL_UINT_MAX PERL_UINT_MIN PERL_ULONG_MAX PERL_ULONG_MIN PERL_UQUAD_MAX PERL_UQUAD_MIN PERL_USHORT_MAX PERL_USHORT_MIN"
11256 .IX Item "PERL_USHORT_MIN"
11257 .PD
11258 These give the largest and smallest number representable in the current
11259 platform in variables of the corresponding types.
11260 .Sp
11261 For signed types, the smallest representable number is the most negative
11262 number, the one furthest away from zero.
11263 .Sp
11264 For C99 and later compilers, these correspond to things like \f(CW\*(C`INT_MAX\*(C'\fR, which
11265 are available to the C code. But these constants, furnished by Perl,
11266 allow code compiled on earlier compilers to portably have access to the same
11267 constants.
11268 .RS 4
11269 .Sp
11270 .Vb 10
11271 \& int PERL_INT_MAX
11272 \& int PERL_INT_MIN
11273 \& long PERL_LONG_MAX
11274 \& long PERL_LONG_MIN
11275 \& IV PERL_QUAD_MAX
11276 \& IV PERL_QUAD_MIN
11277 \& short PERL_SHORT_MAX
11278 \& short PERL_SHORT_MIN
11279 \& U8 PERL_UCHAR_MAX
11280 \& U8 PERL_UCHAR_MIN
11281 \& unsigned int PERL_UINT_MAX
11282 \& unsigned int PERL_UINT_MIN
11283 \& unsigned long PERL_ULONG_MAX
11284 \& unsigned long PERL_ULONG_MIN
11285 \& UV PERL_UQUAD_MAX
11286 \& UV PERL_UQUAD_MIN
11287 \& unsigned short PERL_USHORT_MAX
11288 \& unsigned short PERL_USHORT_MIN
11289 .Ve
11290 .RE
11291 .RS 4
11292 .RE
11293 .ie n .IP """SHORTSIZE""" 4
11294 .el .IP \f(CWSHORTSIZE\fR 4
11295 .IX Xref "SHORTSIZE"
11296 .IX Item "SHORTSIZE"
11297 This symbol contains the value of \f(CWsizeof(short)\fR so that the C
11298 preprocessor can make decisions based on it.
11299 .ie n .IP """UINT16_C""" 4
11300 .el .IP \f(CWUINT16_C\fR 4
11301 .IX Item "UINT16_C"
11302 .PD 0
11303 .ie n .IP """UINT32_C""" 4
11304 .el .IP \f(CWUINT32_C\fR 4
11305 .IX Item "UINT32_C"
11306 .ie n .IP """UINT64_C""" 4
11307 .el .IP \f(CWUINT64_C\fR 4
11308 .IX Xref "UINT16_C UINT32_C UINT64_C"
11309 .IX Item "UINT64_C"
11310 .PD
11311 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11312 corresponding unsigned integer type on the machine.
11313 .Sp
11314 If the machine does not have a 64\-bit type, \f(CW\*(C`UINT64_C\*(C'\fR is undefined.
11315 Use \f(CW"UINTMAX_C"\fR to get the largest type available on the platform.
11316 .RS 4
11317 .Sp
11318 .Vb 3
11319 \& U16 UINT16_C(number)
11320 \& U32 UINT32_C(number)
11321 \& U64 UINT64_C(number)
11322 .Ve
11323 .RE
11324 .RS 4
11325 .RE
11326 .ie n .IP """UINTMAX_C""" 4
11327 .el .IP \f(CWUINTMAX_C\fR 4
11328 .IX Xref "UINTMAX_C"
11329 .IX Item "UINTMAX_C"
11330 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11331 widest unsigned integer type on the machine. For example, if the machine has
11332 \&\f(CW\*(C`long\*(C'\fRs, \f(CWUINTMAX_C(1)\fR would yield
11333 .Sp
11334 .Vb 1
11335 \& 1UL
11336 .Ve
11337 .Sp
11338 See also, for example, \f(CW"UINT32_C"\fR.
11339 .Sp
11340 Use "UV" to declare variables of the maximum usable size on this platform.
11341 .RS 4
11342 .Sp
11343 .Vb 1
11344 \& UINTMAX_C(number)
11345 .Ve
11346 .RE
11347 .RS 4
11348 .RE
11349 .ie n .IP """U32of""" 4
11350 .el .IP \f(CWU32of\fR 4
11351 .IX Xref "U32of"
11352 .IX Item "U32of"
11353 This symbol defines the format string used for printing a Perl U32
11354 as an unsigned octal integer.
11355 .ie n .IP """U8SIZE""" 4
11356 .el .IP \f(CWU8SIZE\fR 4
11357 .IX Xref "U8SIZE"
11358 .IX Item "U8SIZE"
11359 This symbol contains the \f(CWsizeof(U8)\fR.
11360 .ie n .IP """U16SIZE""" 4
11361 .el .IP \f(CWU16SIZE\fR 4
11362 .IX Xref "U16SIZE"
11363 .IX Item "U16SIZE"
11364 This symbol contains the \f(CWsizeof(U16)\fR.
11365 .ie n .IP """U32SIZE""" 4
11366 .el .IP \f(CWU32SIZE\fR 4
11367 .IX Xref "U32SIZE"
11368 .IX Item "U32SIZE"
11369 This symbol contains the \f(CWsizeof(U32)\fR.
11370 .ie n .IP """U64SIZE""" 4
11371 .el .IP \f(CWU64SIZE\fR 4
11372 .IX Xref "U64SIZE"
11373 .IX Item "U64SIZE"
11374 This symbol contains the \f(CWsizeof(U64)\fR.
11375 .ie n .IP """U8TYPE""" 4
11376 .el .IP \f(CWU8TYPE\fR 4
11377 .IX Xref "U8TYPE"
11378 .IX Item "U8TYPE"
11379 This symbol defines the C type used for Perl's U8.
11380 .ie n .IP """U16TYPE""" 4
11381 .el .IP \f(CWU16TYPE\fR 4
11382 .IX Xref "U16TYPE"
11383 .IX Item "U16TYPE"
11384 This symbol defines the C type used for Perl's U16.
11385 .ie n .IP """U32TYPE""" 4
11386 .el .IP \f(CWU32TYPE\fR 4
11387 .IX Xref "U32TYPE"
11388 .IX Item "U32TYPE"
11389 This symbol defines the C type used for Perl's U32.
11390 .ie n .IP """U64TYPE""" 4
11391 .el .IP \f(CWU64TYPE\fR 4
11392 .IX Xref "U64TYPE"
11393 .IX Item "U64TYPE"
11394 This symbol defines the C type used for Perl's U64.
11395 .ie n .IP """U32uf""" 4
11396 .el .IP \f(CWU32uf\fR 4
11397 .IX Xref "U32uf"
11398 .IX Item "U32uf"
11399 This symbol defines the format string used for printing a Perl U32
11400 as an unsigned decimal integer.
11401 .ie n .IP """UV""" 4
11402 .el .IP \f(CWUV\fR 4
11403 .IX Item "UV"
11404 .PD 0
11405 .ie n .IP """U8""" 4
11406 .el .IP \f(CWU8\fR 4
11407 .IX Item "U8"
11408 .ie n .IP """U16""" 4
11409 .el .IP \f(CWU16\fR 4
11410 .IX Item "U16"
11411 .ie n .IP """U32""" 4
11412 .el .IP \f(CWU32\fR 4
11413 .IX Item "U32"
11414 .ie n .IP """U64""" 4
11415 .el .IP \f(CWU64\fR 4
11416 .IX Item "U64"
11417 .PD
11418 Described in perlguts.
11419 .ie n .IP """UV_MAX""" 4
11420 .el .IP \f(CWUV_MAX\fR 4
11421 .IX Xref "UV_MAX"
11422 .IX Item "UV_MAX"
11423 The largest unsigned integer that fits in a UV on this platform.
11424 .RS 4
11425 .Sp
11426 .Vb 1
11427 \& UV UV_MAX
11428 .Ve
11429 .RE
11430 .RS 4
11431 .RE
11432 .ie n .IP """UV_MIN""" 4
11433 .el .IP \f(CWUV_MIN\fR 4
11434 .IX Xref "UV_MIN"
11435 .IX Item "UV_MIN"
11436 The smallest unsigned integer that fits in a UV on this platform. It should
11437 equal zero.
11438 .RS 4
11439 .Sp
11440 .Vb 1
11441 \& UV UV_MIN
11442 .Ve
11443 .RE
11444 .RS 4
11445 .RE
11446 .ie n .IP """UVSIZE""" 4
11447 .el .IP \f(CWUVSIZE\fR 4
11448 .IX Xref "UVSIZE"
11449 .IX Item "UVSIZE"
11450 This symbol contains the \f(CWsizeof(UV)\fR.
11451 .ie n .IP """UVTYPE""" 4
11452 .el .IP \f(CWUVTYPE\fR 4
11453 .IX Xref "UVTYPE"
11454 .IX Item "UVTYPE"
11455 This symbol defines the C type used for Perl's UV.
11456 .ie n .IP """U32Xf""" 4
11457 .el .IP \f(CWU32Xf\fR 4
11458 .IX Xref "U32Xf"
11459 .IX Item "U32Xf"
11460 This symbol defines the format string used for printing a Perl U32
11461 as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR.
11462 .ie n .IP """U32xf""" 4
11463 .el .IP \f(CWU32xf\fR 4
11464 .IX Xref "U32xf"
11465 .IX Item "U32xf"
11466 This symbol defines the format string used for printing a Perl U32
11467 as an unsigned hexadecimal integer in lowercase abcdef.
11468 .ie n .IP """WIDEST_UTYPE""" 4
11469 .el .IP \f(CWWIDEST_UTYPE\fR 4
11470 .IX Xref "WIDEST_UTYPE"
11471 .IX Item "WIDEST_UTYPE"
11472 Yields the widest unsigned integer type on the platform, currently either
11473 \&\f(CW\*(C`U32\*(C'\fR or \f(CW\*(C`U64\*(C'\fR. This can be used in declarations such as
11474 .Sp
11475 .Vb 1
11476 \& WIDEST_UTYPE my_uv;
11477 .Ve
11478 .Sp
11479 or casts
11480 .Sp
11481 .Vb 1
11482 \& my_uv = (WIDEST_UTYPE) val;
11483 .Ve
11484 .SH "I/O Formats"
11485 .IX Header "I/O Formats"
11486 These are used for formatting the corresponding type For example,
11487 instead of saying
11488 .PP
11489 .Vb 1
11490 \& Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\en", iv);
11491 .Ve
11492 .PP
11493 use
11494 .PP
11495 .Vb 1
11496 \& Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\en", iv);
11497 .Ve
11498 .PP
11499 This keeps you from having to know if, say an IV, needs to be
11500 printed as \f(CW%d\fR, \f(CW%ld\fR, or something else.
11501 .ie n .IP """HvNAMEf""" 4
11502 .el .IP \f(CWHvNAMEf\fR 4
11503 .IX Item "HvNAMEf"
11504 Described in perlguts.
11505 .ie n .IP """HvNAMEf_QUOTEDPREFIX""" 4
11506 .el .IP \f(CWHvNAMEf_QUOTEDPREFIX\fR 4
11507 .IX Item "HvNAMEf_QUOTEDPREFIX"
11508 Described in perlguts.
11509 .ie n .IP """IVdf""" 4
11510 .el .IP \f(CWIVdf\fR 4
11511 .IX Xref "IVdf"
11512 .IX Item "IVdf"
11513 This symbol defines the format string used for printing a Perl IV
11514 as a signed decimal integer.
11515 .ie n .IP """NVef""" 4
11516 .el .IP \f(CWNVef\fR 4
11517 .IX Xref "NVef"
11518 .IX Item "NVef"
11519 This symbol defines the format string used for printing a Perl NV
11520 using \f(CW%e\fR\-ish floating point format.
11521 .ie n .IP """NVff""" 4
11522 .el .IP \f(CWNVff\fR 4
11523 .IX Xref "NVff"
11524 .IX Item "NVff"
11525 This symbol defines the format string used for printing a Perl NV
11526 using \f(CW%f\fR\-ish floating point format.
11527 .ie n .IP """NVgf""" 4
11528 .el .IP \f(CWNVgf\fR 4
11529 .IX Xref "NVgf"
11530 .IX Item "NVgf"
11531 This symbol defines the format string used for printing a Perl NV
11532 using \f(CW%g\fR\-ish floating point format.
11533 .ie n .IP """PERL_PRIeldbl""" 4
11534 .el .IP \f(CWPERL_PRIeldbl\fR 4
11535 .IX Xref "PERL_PRIeldbl"
11536 .IX Item "PERL_PRIeldbl"
11537 This symbol, if defined, contains the string used by stdio to
11538 format long doubles (format 'e') for output.
11539 .ie n .IP """PERL_PRIfldbl""" 4
11540 .el .IP \f(CWPERL_PRIfldbl\fR 4
11541 .IX Xref "PERL_PRIfldbl"
11542 .IX Item "PERL_PRIfldbl"
11543 This symbol, if defined, contains the string used by stdio to
11544 format long doubles (format 'f') for output.
11545 .ie n .IP """PERL_PRIgldbl""" 4
11546 .el .IP \f(CWPERL_PRIgldbl\fR 4
11547 .IX Xref "PERL_PRIgldbl"
11548 .IX Item "PERL_PRIgldbl"
11549 This symbol, if defined, contains the string used by stdio to
11550 format long doubles (format 'g') for output.
11551 .ie n .IP """PERL_SCNfldbl""" 4
11552 .el .IP \f(CWPERL_SCNfldbl\fR 4
11553 .IX Xref "PERL_SCNfldbl"
11554 .IX Item "PERL_SCNfldbl"
11555 This symbol, if defined, contains the string used by stdio to
11556 format long doubles (format 'f') for input.
11557 .ie n .IP """PRINTF_FORMAT_NULL_OK""" 4
11558 .el .IP \f(CWPRINTF_FORMAT_NULL_OK\fR 4
11559 .IX Xref "PRINTF_FORMAT_NULL_OK"
11560 .IX Item "PRINTF_FORMAT_NULL_OK"
11561 Allows \f(CW\*(C`_\|_printf_\|_\*(C'\fR format to be null when checking printf-style
11562 .ie n .IP """SVf""" 4
11563 .el .IP \f(CWSVf\fR 4
11564 .IX Item "SVf"
11565 Described in perlguts.
11566 .ie n .IP """SVfARG""" 4
11567 .el .IP \f(CWSVfARG\fR 4
11568 .IX Item "SVfARG"
11569 Described in perlguts.
11570 .RS 4
11571 .Sp
11572 .Vb 1
11573 \& SVfARG(SV *sv)
11574 .Ve
11575 .RE
11576 .RS 4
11577 .RE
11578 .ie n .IP """SVf_QUOTEDPREFIX""" 4
11579 .el .IP \f(CWSVf_QUOTEDPREFIX\fR 4
11580 .IX Item "SVf_QUOTEDPREFIX"
11581 Described in perlguts.
11582 .ie n .IP """UTF8f""" 4
11583 .el .IP \f(CWUTF8f\fR 4
11584 .IX Item "UTF8f"
11585 Described in perlguts.
11586 .ie n .IP """UTF8fARG""" 4
11587 .el .IP \f(CWUTF8fARG\fR 4
11588 .IX Item "UTF8fARG"
11589 Described in perlguts.
11590 .RS 4
11591 .Sp
11592 .Vb 1
11593 \& UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
11594 .Ve
11595 .RE
11596 .RS 4
11597 .RE
11598 .ie n .IP """UTF8f_QUOTEDPREFIX""" 4
11599 .el .IP \f(CWUTF8f_QUOTEDPREFIX\fR 4
11600 .IX Item "UTF8f_QUOTEDPREFIX"
11601 Described in perlguts.
11602 .ie n .IP """UVf""" 4
11603 .el .IP \f(CWUVf\fR 4
11604 .IX Xref "UVf"
11605 .IX Item "UVf"
11606 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`UVf\*(C'\fR
11607 from a future release of Perl. Do not use it for
11608 new code; remove it from existing code.
11609 .Sp
11610 Obsolete form of \f(CW\*(C`UVuf\*(C'\fR, which you should convert to instead use
11611 .RS 4
11612 .Sp
11613 .Vb 1
11614 \& const char * UVf
11615 .Ve
11616 .RE
11617 .RS 4
11618 .RE
11619 .ie n .IP """UVof""" 4
11620 .el .IP \f(CWUVof\fR 4
11621 .IX Xref "UVof"
11622 .IX Item "UVof"
11623 This symbol defines the format string used for printing a Perl UV
11624 as an unsigned octal integer.
11625 .ie n .IP """UVuf""" 4
11626 .el .IP \f(CWUVuf\fR 4
11627 .IX Xref "UVuf"
11628 .IX Item "UVuf"
11629 This symbol defines the format string used for printing a Perl UV
11630 as an unsigned decimal integer.
11631 .ie n .IP """UVXf""" 4
11632 .el .IP \f(CWUVXf\fR 4
11633 .IX Xref "UVXf"
11634 .IX Item "UVXf"
11635 This symbol defines the format string used for printing a Perl UV
11636 as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR.
11637 .ie n .IP """UVxf""" 4
11638 .el .IP \f(CWUVxf\fR 4
11639 .IX Xref "UVxf"
11640 .IX Item "UVxf"
11641 This symbol defines the format string used for printing a Perl UV
11642 as an unsigned hexadecimal integer in lowercase abcdef.
11643 .SH "Lexer interface"
11644 .IX Xref "LEX_KEEP_PREVIOUS LEX_STUFF_UTF8 PARSE_OPTIONAL"
11645 .IX Header "Lexer interface"
11646 This is the lower layer of the Perl parser, managing characters and tokens.
11647 .ie n .IP """BHK""" 4
11648 .el .IP \f(CWBHK\fR 4
11649 .IX Item "BHK"
11650 Described in perlguts.
11651 .ie n .IP """lex_bufutf8""" 4
11652 .el .IP \f(CWlex_bufutf8\fR 4
11653 .IX Xref "lex_bufutf8"
11654 .IX Item "lex_bufutf8"
11655 NOTE: \f(CW\*(C`lex_bufutf8\*(C'\fR is \fBexperimental\fR and may change or be
11656 removed without notice.
11657 .Sp
11658 Indicates whether the octets in the lexer buffer
11659 ("PL_parser\->linestr") should be interpreted as the UTF\-8 encoding
11660 of Unicode characters. If not, they should be interpreted as Latin\-1
11661 characters. This is analogous to the \f(CW\*(C`SvUTF8\*(C'\fR flag for scalars.
11662 .Sp
11663 In UTF\-8 mode, it is not guaranteed that the lexer buffer actually
11664 contains valid UTF\-8. Lexing code must be robust in the face of invalid
11665 encoding.
11666 .Sp
11667 The actual \f(CW\*(C`SvUTF8\*(C'\fR flag of the "PL_parser\->linestr" scalar
11668 is significant, but not the whole story regarding the input character
11669 encoding. Normally, when a file is being read, the scalar contains octets
11670 and its \f(CW\*(C`SvUTF8\*(C'\fR flag is off, but the octets should be interpreted as
11671 UTF\-8 if the \f(CW\*(C`use utf8\*(C'\fR pragma is in effect. During a string eval,
11672 however, the scalar may have the \f(CW\*(C`SvUTF8\*(C'\fR flag on, and in this case its
11673 octets should be interpreted as UTF\-8 unless the \f(CW\*(C`use bytes\*(C'\fR pragma
11674 is in effect. This logic may change in the future; use this function
11675 instead of implementing the logic yourself.
11676 .RS 4
11677 .Sp
11678 .Vb 1
11679 \& bool lex_bufutf8()
11680 .Ve
11681 .RE
11682 .RS 4
11683 .RE
11684 .ie n .IP """lex_discard_to""" 4
11685 .el .IP \f(CWlex_discard_to\fR 4
11686 .IX Xref "lex_discard_to"
11687 .IX Item "lex_discard_to"
11688 NOTE: \f(CW\*(C`lex_discard_to\*(C'\fR is \fBexperimental\fR and may change or be
11689 removed without notice.
11690 .Sp
11691 Discards the first part of the "PL_parser\->linestr" buffer,
11692 up to \f(CW\*(C`ptr\*(C'\fR. The remaining content of the buffer will be moved, and
11693 all pointers into the buffer updated appropriately. \f(CW\*(C`ptr\*(C'\fR must not
11694 be later in the buffer than the position of "PL_parser\->bufptr":
11695 it is not permitted to discard text that has yet to be lexed.
11696 .Sp
11697 Normally it is not necessarily to do this directly, because it suffices to
11698 use the implicit discarding behaviour of "lex_next_chunk" and things
11699 based on it. However, if a token stretches across multiple lines,
11700 and the lexing code has kept multiple lines of text in the buffer for
11701 that purpose, then after completion of the token it would be wise to
11702 explicitly discard the now-unneeded earlier lines, to avoid future
11703 multi-line tokens growing the buffer without bound.
11704 .RS 4
11705 .Sp
11706 .Vb 1
11707 \& void lex_discard_to(char *ptr)
11708 .Ve
11709 .RE
11710 .RS 4
11711 .RE
11712 .ie n .IP """lex_grow_linestr""" 4
11713 .el .IP \f(CWlex_grow_linestr\fR 4
11714 .IX Xref "lex_grow_linestr"
11715 .IX Item "lex_grow_linestr"
11716 NOTE: \f(CW\*(C`lex_grow_linestr\*(C'\fR is \fBexperimental\fR and may change or be
11717 removed without notice.
11718 .Sp
11719 Reallocates the lexer buffer ("PL_parser\->linestr") to accommodate
11720 at least \f(CW\*(C`len\*(C'\fR octets (including terminating \f(CW\*(C`NUL\*(C'\fR). Returns a
11721 pointer to the reallocated buffer. This is necessary before making
11722 any direct modification of the buffer that would increase its length.
11723 "lex_stuff_pvn" provides a more convenient way to insert text into
11724 the buffer.
11725 .Sp
11726 Do not use \f(CW\*(C`SvGROW\*(C'\fR or \f(CW\*(C`sv_grow\*(C'\fR directly on \f(CW\*(C`PL_parser\->linestr\*(C'\fR;
11727 this function updates all of the lexer's variables that point directly
11728 into the buffer.
11729 .RS 4
11730 .Sp
11731 .Vb 1
11732 \& char * lex_grow_linestr(STRLEN len)
11733 .Ve
11734 .RE
11735 .RS 4
11736 .RE
11737 .ie n .IP """lex_next_chunk""" 4
11738 .el .IP \f(CWlex_next_chunk\fR 4
11739 .IX Xref "lex_next_chunk"
11740 .IX Item "lex_next_chunk"
11741 NOTE: \f(CW\*(C`lex_next_chunk\*(C'\fR is \fBexperimental\fR and may change or be
11742 removed without notice.
11743 .Sp
11744 Reads in the next chunk of text to be lexed, appending it to
11745 "PL_parser\->linestr". This should be called when lexing code has
11746 looked to the end of the current chunk and wants to know more. It is
11747 usual, but not necessary, for lexing to have consumed the entirety of
11748 the current chunk at this time.
11749 .Sp
11750 If "PL_parser\->bufptr" is pointing to the very end of the current
11751 chunk (i.e., the current chunk has been entirely consumed), normally the
11752 current chunk will be discarded at the same time that the new chunk is
11753 read in. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, the current chunk
11754 will not be discarded. If the current chunk has not been entirely
11755 consumed, then it will not be discarded regardless of the flag.
11756 .Sp
11757 Returns true if some new text was added to the buffer, or false if the
11758 buffer has reached the end of the input text.
11759 .RS 4
11760 .Sp
11761 .Vb 1
11762 \& bool lex_next_chunk(U32 flags)
11763 .Ve
11764 .RE
11765 .RS 4
11766 .RE
11767 .ie n .IP """lex_peek_unichar""" 4
11768 .el .IP \f(CWlex_peek_unichar\fR 4
11769 .IX Xref "lex_peek_unichar"
11770 .IX Item "lex_peek_unichar"
11771 NOTE: \f(CW\*(C`lex_peek_unichar\*(C'\fR is \fBexperimental\fR and may change or be
11772 removed without notice.
11773 .Sp
11774 Looks ahead one (Unicode) character in the text currently being lexed.
11775 Returns the codepoint (unsigned integer value) of the next character,
11776 or \-1 if lexing has reached the end of the input text. To consume the
11777 peeked character, use "lex_read_unichar".
11778 .Sp
11779 If the next character is in (or extends into) the next chunk of input
11780 text, the next chunk will be read in. Normally the current chunk will be
11781 discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR
11782 bit set, then the current chunk will not be discarded.
11783 .Sp
11784 If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error
11785 is encountered, an exception is generated.
11786 .RS 4
11787 .Sp
11788 .Vb 1
11789 \& I32 lex_peek_unichar(U32 flags)
11790 .Ve
11791 .RE
11792 .RS 4
11793 .RE
11794 .ie n .IP """lex_read_space""" 4
11795 .el .IP \f(CWlex_read_space\fR 4
11796 .IX Xref "lex_read_space"
11797 .IX Item "lex_read_space"
11798 NOTE: \f(CW\*(C`lex_read_space\*(C'\fR is \fBexperimental\fR and may change or be
11799 removed without notice.
11800 .Sp
11801 Reads optional spaces, in Perl style, in the text currently being
11802 lexed. The spaces may include ordinary whitespace characters and
11803 Perl-style comments. \f(CW\*(C`#line\*(C'\fR directives are processed if encountered.
11804 "PL_parser\->bufptr" is moved past the spaces, so that it points
11805 at a non-space character (or the end of the input text).
11806 .Sp
11807 If spaces extend into the next chunk of input text, the next chunk will
11808 be read in. Normally the current chunk will be discarded at the same
11809 time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, then the current
11810 chunk will not be discarded.
11811 .RS 4
11812 .Sp
11813 .Vb 1
11814 \& void lex_read_space(U32 flags)
11815 .Ve
11816 .RE
11817 .RS 4
11818 .RE
11819 .ie n .IP """lex_read_to""" 4
11820 .el .IP \f(CWlex_read_to\fR 4
11821 .IX Xref "lex_read_to"
11822 .IX Item "lex_read_to"
11823 NOTE: \f(CW\*(C`lex_read_to\*(C'\fR is \fBexperimental\fR and may change or be
11824 removed without notice.
11825 .Sp
11826 Consume text in the lexer buffer, from "PL_parser\->bufptr" up
11827 to \f(CW\*(C`ptr\*(C'\fR. This advances "PL_parser\->bufptr" to match \f(CW\*(C`ptr\*(C'\fR,
11828 performing the correct bookkeeping whenever a newline character is passed.
11829 This is the normal way to consume lexed text.
11830 .Sp
11831 Interpretation of the buffer's octets can be abstracted out by
11832 using the slightly higher-level functions "lex_peek_unichar" and
11833 "lex_read_unichar".
11834 .RS 4
11835 .Sp
11836 .Vb 1
11837 \& void lex_read_to(char *ptr)
11838 .Ve
11839 .RE
11840 .RS 4
11841 .RE
11842 .ie n .IP """lex_read_unichar""" 4
11843 .el .IP \f(CWlex_read_unichar\fR 4
11844 .IX Xref "lex_read_unichar"
11845 .IX Item "lex_read_unichar"
11846 NOTE: \f(CW\*(C`lex_read_unichar\*(C'\fR is \fBexperimental\fR and may change or be
11847 removed without notice.
11848 .Sp
11849 Reads the next (Unicode) character in the text currently being lexed.
11850 Returns the codepoint (unsigned integer value) of the character read,
11851 and moves "PL_parser\->bufptr" past the character, or returns \-1
11852 if lexing has reached the end of the input text. To non-destructively
11853 examine the next character, use "lex_peek_unichar" instead.
11854 .Sp
11855 If the next character is in (or extends into) the next chunk of input
11856 text, the next chunk will be read in. Normally the current chunk will be
11857 discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR
11858 bit set, then the current chunk will not be discarded.
11859 .Sp
11860 If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error
11861 is encountered, an exception is generated.
11862 .RS 4
11863 .Sp
11864 .Vb 1
11865 \& I32 lex_read_unichar(U32 flags)
11866 .Ve
11867 .RE
11868 .RS 4
11869 .RE
11870 .ie n .IP """lex_start""" 4
11871 .el .IP \f(CWlex_start\fR 4
11872 .IX Xref "lex_start"
11873 .IX Item "lex_start"
11874 NOTE: \f(CW\*(C`lex_start\*(C'\fR is \fBexperimental\fR and may change or be
11875 removed without notice.
11876 .Sp
11877 Creates and initialises a new lexer/parser state object, supplying
11878 a context in which to lex and parse from a new source of Perl code.
11879 A pointer to the new state object is placed in "PL_parser". An entry
11880 is made on the save stack so that upon unwinding, the new state object
11881 will be destroyed and the former value of "PL_parser" will be restored.
11882 Nothing else need be done to clean up the parsing context.
11883 .Sp
11884 The code to be parsed comes from \f(CW\*(C`line\*(C'\fR and \f(CW\*(C`rsfp\*(C'\fR. \f(CW\*(C`line\*(C'\fR, if
11885 non-null, provides a string (in SV form) containing code to be parsed.
11886 A copy of the string is made, so subsequent modification of \f(CW\*(C`line\*(C'\fR
11887 does not affect parsing. \f(CW\*(C`rsfp\*(C'\fR, if non-null, provides an input stream
11888 from which code will be read to be parsed. If both are non-null, the
11889 code in \f(CW\*(C`line\*(C'\fR comes first and must consist of complete lines of input,
11890 and \f(CW\*(C`rsfp\*(C'\fR supplies the remainder of the source.
11891 .Sp
11892 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use. Currently it is only
11893 used by perl internally, so extensions should always pass zero.
11894 .RS 4
11895 .Sp
11896 .Vb 1
11897 \& void lex_start(SV *line, PerlIO *rsfp, U32 flags)
11898 .Ve
11899 .RE
11900 .RS 4
11901 .RE
11902 .ie n .IP """lex_stuff_pv""" 4
11903 .el .IP \f(CWlex_stuff_pv\fR 4
11904 .IX Xref "lex_stuff_pv"
11905 .IX Item "lex_stuff_pv"
11906 NOTE: \f(CW\*(C`lex_stuff_pv\*(C'\fR is \fBexperimental\fR and may change or be
11907 removed without notice.
11908 .Sp
11909 Insert characters into the lexer buffer ("PL_parser\->linestr"),
11910 immediately after the current lexing point ("PL_parser\->bufptr"),
11911 reallocating the buffer if necessary. This means that lexing code that
11912 runs later will see the characters as if they had appeared in the input.
11913 It is not recommended to do this as part of normal parsing, and most
11914 uses of this facility run the risk of the inserted characters being
11915 interpreted in an unintended manner.
11916 .Sp
11917 The string to be inserted is represented by octets starting at \f(CW\*(C`pv\*(C'\fR
11918 and continuing to the first nul. These octets are interpreted as either
11919 UTF\-8 or Latin\-1, according to whether the \f(CW\*(C`LEX_STUFF_UTF8\*(C'\fR flag is set
11920 in \f(CW\*(C`flags\*(C'\fR. The characters are recoded for the lexer buffer, according
11921 to how the buffer is currently being interpreted ("lex_bufutf8").
11922 If it is not convenient to nul-terminate a string to be inserted, the
11923 "lex_stuff_pvn" function is more appropriate.
11924 .RS 4
11925 .Sp
11926 .Vb 1
11927 \& void lex_stuff_pv(const char *pv, U32 flags)
11928 .Ve
11929 .RE
11930 .RS 4
11931 .RE
11932 .ie n .IP """lex_stuff_pvn""" 4
11933 .el .IP \f(CWlex_stuff_pvn\fR 4
11934 .IX Xref "lex_stuff_pvn"
11935 .IX Item "lex_stuff_pvn"
11936 NOTE: \f(CW\*(C`lex_stuff_pvn\*(C'\fR is \fBexperimental\fR and may change or be
11937 removed without notice.
11938 .Sp
11939 Insert characters into the lexer buffer ("PL_parser\->linestr"),
11940 immediately after the current lexing point ("PL_parser\->bufptr"),
11941 reallocating the buffer if necessary. This means that lexing code that
11942 runs later will see the characters as if they had appeared in the input.
11943 It is not recommended to do this as part of normal parsing, and most
11944 uses of this facility run the risk of the inserted characters being
11945 interpreted in an unintended manner.
11946 .Sp
11947 The string to be inserted is represented by \f(CW\*(C`len\*(C'\fR octets starting
11948 at \f(CW\*(C`pv\*(C'\fR. These octets are interpreted as either UTF\-8 or Latin\-1,
11949 according to whether the \f(CW\*(C`LEX_STUFF_UTF8\*(C'\fR flag is set in \f(CW\*(C`flags\*(C'\fR.
11950 The characters are recoded for the lexer buffer, according to how the
11951 buffer is currently being interpreted ("lex_bufutf8"). If a string
11952 to be inserted is available as a Perl scalar, the "lex_stuff_sv"
11953 function is more convenient.
11954 .RS 4
11955 .Sp
11956 .Vb 1
11957 \& void lex_stuff_pvn(const char *pv, STRLEN len, U32 flags)
11958 .Ve
11959 .RE
11960 .RS 4
11961 .RE
11962 .ie n .IP """lex_stuff_pvs""" 4
11963 .el .IP \f(CWlex_stuff_pvs\fR 4
11964 .IX Xref "lex_stuff_pvs"
11965 .IX Item "lex_stuff_pvs"
11966 NOTE: \f(CW\*(C`lex_stuff_pvs\*(C'\fR is \fBexperimental\fR and may change or be
11967 removed without notice.
11968 .Sp
11969 Like "lex_stuff_pvn", but takes a literal string instead of
11970 a string/length pair.
11971 .RS 4
11972 .Sp
11973 .Vb 1
11974 \& void lex_stuff_pvs("pv", U32 flags)
11975 .Ve
11976 .RE
11977 .RS 4
11978 .RE
11979 .ie n .IP """lex_stuff_sv""" 4
11980 .el .IP \f(CWlex_stuff_sv\fR 4
11981 .IX Xref "lex_stuff_sv"
11982 .IX Item "lex_stuff_sv"
11983 NOTE: \f(CW\*(C`lex_stuff_sv\*(C'\fR is \fBexperimental\fR and may change or be
11984 removed without notice.
11985 .Sp
11986 Insert characters into the lexer buffer ("PL_parser\->linestr"),
11987 immediately after the current lexing point ("PL_parser\->bufptr"),
11988 reallocating the buffer if necessary. This means that lexing code that
11989 runs later will see the characters as if they had appeared in the input.
11990 It is not recommended to do this as part of normal parsing, and most
11991 uses of this facility run the risk of the inserted characters being
11992 interpreted in an unintended manner.
11993 .Sp
11994 The string to be inserted is the string value of \f(CW\*(C`sv\*(C'\fR. The characters
11995 are recoded for the lexer buffer, according to how the buffer is currently
11996 being interpreted ("lex_bufutf8"). If a string to be inserted is
11997 not already a Perl scalar, the "lex_stuff_pvn" function avoids the
11998 need to construct a scalar.
11999 .RS 4
12000 .Sp
12001 .Vb 1
12002 \& void lex_stuff_sv(SV *sv, U32 flags)
12003 .Ve
12004 .RE
12005 .RS 4
12006 .RE
12007 .ie n .IP """lex_unstuff""" 4
12008 .el .IP \f(CWlex_unstuff\fR 4
12009 .IX Xref "lex_unstuff"
12010 .IX Item "lex_unstuff"
12011 NOTE: \f(CW\*(C`lex_unstuff\*(C'\fR is \fBexperimental\fR and may change or be
12012 removed without notice.
12013 .Sp
12014 Discards text about to be lexed, from "PL_parser\->bufptr" up to
12015 \&\f(CW\*(C`ptr\*(C'\fR. Text following \f(CW\*(C`ptr\*(C'\fR will be moved, and the buffer shortened.
12016 This hides the discarded text from any lexing code that runs later,
12017 as if the text had never appeared.
12018 .Sp
12019 This is not the normal way to consume lexed text. For that, use
12020 "lex_read_to".
12021 .RS 4
12022 .Sp
12023 .Vb 1
12024 \& void lex_unstuff(char *ptr)
12025 .Ve
12026 .RE
12027 .RS 4
12028 .RE
12029 .ie n .IP """parse_arithexpr""" 4
12030 .el .IP \f(CWparse_arithexpr\fR 4
12031 .IX Xref "parse_arithexpr"
12032 .IX Item "parse_arithexpr"
12033 NOTE: \f(CW\*(C`parse_arithexpr\*(C'\fR is \fBexperimental\fR and may change or be
12034 removed without notice.
12035 .Sp
12036 Parse a Perl arithmetic expression. This may contain operators of precedence
12037 down to the bit shift operators. The expression must be followed (and thus
12038 terminated) either by a comparison or lower-precedence operator or by
12039 something that would normally terminate an expression such as semicolon.
12040 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
12041 otherwise it is mandatory. It is up to the caller to ensure that the
12042 dynamic parser state ("PL_parser" et al) is correctly set to reflect
12043 the source of the code to be parsed and the lexical context for the
12044 expression.
12045 .Sp
12046 The op tree representing the expression is returned. If an optional
12047 expression is absent, a null pointer is returned, otherwise the pointer
12048 will be non-null.
12049 .Sp
12050 If an error occurs in parsing or compilation, in most cases a valid op
12051 tree is returned anyway. The error is reflected in the parser state,
12052 normally resulting in a single exception at the top level of parsing
12053 which covers all the compilation errors that occurred. Some compilation
12054 errors, however, will throw an exception immediately.
12055 .RS 4
12056 .Sp
12057 .Vb 1
12058 \& OP * parse_arithexpr(U32 flags)
12059 .Ve
12060 .RE
12061 .RS 4
12062 .RE
12063 .ie n .IP """parse_barestmt""" 4
12064 .el .IP \f(CWparse_barestmt\fR 4
12065 .IX Xref "parse_barestmt"
12066 .IX Item "parse_barestmt"
12067 NOTE: \f(CW\*(C`parse_barestmt\*(C'\fR is \fBexperimental\fR and may change or be
12068 removed without notice.
12069 .Sp
12070 Parse a single unadorned Perl statement. This may be a normal imperative
12071 statement or a declaration that has compile-time effect. It does not
12072 include any label or other affixture. It is up to the caller to ensure
12073 that the dynamic parser state ("PL_parser" et al) is correctly set to
12074 reflect the source of the code to be parsed and the lexical context for
12075 the statement.
12076 .Sp
12077 The op tree representing the statement is returned. This may be a
12078 null pointer if the statement is null, for example if it was actually
12079 a subroutine definition (which has compile-time side effects). If not
12080 null, it will be ops directly implementing the statement, suitable to
12081 pass to "newSTATEOP". It will not normally include a \f(CW\*(C`nextstate\*(C'\fR or
12082 equivalent op (except for those embedded in a scope contained entirely
12083 within the statement).
12084 .Sp
12085 If an error occurs in parsing or compilation, in most cases a valid op
12086 tree (most likely null) is returned anyway. The error is reflected in
12087 the parser state, normally resulting in a single exception at the top
12088 level of parsing which covers all the compilation errors that occurred.
12089 Some compilation errors, however, will throw an exception immediately.
12090 .Sp
12091 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12092 be zero.
12093 .RS 4
12094 .Sp
12095 .Vb 1
12096 \& OP * parse_barestmt(U32 flags)
12097 .Ve
12098 .RE
12099 .RS 4
12100 .RE
12101 .ie n .IP """parse_block""" 4
12102 .el .IP \f(CWparse_block\fR 4
12103 .IX Xref "parse_block"
12104 .IX Item "parse_block"
12105 NOTE: \f(CW\*(C`parse_block\*(C'\fR is \fBexperimental\fR and may change or be
12106 removed without notice.
12107 .Sp
12108 Parse a single complete Perl code block. This consists of an opening
12109 brace, a sequence of statements, and a closing brace. The block
12110 constitutes a lexical scope, so \f(CW\*(C`my\*(C'\fR variables and various compile-time
12111 effects can be contained within it. It is up to the caller to ensure
12112 that the dynamic parser state ("PL_parser" et al) is correctly set to
12113 reflect the source of the code to be parsed and the lexical context for
12114 the statement.
12115 .Sp
12116 The op tree representing the code block is returned. This is always a
12117 real op, never a null pointer. It will normally be a \f(CW\*(C`lineseq\*(C'\fR list,
12118 including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops. No ops to construct any kind
12119 of runtime scope are included by virtue of it being a block.
12120 .Sp
12121 If an error occurs in parsing or compilation, in most cases a valid op
12122 tree (most likely null) is returned anyway. The error is reflected in
12123 the parser state, normally resulting in a single exception at the top
12124 level of parsing which covers all the compilation errors that occurred.
12125 Some compilation errors, however, will throw an exception immediately.
12126 .Sp
12127 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12128 be zero.
12129 .RS 4
12130 .Sp
12131 .Vb 1
12132 \& OP * parse_block(U32 flags)
12133 .Ve
12134 .RE
12135 .RS 4
12136 .RE
12137 .ie n .IP """parse_fullexpr""" 4
12138 .el .IP \f(CWparse_fullexpr\fR 4
12139 .IX Xref "parse_fullexpr"
12140 .IX Item "parse_fullexpr"
12141 NOTE: \f(CW\*(C`parse_fullexpr\*(C'\fR is \fBexperimental\fR and may change or be
12142 removed without notice.
12143 .Sp
12144 Parse a single complete Perl expression. This allows the full
12145 expression grammar, including the lowest-precedence operators such
12146 as \f(CW\*(C`or\*(C'\fR. The expression must be followed (and thus terminated) by a
12147 token that an expression would normally be terminated by: end-of-file,
12148 closing bracketing punctuation, semicolon, or one of the keywords that
12149 signals a postfix expression-statement modifier. If \f(CW\*(C`flags\*(C'\fR has the
12150 \&\f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional, otherwise it is
12151 mandatory. It is up to the caller to ensure that the dynamic parser
12152 state ("PL_parser" et al) is correctly set to reflect the source of
12153 the code to be parsed and the lexical context for the expression.
12154 .Sp
12155 The op tree representing the expression is returned. If an optional
12156 expression is absent, a null pointer is returned, otherwise the pointer
12157 will be non-null.
12158 .Sp
12159 If an error occurs in parsing or compilation, in most cases a valid op
12160 tree is returned anyway. The error is reflected in the parser state,
12161 normally resulting in a single exception at the top level of parsing
12162 which covers all the compilation errors that occurred. Some compilation
12163 errors, however, will throw an exception immediately.
12164 .RS 4
12165 .Sp
12166 .Vb 1
12167 \& OP * parse_fullexpr(U32 flags)
12168 .Ve
12169 .RE
12170 .RS 4
12171 .RE
12172 .ie n .IP """parse_fullstmt""" 4
12173 .el .IP \f(CWparse_fullstmt\fR 4
12174 .IX Xref "parse_fullstmt"
12175 .IX Item "parse_fullstmt"
12176 NOTE: \f(CW\*(C`parse_fullstmt\*(C'\fR is \fBexperimental\fR and may change or be
12177 removed without notice.
12178 .Sp
12179 Parse a single complete Perl statement. This may be a normal imperative
12180 statement or a declaration that has compile-time effect, and may include
12181 optional labels. It is up to the caller to ensure that the dynamic
12182 parser state ("PL_parser" et al) is correctly set to reflect the source
12183 of the code to be parsed and the lexical context for the statement.
12184 .Sp
12185 The op tree representing the statement is returned. This may be a
12186 null pointer if the statement is null, for example if it was actually
12187 a subroutine definition (which has compile-time side effects). If not
12188 null, it will be the result of a "newSTATEOP" call, normally including
12189 a \f(CW\*(C`nextstate\*(C'\fR or equivalent op.
12190 .Sp
12191 If an error occurs in parsing or compilation, in most cases a valid op
12192 tree (most likely null) is returned anyway. The error is reflected in
12193 the parser state, normally resulting in a single exception at the top
12194 level of parsing which covers all the compilation errors that occurred.
12195 Some compilation errors, however, will throw an exception immediately.
12196 .Sp
12197 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12198 be zero.
12199 .RS 4
12200 .Sp
12201 .Vb 1
12202 \& OP * parse_fullstmt(U32 flags)
12203 .Ve
12204 .RE
12205 .RS 4
12206 .RE
12207 .ie n .IP """parse_label""" 4
12208 .el .IP \f(CWparse_label\fR 4
12209 .IX Xref "parse_label"
12210 .IX Item "parse_label"
12211 NOTE: \f(CW\*(C`parse_label\*(C'\fR is \fBexperimental\fR and may change or be
12212 removed without notice.
12213 .Sp
12214 Parse a single label, possibly optional, of the type that may prefix a
12215 Perl statement. It is up to the caller to ensure that the dynamic parser
12216 state ("PL_parser" et al) is correctly set to reflect the source of
12217 the code to be parsed. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the
12218 label is optional, otherwise it is mandatory.
12219 .Sp
12220 The name of the label is returned in the form of a fresh scalar. If an
12221 optional label is absent, a null pointer is returned.
12222 .Sp
12223 If an error occurs in parsing, which can only occur if the label is
12224 mandatory, a valid label is returned anyway. The error is reflected in
12225 the parser state, normally resulting in a single exception at the top
12226 level of parsing which covers all the compilation errors that occurred.
12227 .RS 4
12228 .Sp
12229 .Vb 1
12230 \& SV * parse_label(U32 flags)
12231 .Ve
12232 .RE
12233 .RS 4
12234 .RE
12235 .ie n .IP """parse_listexpr""" 4
12236 .el .IP \f(CWparse_listexpr\fR 4
12237 .IX Xref "parse_listexpr"
12238 .IX Item "parse_listexpr"
12239 NOTE: \f(CW\*(C`parse_listexpr\*(C'\fR is \fBexperimental\fR and may change or be
12240 removed without notice.
12241 .Sp
12242 Parse a Perl list expression. This may contain operators of precedence
12243 down to the comma operator. The expression must be followed (and thus
12244 terminated) either by a low-precedence logic operator such as \f(CW\*(C`or\*(C'\fR or by
12245 something that would normally terminate an expression such as semicolon.
12246 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
12247 otherwise it is mandatory. It is up to the caller to ensure that the
12248 dynamic parser state ("PL_parser" et al) is correctly set to reflect
12249 the source of the code to be parsed and the lexical context for the
12250 expression.
12251 .Sp
12252 The op tree representing the expression is returned. If an optional
12253 expression is absent, a null pointer is returned, otherwise the pointer
12254 will be non-null.
12255 .Sp
12256 If an error occurs in parsing or compilation, in most cases a valid op
12257 tree is returned anyway. The error is reflected in the parser state,
12258 normally resulting in a single exception at the top level of parsing
12259 which covers all the compilation errors that occurred. Some compilation
12260 errors, however, will throw an exception immediately.
12261 .RS 4
12262 .Sp
12263 .Vb 1
12264 \& OP * parse_listexpr(U32 flags)
12265 .Ve
12266 .RE
12267 .RS 4
12268 .RE
12269 .ie n .IP """parse_stmtseq""" 4
12270 .el .IP \f(CWparse_stmtseq\fR 4
12271 .IX Xref "parse_stmtseq"
12272 .IX Item "parse_stmtseq"
12273 NOTE: \f(CW\*(C`parse_stmtseq\*(C'\fR is \fBexperimental\fR and may change or be
12274 removed without notice.
12275 .Sp
12276 Parse a sequence of zero or more Perl statements. These may be normal
12277 imperative statements, including optional labels, or declarations
12278 that have compile-time effect, or any mixture thereof. The statement
12279 sequence ends when a closing brace or end-of-file is encountered in a
12280 place where a new statement could have validly started. It is up to
12281 the caller to ensure that the dynamic parser state ("PL_parser" et al)
12282 is correctly set to reflect the source of the code to be parsed and the
12283 lexical context for the statements.
12284 .Sp
12285 The op tree representing the statement sequence is returned. This may
12286 be a null pointer if the statements were all null, for example if there
12287 were no statements or if there were only subroutine definitions (which
12288 have compile-time side effects). If not null, it will be a \f(CW\*(C`lineseq\*(C'\fR
12289 list, normally including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops.
12290 .Sp
12291 If an error occurs in parsing or compilation, in most cases a valid op
12292 tree is returned anyway. The error is reflected in the parser state,
12293 normally resulting in a single exception at the top level of parsing
12294 which covers all the compilation errors that occurred. Some compilation
12295 errors, however, will throw an exception immediately.
12296 .Sp
12297 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12298 be zero.
12299 .RS 4
12300 .Sp
12301 .Vb 1
12302 \& OP * parse_stmtseq(U32 flags)
12303 .Ve
12304 .RE
12305 .RS 4
12306 .RE
12307 .ie n .IP """parse_subsignature""" 4
12308 .el .IP \f(CWparse_subsignature\fR 4
12309 .IX Xref "parse_subsignature"
12310 .IX Item "parse_subsignature"
12311 NOTE: \f(CW\*(C`parse_subsignature\*(C'\fR is \fBexperimental\fR and may change or be
12312 removed without notice.
12313 .Sp
12314 Parse a subroutine signature declaration. This is the contents of the
12315 parentheses following a named or anonymous subroutine declaration when the
12316 \&\f(CW\*(C`signatures\*(C'\fR feature is enabled. Note that this function neither expects
12317 nor consumes the opening and closing parentheses around the signature; it
12318 is the caller's job to handle these.
12319 .Sp
12320 This function must only be called during parsing of a subroutine; after
12321 "start_subparse" has been called. It might allocate lexical variables on
12322 the pad for the current subroutine.
12323 .Sp
12324 The op tree to unpack the arguments from the stack at runtime is returned.
12325 This op tree should appear at the beginning of the compiled function. The
12326 caller may wish to use "op_append_list" to build their function body
12327 after it, or splice it together with the body before calling "newATTRSUB".
12328 .Sp
12329 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12330 be zero.
12331 .RS 4
12332 .Sp
12333 .Vb 1
12334 \& OP * parse_subsignature(U32 flags)
12335 .Ve
12336 .RE
12337 .RS 4
12338 .RE
12339 .ie n .IP """parse_termexpr""" 4
12340 .el .IP \f(CWparse_termexpr\fR 4
12341 .IX Xref "parse_termexpr"
12342 .IX Item "parse_termexpr"
12343 NOTE: \f(CW\*(C`parse_termexpr\*(C'\fR is \fBexperimental\fR and may change or be
12344 removed without notice.
12345 .Sp
12346 Parse a Perl term expression. This may contain operators of precedence
12347 down to the assignment operators. The expression must be followed (and thus
12348 terminated) either by a comma or lower-precedence operator or by
12349 something that would normally terminate an expression such as semicolon.
12350 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
12351 otherwise it is mandatory. It is up to the caller to ensure that the
12352 dynamic parser state ("PL_parser" et al) is correctly set to reflect
12353 the source of the code to be parsed and the lexical context for the
12354 expression.
12355 .Sp
12356 The op tree representing the expression is returned. If an optional
12357 expression is absent, a null pointer is returned, otherwise the pointer
12358 will be non-null.
12359 .Sp
12360 If an error occurs in parsing or compilation, in most cases a valid op
12361 tree is returned anyway. The error is reflected in the parser state,
12362 normally resulting in a single exception at the top level of parsing
12363 which covers all the compilation errors that occurred. Some compilation
12364 errors, however, will throw an exception immediately.
12365 .RS 4
12366 .Sp
12367 .Vb 1
12368 \& OP * parse_termexpr(U32 flags)
12369 .Ve
12370 .RE
12371 .RS 4
12372 .RE
12373 .ie n .IP """PL_parser""" 4
12374 .el .IP \f(CWPL_parser\fR 4
12375 .IX Xref "PL_parser"
12376 .IX Item "PL_parser"
12377 Pointer to a structure encapsulating the state of the parsing operation
12378 currently in progress. The pointer can be locally changed to perform
12379 a nested parse without interfering with the state of an outer parse.
12380 Individual members of \f(CW\*(C`PL_parser\*(C'\fR have their own documentation.
12381 .ie n .IP """PL_parser\->bufend""" 4
12382 .el .IP \f(CWPL_parser\->bufend\fR 4
12383 .IX Xref "PL_parser->bufend"
12384 .IX Item "PL_parser->bufend"
12385 NOTE: \f(CW\*(C`PL_parser\->bufend\*(C'\fR is \fBexperimental\fR and may change or be
12386 removed without notice.
12387 .Sp
12388 Direct pointer to the end of the chunk of text currently being lexed, the
12389 end of the lexer buffer. This is equal to \f(CW\*(C`SvPVX(PL_parser\->linestr)
12390 + SvCUR(PL_parser\->linestr)\*(C'\fR. A \f(CW\*(C`NUL\*(C'\fR character (zero octet) is
12391 always located at the end of the buffer, and does not count as part of
12392 the buffer's contents.
12393 .ie n .IP """PL_parser\->bufptr""" 4
12394 .el .IP \f(CWPL_parser\->bufptr\fR 4
12395 .IX Xref "PL_parser->bufptr"
12396 .IX Item "PL_parser->bufptr"
12397 NOTE: \f(CW\*(C`PL_parser\->bufptr\*(C'\fR is \fBexperimental\fR and may change or be
12398 removed without notice.
12399 .Sp
12400 Points to the current position of lexing inside the lexer buffer.
12401 Characters around this point may be freely examined, within
12402 the range delimited by \f(CWSvPVX("PL_parser\->linestr")\fR and
12403 "PL_parser\->bufend". The octets of the buffer may be intended to be
12404 interpreted as either UTF\-8 or Latin\-1, as indicated by "lex_bufutf8".
12405 .Sp
12406 Lexing code (whether in the Perl core or not) moves this pointer past
12407 the characters that it consumes. It is also expected to perform some
12408 bookkeeping whenever a newline character is consumed. This movement
12409 can be more conveniently performed by the function "lex_read_to",
12410 which handles newlines appropriately.
12411 .Sp
12412 Interpretation of the buffer's octets can be abstracted out by
12413 using the slightly higher-level functions "lex_peek_unichar" and
12414 "lex_read_unichar".
12415 .ie n .IP """PL_parser\->linestart""" 4
12416 .el .IP \f(CWPL_parser\->linestart\fR 4
12417 .IX Xref "PL_parser->linestart"
12418 .IX Item "PL_parser->linestart"
12419 NOTE: \f(CW\*(C`PL_parser\->linestart\*(C'\fR is \fBexperimental\fR and may change or be
12420 removed without notice.
12421 .Sp
12422 Points to the start of the current line inside the lexer buffer.
12423 This is useful for indicating at which column an error occurred, and
12424 not much else. This must be updated by any lexing code that consumes
12425 a newline; the function "lex_read_to" handles this detail.
12426 .ie n .IP """PL_parser\->linestr""" 4
12427 .el .IP \f(CWPL_parser\->linestr\fR 4
12428 .IX Xref "PL_parser->linestr"
12429 .IX Item "PL_parser->linestr"
12430 NOTE: \f(CW\*(C`PL_parser\->linestr\*(C'\fR is \fBexperimental\fR and may change or be
12431 removed without notice.
12432 .Sp
12433 Buffer scalar containing the chunk currently under consideration of the
12434 text currently being lexed. This is always a plain string scalar (for
12435 which \f(CW\*(C`SvPOK\*(C'\fR is true). It is not intended to be used as a scalar by
12436 normal scalar means; instead refer to the buffer directly by the pointer
12437 variables described below.
12438 .Sp
12439 The lexer maintains various \f(CW\*(C`char*\*(C'\fR pointers to things in the
12440 \&\f(CW\*(C`PL_parser\->linestr\*(C'\fR buffer. If \f(CW\*(C`PL_parser\->linestr\*(C'\fR is ever
12441 reallocated, all of these pointers must be updated. Don't attempt to
12442 do this manually, but rather use "lex_grow_linestr" if you need to
12443 reallocate the buffer.
12444 .Sp
12445 The content of the text chunk in the buffer is commonly exactly one
12446 complete line of input, up to and including a newline terminator,
12447 but there are situations where it is otherwise. The octets of the
12448 buffer may be intended to be interpreted as either UTF\-8 or Latin\-1.
12449 The function "lex_bufutf8" tells you which. Do not use the \f(CW\*(C`SvUTF8\*(C'\fR
12450 flag on this scalar, which may disagree with it.
12451 .Sp
12452 For direct examination of the buffer, the variable
12453 "PL_parser\->bufend" points to the end of the buffer. The current
12454 lexing position is pointed to by "PL_parser\->bufptr". Direct use
12455 of these pointers is usually preferable to examination of the scalar
12456 through normal scalar means.
12457 .ie n .IP """suspend_compcv""" 4
12458 .el .IP \f(CWsuspend_compcv\fR 4
12459 .IX Xref "suspend_compcv"
12460 .IX Item "suspend_compcv"
12461 Implements part of the concept of a "suspended compilation CV", which can be
12462 used to pause the parser and compiler during parsing a CV in order to come
12463 back to it later on.
12464 .Sp
12465 This function saves the current state of the subroutine under compilation
12466 (\f(CW\*(C`PL_compcv\*(C'\fR) into the supplied buffer. This should be used initially to
12467 create the state in the buffer, as the final thing before a \f(CW\*(C`LEAVE\*(C'\fR within a
12468 block.
12469 .Sp
12470 .Vb 3
12471 \& ENTER;
12472 \& start_subparse(0);
12473 \& ...
12474 \&
12475 \& suspend_compcv(&buffer);
12476 \& LEAVE;
12477 .Ve
12478 .Sp
12479 Once suspended, the \f(CW\*(C`resume_compcv_final\*(C'\fR or \f(CW\*(C`resume_compcv_and_save\*(C'\fR
12480 function can later be used to continue the parsing from the point this stopped.
12481 .RS 4
12482 .Sp
12483 .Vb 1
12484 \& void suspend_compcv(struct suspended_compcv *buffer)
12485 .Ve
12486 .RE
12487 .RS 4
12488 .RE
12489 .ie n .IP """wrap_infix_plugin""" 4
12490 .el .IP \f(CWwrap_infix_plugin\fR 4
12491 .IX Xref "wrap_infix_plugin"
12492 .IX Item "wrap_infix_plugin"
12493 NOTE: \f(CW\*(C`wrap_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be
12494 removed without notice.
12495 .Sp
12496 \&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module
12497 \&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make
12498 use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing
12499 of new infix operators.
12500 .Sp
12501 Puts a C function into the chain of infix plugins. This is the preferred
12502 way to manipulate the "PL_infix_plugin" variable. \f(CW\*(C`new_plugin\*(C'\fR is a
12503 pointer to the C function that is to be added to the infix plugin chain, and
12504 \&\f(CW\*(C`old_plugin_p\*(C'\fR points to a storage location where a pointer to the next
12505 function in the chain will be stored. The value of \f(CW\*(C`new_plugin\*(C'\fR is written
12506 into the "PL_infix_plugin" variable, while the value previously stored there
12507 is written to \f(CW*old_plugin_p\fR.
12508 .Sp
12509 Direct access to "PL_infix_plugin" should be avoided.
12510 .RS 4
12511 .Sp
12512 .Vb 2
12513 \& void wrap_infix_plugin(Perl_infix_plugin_t new_plugin,
12514 \& Perl_infix_plugin_t *old_plugin_p)
12515 .Ve
12516 .RE
12517 .RS 4
12518 .RE
12519 .ie n .IP """wrap_keyword_plugin""" 4
12520 .el .IP \f(CWwrap_keyword_plugin\fR 4
12521 .IX Xref "wrap_keyword_plugin"
12522 .IX Item "wrap_keyword_plugin"
12523 NOTE: \f(CW\*(C`wrap_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be
12524 removed without notice.
12525 .Sp
12526 Puts a C function into the chain of keyword plugins. This is the
12527 preferred way to manipulate the "PL_keyword_plugin" variable.
12528 \&\f(CW\*(C`new_plugin\*(C'\fR is a pointer to the C function that is to be added to the
12529 keyword plugin chain, and \f(CW\*(C`old_plugin_p\*(C'\fR points to the storage location
12530 where a pointer to the next function in the chain will be stored. The
12531 value of \f(CW\*(C`new_plugin\*(C'\fR is written into the "PL_keyword_plugin" variable,
12532 while the value previously stored there is written to \f(CW*old_plugin_p\fR.
12533 .Sp
12534 "PL_keyword_plugin" is global to an entire process, and a module wishing
12535 to hook keyword parsing may find itself invoked more than once per
12536 process, typically in different threads. To handle that situation, this
12537 function is idempotent. The location \f(CW*old_plugin_p\fR must initially
12538 (once per process) contain a null pointer. A C variable of static
12539 duration (declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give
12540 it internal linkage) will be implicitly initialised appropriately, if it
12541 does not have an explicit initialiser. This function will only actually
12542 modify the plugin chain if it finds \f(CW*old_plugin_p\fR to be null. This
12543 function is also thread safe on the small scale. It uses appropriate
12544 locking to avoid race conditions in accessing "PL_keyword_plugin".
12545 .Sp
12546 When this function is called, the function referenced by \f(CW\*(C`new_plugin\*(C'\fR
12547 must be ready to be called, except for \f(CW*old_plugin_p\fR being unfilled.
12548 In a threading situation, \f(CW\*(C`new_plugin\*(C'\fR may be called immediately, even
12549 before this function has returned. \f(CW*old_plugin_p\fR will always be
12550 appropriately set before \f(CW\*(C`new_plugin\*(C'\fR is called. If \f(CW\*(C`new_plugin\*(C'\fR
12551 decides not to do anything special with the identifier that it is given
12552 (which is the usual case for most calls to a keyword plugin), it must
12553 chain the plugin function referenced by \f(CW*old_plugin_p\fR.
12554 .Sp
12555 Taken all together, XS code to install a keyword plugin should typically
12556 look something like this:
12557 .Sp
12558 .Vb 10
12559 \& static Perl_keyword_plugin_t next_keyword_plugin;
12560 \& static OP *my_keyword_plugin(pTHX_
12561 \& char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
12562 \& {
12563 \& if (memEQs(keyword_ptr, keyword_len,
12564 \& "my_new_keyword")) {
12565 \& ...
12566 \& } else {
12567 \& return next_keyword_plugin(aTHX_
12568 \& keyword_ptr, keyword_len, op_ptr);
12569 \& }
12570 \& }
12571 \& BOOT:
12572 \& wrap_keyword_plugin(my_keyword_plugin,
12573 \& &next_keyword_plugin);
12574 .Ve
12575 .Sp
12576 Direct access to "PL_keyword_plugin" should be avoided.
12577 .RS 4
12578 .Sp
12579 .Vb 2
12580 \& void wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
12581 \& Perl_keyword_plugin_t *old_plugin_p)
12582 .Ve
12583 .RE
12584 .RS 4
12585 .RE
12586 .SH Locales
12587 .IX Header "Locales"
12588 .ie n .IP """DECLARATION_FOR_LC_NUMERIC_MANIPULATION""" 4
12589 .el .IP \f(CWDECLARATION_FOR_LC_NUMERIC_MANIPULATION\fR 4
12590 .IX Xref "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
12591 .IX Item "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
12592 This macro should be used as a statement. It declares a private variable
12593 (whose name begins with an underscore) that is needed by the other macros in
12594 this section. Failing to include this correctly should lead to a syntax error.
12595 For compatibility with C89 C compilers it should be placed in a block before
12596 any executable statements.
12597 .RS 4
12598 .Sp
12599 .Vb 1
12600 \& void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
12601 .Ve
12602 .RE
12603 .RS 4
12604 .RE
12605 .ie n .IP """foldEQ_locale""" 4
12606 .el .IP \f(CWfoldEQ_locale\fR 4
12607 .IX Xref "foldEQ_locale"
12608 .IX Item "foldEQ_locale"
12609 Returns true if the leading \f(CW\*(C`len\*(C'\fR bytes of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR are the
12610 same case-insensitively in the current locale; false otherwise.
12611 .RS 4
12612 .Sp
12613 .Vb 1
12614 \& I32 foldEQ_locale(const char *a, const char *b, I32 len)
12615 .Ve
12616 .RE
12617 .RS 4
12618 .RE
12619 .ie n .IP """HAS_DUPLOCALE""" 4
12620 .el .IP \f(CWHAS_DUPLOCALE\fR 4
12621 .IX Xref "HAS_DUPLOCALE"
12622 .IX Item "HAS_DUPLOCALE"
12623 This symbol, if defined, indicates that the \f(CW\*(C`duplocale\*(C'\fR routine is
12624 available to duplicate a locale object.
12625 .ie n .IP """HAS_FREELOCALE""" 4
12626 .el .IP \f(CWHAS_FREELOCALE\fR 4
12627 .IX Xref "HAS_FREELOCALE"
12628 .IX Item "HAS_FREELOCALE"
12629 This symbol, if defined, indicates that the \f(CW\*(C`freelocale\*(C'\fR routine is
12630 available to deallocates the resources associated with a locale object.
12631 .ie n .IP """HAS_LC_MONETARY_2008""" 4
12632 .el .IP \f(CWHAS_LC_MONETARY_2008\fR 4
12633 .IX Xref "HAS_LC_MONETARY_2008"
12634 .IX Item "HAS_LC_MONETARY_2008"
12635 This symbol, if defined, indicates that the localeconv routine is
12636 available and has the additional members added in \f(CW\*(C`POSIX\*(C'\fR 1003.1\-2008.
12637 .ie n .IP """HAS_LOCALECONV""" 4
12638 .el .IP \f(CWHAS_LOCALECONV\fR 4
12639 .IX Xref "HAS_LOCALECONV"
12640 .IX Item "HAS_LOCALECONV"
12641 This symbol, if defined, indicates that the \f(CW\*(C`localeconv\*(C'\fR routine is
12642 available for numeric and monetary formatting conventions.
12643 .ie n .IP """HAS_LOCALECONV_L""" 4
12644 .el .IP \f(CWHAS_LOCALECONV_L\fR 4
12645 .IX Xref "HAS_LOCALECONV_L"
12646 .IX Item "HAS_LOCALECONV_L"
12647 This symbol, if defined, indicates that the \f(CW\*(C`localeconv_l\*(C'\fR routine is
12648 available to query certain information about a locale.
12649 .ie n .IP """HAS_NEWLOCALE""" 4
12650 .el .IP \f(CWHAS_NEWLOCALE\fR 4
12651 .IX Xref "HAS_NEWLOCALE"
12652 .IX Item "HAS_NEWLOCALE"
12653 This symbol, if defined, indicates that the \f(CW\*(C`newlocale\*(C'\fR routine is
12654 available to return a new locale object or modify an existing
12655 locale object.
12656 .ie n .IP """HAS_NL_LANGINFO""" 4
12657 .el .IP \f(CWHAS_NL_LANGINFO\fR 4
12658 .IX Xref "HAS_NL_LANGINFO"
12659 .IX Item "HAS_NL_LANGINFO"
12660 This symbol, if defined, indicates that the \f(CW\*(C`nl_langinfo\*(C'\fR routine is
12661 available to return locale data. You will also need \fIlanginfo.h\fR
12662 and therefore \f(CW\*(C`I_LANGINFO\*(C'\fR.
12663 .ie n .IP """HAS_NL_LANGINFO_L""" 4
12664 .el .IP \f(CWHAS_NL_LANGINFO_L\fR 4
12665 .IX Xref "HAS_NL_LANGINFO_L"
12666 .IX Item "HAS_NL_LANGINFO_L"
12667 This symbol, if defined, indicates that the \f(CW\*(C`nl_langinfo_l\*(C'\fR routine is
12668 available to return locale data. You will also need \fIlanginfo.h\fR
12669 and therefore \f(CW\*(C`I_LANGINFO\*(C'\fR.
12670 .ie n .IP """HAS_QUERYLOCALE""" 4
12671 .el .IP \f(CWHAS_QUERYLOCALE\fR 4
12672 .IX Xref "HAS_QUERYLOCALE"
12673 .IX Item "HAS_QUERYLOCALE"
12674 This symbol, if defined, indicates that the \f(CW\*(C`querylocale\*(C'\fR routine is
12675 available to return the name of the locale for a category mask.
12676 .ie n .IP """HAS_SETLOCALE""" 4
12677 .el .IP \f(CWHAS_SETLOCALE\fR 4
12678 .IX Xref "HAS_SETLOCALE"
12679 .IX Item "HAS_SETLOCALE"
12680 This symbol, if defined, indicates that the \f(CW\*(C`setlocale\*(C'\fR routine is
12681 available to handle locale-specific ctype implementations.
12682 .ie n .IP """HAS_SETLOCALE_R""" 4
12683 .el .IP \f(CWHAS_SETLOCALE_R\fR 4
12684 .IX Xref "HAS_SETLOCALE_R"
12685 .IX Item "HAS_SETLOCALE_R"
12686 This symbol, if defined, indicates that the \f(CW\*(C`setlocale_r\*(C'\fR routine
12687 is available to setlocale re-entrantly.
12688 .ie n .IP """HAS_USELOCALE""" 4
12689 .el .IP \f(CWHAS_USELOCALE\fR 4
12690 .IX Xref "HAS_USELOCALE"
12691 .IX Item "HAS_USELOCALE"
12692 This symbol, if defined, indicates that the \f(CW\*(C`uselocale\*(C'\fR routine is
12693 available to set the current locale for the calling thread.
12694 .ie n .IP """I_LANGINFO""" 4
12695 .el .IP \f(CWI_LANGINFO\fR 4
12696 .IX Xref "I_LANGINFO"
12697 .IX Item "I_LANGINFO"
12698 This symbol, if defined, indicates that \fIlanginfo.h\fR exists and
12699 should be included.
12700 .RS 4
12701 .Sp
12702 .Vb 3
12703 \& #ifdef I_LANGINFO
12704 \& #include <langinfo.h>
12705 \& #endif
12706 .Ve
12707 .RE
12708 .RS 4
12709 .RE
12710 .ie n .IP """I_LOCALE""" 4
12711 .el .IP \f(CWI_LOCALE\fR 4
12712 .IX Xref "I_LOCALE"
12713 .IX Item "I_LOCALE"
12714 This symbol, if defined, indicates to the C program that it should
12715 include \fIlocale.h\fR.
12716 .RS 4
12717 .Sp
12718 .Vb 3
12719 \& #ifdef I_LOCALE
12720 \& #include <locale.h>
12721 \& #endif
12722 .Ve
12723 .RE
12724 .RS 4
12725 .RE
12726 .ie n .IP """IN_LOCALE""" 4
12727 .el .IP \f(CWIN_LOCALE\fR 4
12728 .IX Xref "IN_LOCALE"
12729 .IX Item "IN_LOCALE"
12730 Evaluates to TRUE if the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
12731 .RS 4
12732 .Sp
12733 .Vb 1
12734 \& bool IN_LOCALE
12735 .Ve
12736 .RE
12737 .RS 4
12738 .RE
12739 .ie n .IP """IN_LOCALE_COMPILETIME""" 4
12740 .el .IP \f(CWIN_LOCALE_COMPILETIME\fR 4
12741 .IX Xref "IN_LOCALE_COMPILETIME"
12742 .IX Item "IN_LOCALE_COMPILETIME"
12743 Evaluates to TRUE if, when compiling a perl program (including an \f(CW\*(C`eval\*(C'\fR) if
12744 the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
12745 .RS 4
12746 .Sp
12747 .Vb 1
12748 \& bool IN_LOCALE_COMPILETIME
12749 .Ve
12750 .RE
12751 .RS 4
12752 .RE
12753 .ie n .IP """IN_LOCALE_RUNTIME""" 4
12754 .el .IP \f(CWIN_LOCALE_RUNTIME\fR 4
12755 .IX Xref "IN_LOCALE_RUNTIME"
12756 .IX Item "IN_LOCALE_RUNTIME"
12757 Evaluates to TRUE if, when executing a perl program (including an \f(CW\*(C`eval\*(C'\fR) if
12758 the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
12759 .RS 4
12760 .Sp
12761 .Vb 1
12762 \& bool IN_LOCALE_RUNTIME
12763 .Ve
12764 .RE
12765 .RS 4
12766 .RE
12767 .ie n .IP """I_XLOCALE""" 4
12768 .el .IP \f(CWI_XLOCALE\fR 4
12769 .IX Xref "I_XLOCALE"
12770 .IX Item "I_XLOCALE"
12771 This symbol, if defined, indicates to the C program that the
12772 header \fIxlocale.h\fR is available. See also \f(CW"NEED_XLOCALE_H"\fR
12773 .RS 4
12774 .Sp
12775 .Vb 3
12776 \& #ifdef I_XLOCALE
12777 \& #include <xlocale.h>
12778 \& #endif
12779 .Ve
12780 .RE
12781 .RS 4
12782 .RE
12783 .ie n .IP """NEED_XLOCALE_H""" 4
12784 .el .IP \f(CWNEED_XLOCALE_H\fR 4
12785 .IX Xref "NEED_XLOCALE_H"
12786 .IX Item "NEED_XLOCALE_H"
12787 This symbol, if defined, indicates that the C program should
12788 include \fIxlocale.h\fR to get \f(CWnewlocale()\fR and its friends.
12789 .ie n .IP """Perl_langinfo""" 4
12790 .el .IP \f(CWPerl_langinfo\fR 4
12791 .IX Item "Perl_langinfo"
12792 .PD 0
12793 .ie n .IP """Perl_langinfo8""" 4
12794 .el .IP \f(CWPerl_langinfo8\fR 4
12795 .IX Xref "Perl_langinfo Perl_langinfo8"
12796 .IX Item "Perl_langinfo8"
12797 .PD
12798 \&\f(CW\*(C`Perl_langinfo\*(C'\fR is an (almost) drop-in replacement for the system
12799 \&\f(CWnl_langinfo(3)\fR, taking the same \f(CW\*(C`item\*(C'\fR parameter values, and returning
12800 the same information. But it is more thread-safe than regular
12801 \&\f(CWnl_langinfo()\fR, and hides the quirks of Perl's locale handling from your
12802 code, and can be used on systems that lack a native \f(CW\*(C`nl_langinfo\*(C'\fR.
12803 .Sp
12804 However, you should instead use either the improved version of this,
12805 "Perl_langinfo8", or even better, "sv_langinfo". The latter returns an SV,
12806 handling all the possible non-standard returns of \f(CWnl_langinfo()\fR, including
12807 the UTF8ness of any returned string.
12808 .Sp
12809 \&\f(CW\*(C`Perl_langinfo8\*(C'\fR is identical to \f(CW\*(C`Perl_langinfo\*(C'\fR except for an additional
12810 parameter, a pointer to a variable declared as "\f(CW\*(C`utf8ness_t\*(C'\fR", into which it
12811 returns to you how you should treat the returned string with regards to it
12812 being encoded in UTF\-8 or not.
12813 .Sp
12814 These two functions share private per-thread memory that will be changed the
12815 next time either one of them is called with any input, but not before.
12816 .Sp
12817 Concerning the differences between these and plain \f(CWnl_langinfo()\fR:
12818 .RS 4
12819 .IP a. 4
12820 .IX Item "a."
12821 \&\f(CW\*(C`Perl_langinfo8\*(C'\fR has an extra parameter, described above. Besides this, the
12822 other reason they aren't quite a drop-in replacement is actually an advantage.
12823 The \f(CW\*(C`const\*(C'\fRness of the return allows the compiler to catch attempts to write
12824 into the returned buffer, which is illegal and could cause run-time crashes.
12825 .IP b. 4
12826 .IX Item "b."
12827 They deliver the correct results for the \f(CW\*(C`RADIXCHAR\*(C'\fR and \f(CW\*(C`THOUSEP\*(C'\fR items,
12828 without you having to write extra code. The reason for the extra code would be
12829 because these are from the \f(CW\*(C`LC_NUMERIC\*(C'\fR locale category, which is normally
12830 kept set by Perl so that the radix is a dot, and the separator is the empty
12831 string, no matter what the underlying locale is supposed to be, and so to get
12832 the expected results, you have to temporarily toggle into the underlying
12833 locale, and later toggle back. (You could use plain \f(CW\*(C`nl_langinfo\*(C'\fR and
12834 \&\f(CW"STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"\fR for this but then you wouldn't get
12835 the other advantages of \f(CWPerl_langinfo()\fR; not keeping \f(CW\*(C`LC_NUMERIC\*(C'\fR in the C
12836 (or equivalent) locale would break a lot of CPAN, which is expecting the radix
12837 (decimal point) character to be a dot.)
12838 .IP c. 4
12839 .IX Item "c."
12840 The system function they replace can have its static return buffer trashed,
12841 not only by a subsequent call to that function, but by a \f(CW\*(C`freelocale\*(C'\fR,
12842 \&\f(CW\*(C`setlocale\*(C'\fR, or other locale change. The returned buffer of these functions
12843 is not changed until the next call to one or the other, so the buffer is never
12844 in a trashed state.
12845 .IP d. 4
12846 .IX Item "d."
12847 The return buffer is per-thread, so it also is never overwritten by a call to
12848 these functions from another thread; unlike the function it replaces.
12849 .IP e. 4
12850 .IX Item "e."
12851 But most importantly, they work on systems that don't have \f(CW\*(C`nl_langinfo\*(C'\fR, such
12852 as Windows, hence making your code more portable. Of the fifty-some possible
12853 items specified by the POSIX 2008 standard,
12854 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
12855 only one is completely unimplemented, though on non-Windows platforms, another
12856 significant one is not fully implemented). They use various techniques to
12857 recover the other items, including calling \f(CWlocaleconv(3)\fR, and
12858 \&\f(CWstrftime(3)\fR, both of which are specified in C89, so should be always be
12859 available. Later \f(CWstrftime()\fR versions have additional capabilities.
12860 If an item is not available on your system, this returns either the value
12861 associated with the C locale, or simply \f(CW""\fR, whichever is more appropriate.
12862 .Sp
12863 It is important to note that, when called with an item that is recovered by
12864 using \f(CW\*(C`localeconv\*(C'\fR, the buffer from any previous explicit call to
12865 \&\f(CWlocaleconv(3)\fR will be overwritten. But you shouldn't be using
12866 \&\f(CW\*(C`localeconv\*(C'\fR anyway because it is is very much not thread-safe, and suffers
12867 from the same problems outlined in item 'b.' above for the fields it returns
12868 that are controlled by the LC_NUMERIC locale category. Instead, avoid all of
12869 those problems by calling "Perl_localeconv", which is thread-safe; or by
12870 using the methods given in perlcall to call
12871 \&\f(CWPOSIX::localeconv()\fR, which is also thread-safe.
12872 .RE
12873 .RS 4
12874 .Sp
12875 The details for those items which may deviate from what this emulation returns
12876 and what a native \f(CWnl_langinfo()\fR would return are specified in
12877 I18N::Langinfo.
12878 .Sp
12879 .Vb 3
12880 \& const char * Perl_langinfo (const nl_item item)
12881 \& const char * Perl_langinfo8(const nl_item item,
12882 \& utf8ness_t *utf8ness)
12883 .Ve
12884 .RE
12885 .RS 4
12886 .RE
12887 .ie n .IP """PERL_LC_ALL_CATEGORY_POSITIONS_INIT""" 4
12888 .el .IP \f(CWPERL_LC_ALL_CATEGORY_POSITIONS_INIT\fR 4
12889 .IX Xref "PERL_LC_ALL_CATEGORY_POSITIONS_INIT"
12890 .IX Item "PERL_LC_ALL_CATEGORY_POSITIONS_INIT"
12891 This symbol, when defined, gives the C initializer for an array whose
12892 element [0] is the first category in the string returned by
12893 \&\f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR when not all categories are the same, on
12894 systems that use a positional notation. After element [0] is
12895 \&\f(CW\*(C`LC_ALL_SEPARATOR\*(C'\fR, then the category given by element [1] and so on.
12896 .ie n .IP """PERL_LC_ALL_SEPARATOR""" 4
12897 .el .IP \f(CWPERL_LC_ALL_SEPARATOR\fR 4
12898 .IX Xref "PERL_LC_ALL_SEPARATOR"
12899 .IX Item "PERL_LC_ALL_SEPARATOR"
12900 This symbol, if defined, gives the string returned by
12901 \&\f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR to separate categories that are in different
12902 locales on systems that use a positional notation as opposed to
12903 \&'name=value' pairs. An example on some platforms could be the '/' in
12904 "C/\f(CW\*(C`de_DE\*(C'\fR/C/\f(CW\*(C`en_UK\*(C'\fR/C/C"
12905 .ie n .IP """PERL_LC_ALL_USES_NAME_VALUE_PAIRS""" 4
12906 .el .IP \f(CWPERL_LC_ALL_USES_NAME_VALUE_PAIRS\fR 4
12907 .IX Xref "PERL_LC_ALL_USES_NAME_VALUE_PAIRS"
12908 .IX Item "PERL_LC_ALL_USES_NAME_VALUE_PAIRS"
12909 This symbol, if defined, indicates to the C program that the string
12910 returned by \f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR uses 'name=value;' pairs to
12911 indicate what each category's locale is when they aren't all set to the
12912 same locale. For example, "\f(CW\*(C`LC_NUMERIC\*(C'\fR=C;\f(CW\*(C`LC_CTYPE\*(C'\fR=\f(CW\*(C`de_DE\*(C'\fR;..."
12913 When not defined, the system uses positional notation.
12914 .ie n .IP """Perl_localeconv""" 4
12915 .el .IP \f(CWPerl_localeconv\fR 4
12916 .IX Xref "Perl_localeconv"
12917 .IX Item "Perl_localeconv"
12918 This is a thread-safe version of the libc \fBlocaleconv\fR\|(3). It is the same as
12919 POSIX::localeconv (returning a hash of the \f(CWlocaleconv()\fR
12920 fields), but directly callable from XS code. The hash is mortalized, so must
12921 be dealt with immediately.
12922 .RS 4
12923 .Sp
12924 .Vb 1
12925 \& HV * Perl_localeconv(pTHX)
12926 .Ve
12927 .RE
12928 .RS 4
12929 .RE
12930 .ie n .IP """Perl_setlocale""" 4
12931 .el .IP \f(CWPerl_setlocale\fR 4
12932 .IX Xref "Perl_setlocale"
12933 .IX Item "Perl_setlocale"
12934 This is an (almost) drop-in replacement for the system \f(CWsetlocale(3)\fR,
12935 taking the same parameters, and returning the same information, except that it
12936 returns the correct underlying \f(CW\*(C`LC_NUMERIC\*(C'\fR locale. Regular \f(CW\*(C`setlocale\*(C'\fR will
12937 instead return \f(CW\*(C`C\*(C'\fR if the underlying locale has a non-dot decimal point
12938 character, or a non-empty thousands separator for displaying floating point
12939 numbers. This is because perl keeps that locale category such that it has a
12940 dot and empty separator, changing the locale briefly during the operations
12941 where the underlying one is required. \f(CW\*(C`Perl_setlocale\*(C'\fR knows about this, and
12942 compensates; regular \f(CW\*(C`setlocale\*(C'\fR doesn't.
12943 .Sp
12944 Another reason it isn't completely a drop-in replacement is that it is
12945 declared to return \f(CW\*(C`const\ char\ *\*(C'\fR, whereas the system setlocale omits the
12946 \&\f(CW\*(C`const\*(C'\fR (presumably because its API was specified long ago, and can't be
12947 updated; it is illegal to change the information \f(CW\*(C`setlocale\*(C'\fR returns; doing
12948 so leads to segfaults.)
12949 .Sp
12950 Finally, \f(CW\*(C`Perl_setlocale\*(C'\fR works under all circumstances, whereas plain
12951 \&\f(CW\*(C`setlocale\*(C'\fR can be completely ineffective on some platforms under some
12952 configurations.
12953 .Sp
12954 Changing the locale is not a good idea when more than one thread is running,
12955 except on systems where the predefined variable \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR is
12956 non-zero. This is because on such systems the locale is global to the whole
12957 process and not local to just the thread calling the function. So changing it
12958 in one thread instantaneously changes it in all. On some such systems, the
12959 system \f(CWsetlocale()\fR is ineffective, returning the wrong information, and
12960 failing to actually change the locale. z/OS refuses to try to change the
12961 locale once a second thread is created. \f(CW\*(C`Perl_setlocale\*(C'\fR, should give you
12962 accurate results of what actually happened on these problematic platforms,
12963 returning NULL if the system forbade the locale change.
12964 .Sp
12965 The return points to a per-thread static buffer, which is overwritten the next
12966 time \f(CW\*(C`Perl_setlocale\*(C'\fR is called from the same thread.
12967 .RS 4
12968 .Sp
12969 .Vb 2
12970 \& const char * Perl_setlocale(const int category,
12971 \& const char *locale)
12972 .Ve
12973 .RE
12974 .RS 4
12975 .RE
12976 .ie n .IP """RESTORE_LC_NUMERIC""" 4
12977 .el .IP \f(CWRESTORE_LC_NUMERIC\fR 4
12978 .IX Xref "RESTORE_LC_NUMERIC"
12979 .IX Item "RESTORE_LC_NUMERIC"
12980 This is used in conjunction with one of the macros
12981 "STORE_LC_NUMERIC_SET_TO_NEEDED"
12982 and "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
12983 \&\f(CW\*(C`LC_NUMERIC\*(C'\fR state.
12984 .Sp
12985 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
12986 declare at compile time a private variable used by this macro and the two
12987 \&\f(CW\*(C`STORE\*(C'\fR ones. This macro should be called as a single statement, not an
12988 expression, but with an empty argument list, like this:
12989 .Sp
12990 .Vb 6
12991 \& {
12992 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
12993 \& ...
12994 \& RESTORE_LC_NUMERIC();
12995 \& ...
12996 \& }
12997 .Ve
12998 .RS 4
12999 .Sp
13000 .Vb 1
13001 \& void RESTORE_LC_NUMERIC()
13002 .Ve
13003 .RE
13004 .RS 4
13005 .RE
13006 .ie n .IP """SETLOCALE_ACCEPTS_ANY_LOCALE_NAME""" 4
13007 .el .IP \f(CWSETLOCALE_ACCEPTS_ANY_LOCALE_NAME\fR 4
13008 .IX Xref "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
13009 .IX Item "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
13010 This symbol, if defined, indicates that the setlocale routine is
13011 available and it accepts any input locale name as valid.
13012 .ie n .IP """STORE_LC_NUMERIC_FORCE_TO_UNDERLYING""" 4
13013 .el .IP \f(CWSTORE_LC_NUMERIC_FORCE_TO_UNDERLYING\fR 4
13014 .IX Xref "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
13015 .IX Item "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
13016 This is used by XS code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale-aware to force the
13017 locale for category \f(CW\*(C`LC_NUMERIC\*(C'\fR to be what perl thinks is the current
13018 underlying locale. (The perl interpreter could be wrong about what the
13019 underlying locale actually is if some C or XS code has called the C library
13020 function \fBsetlocale\fR\|(3) behind its back; calling "sync_locale" before calling
13021 this macro will update perl's records.)
13022 .Sp
13023 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
13024 declare at compile time a private variable used by this macro. This macro
13025 should be called as a single statement, not an expression, but with an empty
13026 argument list, like this:
13027 .Sp
13028 .Vb 8
13029 \& {
13030 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
13031 \& ...
13032 \& STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
13033 \& ...
13034 \& RESTORE_LC_NUMERIC();
13035 \& ...
13036 \& }
13037 .Ve
13038 .Sp
13039 The private variable is used to save the current locale state, so
13040 that the requisite matching call to "RESTORE_LC_NUMERIC" can restore it.
13041 .Sp
13042 On threaded perls not operating with thread-safe functionality, this macro uses
13043 a mutex to force a critical section. Therefore the matching RESTORE should be
13044 close by, and guaranteed to be called.
13045 .RS 4
13046 .Sp
13047 .Vb 1
13048 \& void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
13049 .Ve
13050 .RE
13051 .RS 4
13052 .RE
13053 .ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED""" 4
13054 .el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED\fR 4
13055 .IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED"
13056 .IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED"
13057 This is used to help wrap XS or C code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale-aware.
13058 This locale category is generally kept set to a locale where the decimal radix
13059 character is a dot, and the separator between groups of digits is empty. This
13060 is because most XS code that reads floating point numbers is expecting them to
13061 have this syntax.
13062 .Sp
13063 This macro makes sure the current \f(CW\*(C`LC_NUMERIC\*(C'\fR state is set properly, to be
13064 aware of locale if the call to the XS or C code from the Perl program is
13065 from within the scope of a \f(CW\*(C`use\ locale\*(C'\fR; or to ignore locale if the call is
13066 instead from outside such scope.
13067 .Sp
13068 This macro is the start of wrapping the C or XS code; the wrap ending is done
13069 by calling the "RESTORE_LC_NUMERIC" macro after the operation. Otherwise
13070 the state can be changed that will adversely affect other XS code.
13071 .Sp
13072 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
13073 declare at compile time a private variable used by this macro. This macro
13074 should be called as a single statement, not an expression, but with an empty
13075 argument list, like this:
13076 .Sp
13077 .Vb 8
13078 \& {
13079 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
13080 \& ...
13081 \& STORE_LC_NUMERIC_SET_TO_NEEDED();
13082 \& ...
13083 \& RESTORE_LC_NUMERIC();
13084 \& ...
13085 \& }
13086 .Ve
13087 .Sp
13088 On threaded perls not operating with thread-safe functionality, this macro uses
13089 a mutex to force a critical section. Therefore the matching RESTORE should be
13090 close by, and guaranteed to be called; see "WITH_LC_NUMERIC_SET_TO_NEEDED"
13091 for a more contained way to ensure that.
13092 .RS 4
13093 .Sp
13094 .Vb 1
13095 \& void STORE_LC_NUMERIC_SET_TO_NEEDED()
13096 .Ve
13097 .RE
13098 .RS 4
13099 .RE
13100 .ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED_IN""" 4
13101 .el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4
13102 .IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
13103 .IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
13104 Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
13105 as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller's
13106 responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR
13107 cannot have changed since the precalculation.
13108 .RS 4
13109 .Sp
13110 .Vb 1
13111 \& void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
13112 .Ve
13113 .RE
13114 .RS 4
13115 .RE
13116 .ie n .IP """sv_langinfo""" 4
13117 .el .IP \f(CWsv_langinfo\fR 4
13118 .IX Xref "sv_langinfo"
13119 .IX Item "sv_langinfo"
13120 This is the preferred interface for accessing the data that \fBnl_langinfo\fR\|(3)
13121 provides (or Perl's emulation of it on platforms lacking it), returning an SV.
13122 Unlike, the earlier-defined interfaces to this ("Perl_langinfo" and
13123 "Perl_langinfo8"), which return strings, the UTF8ness of the result is
13124 automatically handled for you. And like them, it is thread-safe and
13125 automatically handles getting the proper values for the \f(CW\*(C`RADIXCHAR\*(C'\fR and
13126 \&\f(CW\*(C`THOUSEP\*(C'\fR items (that calling the plain libc \f(CWnl_langinfo()\fR could give the
13127 wrong results for). Like them, this also doesn't play well with the libc
13128 \&\f(CWlocaleconv()\fR; use \f(CWPOSIX::localeconv()\fR instead.
13129 .Sp
13130 There are a few deviations from what a native \f(CWnl_langinfo()\fR would return and
13131 what this returns on platforms that don't implement that function. These are
13132 detailed in I18N::Langinfo.
13133 .RS 4
13134 .Sp
13135 .Vb 1
13136 \& SV * sv_langinfo(const nl_item item)
13137 .Ve
13138 .RE
13139 .RS 4
13140 .RE
13141 .ie n .IP """switch_to_global_locale""" 4
13142 .el .IP \f(CWswitch_to_global_locale\fR 4
13143 .IX Xref "switch_to_global_locale"
13144 .IX Item "switch_to_global_locale"
13145 This function copies the locale state of the calling thread into the program's
13146 global locale, and converts the thread to use that global locale.
13147 .Sp
13148 It is intended so that Perl can safely be used with C libraries that access the
13149 global locale and which can't be converted to not access it. Effectively, this
13150 means libraries that call \f(CWsetlocale(3)\fR on non-Windows systems. (For
13151 portability, it is a good idea to use it on Windows as well.)
13152 .Sp
13153 A downside of using it is that it disables the services that Perl provides to
13154 hide locale gotchas from your code. The service you most likely will miss
13155 regards the radix character (decimal point) in floating point numbers. Code
13156 executed after this function is called can no longer just assume that this
13157 character is correct for the current circumstances.
13158 .Sp
13159 To return to Perl control, and restart the gotcha prevention services, call
13160 \&\f(CW"sync_locale"\fR. Behavior is undefined for any pure Perl code that executes
13161 while the switch is in effect.
13162 .Sp
13163 The global locale and the per-thread locales are independent. As long as just
13164 one thread converts to the global locale, everything works smoothly. But if
13165 more than one does, they can easily interfere with each other, and races are
13166 likely. On Windows systems prior to Visual Studio 15 (at which point Microsoft
13167 fixed a bug), races can occur (even if only one thread has been converted to
13168 the global locale), but only if you use the following operations:
13169 .RS 4
13170 .IP POSIX::localeconv 4
13171 .IX Item "POSIX::localeconv"
13172 .PD 0
13173 .ie n .IP "I18N::Langinfo, items ""CRNCYSTR"" and ""THOUSEP""" 4
13174 .el .IP "I18N::Langinfo, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4
13175 .IX Item "I18N::Langinfo, items CRNCYSTR and THOUSEP"
13176 .ie n .IP """sv_langinfo"" in perlapi, items ""CRNCYSTR"" and ""THOUSEP""" 4
13177 .el .IP """sv_langinfo"" in perlapi, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4
13178 .IX Item """sv_langinfo"" in perlapi, items CRNCYSTR and THOUSEP"
13179 .RE
13180 .RS 4
13181 .PD
13182 .Sp
13183 The first item is not fixable (except by upgrading to a later Visual Studio
13184 release), but it would be possible to work around the latter two items by
13185 having Perl change its algorithm for calculating these to use Windows API
13186 functions (likely \f(CW\*(C`GetNumberFormat\*(C'\fR and \f(CW\*(C`GetCurrencyFormat\*(C'\fR); patches
13187 welcome.
13188 .Sp
13189 XS code should never call plain \f(CW\*(C`setlocale\*(C'\fR, but should instead be converted
13190 to either call \f(CW\*(C`Perl_setlocale\*(C'\fR (which is a drop-in
13191 for the system \f(CW\*(C`setlocale\*(C'\fR) or use the methods given in perlcall to call
13192 \&\f(CW\*(C`POSIX::setlocale\*(C'\fR. Either one will transparently properly
13193 handle all cases of single\- vs multi-thread, POSIX 2008\-supported or not.
13194 .Sp
13195 .Vb 1
13196 \& void switch_to_global_locale()
13197 .Ve
13198 .RE
13199 .RS 4
13200 .RE
13201 .ie n .IP """sync_locale""" 4
13202 .el .IP \f(CWsync_locale\fR 4
13203 .IX Xref "sync_locale"
13204 .IX Item "sync_locale"
13205 This function copies the state of the program global locale into the calling
13206 thread, and converts that thread to using per-thread locales, if it wasn't
13207 already, and the platform supports them. The LC_NUMERIC locale is toggled into
13208 the standard state (using the C locale's conventions), if not within the
13209 lexical scope of \f(CW\*(C`use\ locale\*(C'\fR.
13210 .Sp
13211 Perl will now consider itself to have control of the locale.
13212 .Sp
13213 Since unthreaded perls have only a global locale, this function is a no-op
13214 without threads.
13215 .Sp
13216 This function is intended for use with C libraries that do locale manipulation.
13217 It allows Perl to accommodate the use of them. Call this function before
13218 transferring back to Perl space so that it knows what state the C code has left
13219 things in.
13220 .Sp
13221 XS code should not manipulate the locale on its own. Instead,
13222 \&\f(CW\*(C`Perl_setlocale\*(C'\fR can be used at any time to query or
13223 change the locale (though changing the locale is antisocial and dangerous on
13224 multi-threaded systems that don't have multi-thread safe locale operations.
13225 (See "Multi-threaded operation" in perllocale).
13226 .Sp
13227 Using the libc \f(CWsetlocale(3)\fR function should be avoided. Nevertheless,
13228 certain non-Perl libraries called from XS, do call it, and their behavior may
13229 not be able to be changed. This function, along with
13230 \&\f(CW"switch_to_global_locale"\fR, can be used to get seamless behavior in these
13231 circumstances, as long as only one thread is involved.
13232 .Sp
13233 If the library has an option to turn off its locale manipulation, doing that is
13234 preferable to using this mechanism. \f(CW\*(C`Gtk\*(C'\fR is such a library.
13235 .Sp
13236 The return value is a boolean: TRUE if the global locale at the time of call
13237 was in effect for the caller; and FALSE if a per-thread locale was in effect.
13238 .RS 4
13239 .Sp
13240 .Vb 1
13241 \& bool sync_locale()
13242 .Ve
13243 .RE
13244 .RS 4
13245 .RE
13246 .ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED""" 4
13247 .el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED\fR 4
13248 .IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED"
13249 .IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED"
13250 This macro invokes the supplied statement or block within the context
13251 of a "STORE_LC_NUMERIC_SET_TO_NEEDED" .. "RESTORE_LC_NUMERIC" pair
13252 if required, so eg:
13253 .Sp
13254 .Vb 3
13255 \& WITH_LC_NUMERIC_SET_TO_NEEDED(
13256 \& SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
13257 \& );
13258 .Ve
13259 .Sp
13260 is equivalent to:
13261 .Sp
13262 .Vb 10
13263 \& {
13264 \&#ifdef USE_LOCALE_NUMERIC
13265 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
13266 \& STORE_LC_NUMERIC_SET_TO_NEEDED();
13267 \&#endif
13268 \& SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
13269 \&#ifdef USE_LOCALE_NUMERIC
13270 \& RESTORE_LC_NUMERIC();
13271 \&#endif
13272 \& }
13273 .Ve
13274 .RS 4
13275 .Sp
13276 .Vb 1
13277 \& void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
13278 .Ve
13279 .RE
13280 .RS 4
13281 .RE
13282 .ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED_IN""" 4
13283 .el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4
13284 .IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
13285 .IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
13286 Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
13287 as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller's
13288 responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR
13289 cannot have changed since the precalculation.
13290 .RS 4
13291 .Sp
13292 .Vb 1
13293 \& void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
13294 .Ve
13295 .RE
13296 .RS 4
13297 .RE
13298 .SH Magic
13299 .IX Xref "MAGIC"
13300 .IX Header "Magic"
13301 "Magic" is special data attached to SV structures in order to give them
13302 "magical" properties. When any Perl code tries to read from, or assign to,
13303 an SV marked as magical, it calls the 'get' or 'set' function associated
13304 with that SV's magic. A get is called prior to reading an SV, in order to
13305 give it a chance to update its internal value (get on $. writes the line
13306 number of the last read filehandle into the SV's IV slot), while
13307 set is called after an SV has been written to, in order to allow it to make
13308 use of its changed value (set on $/ copies the SV's new value to the
13309 PL_rs global variable).
13310 .PP
13311 Magic is implemented as a linked list of MAGIC structures attached to the
13312 SV. Each MAGIC struct holds the type of the magic, a pointer to an array
13313 of functions that implement the \fBget()\fR, \fBset()\fR, \fBlength()\fR etc functions,
13314 plus space for some flags and pointers. For example, a tied variable has
13315 a MAGIC structure that contains a pointer to the object associated with the
13316 tie.
13317 .ie n .IP """mg_clear""" 4
13318 .el .IP \f(CWmg_clear\fR 4
13319 .IX Xref "mg_clear"
13320 .IX Item "mg_clear"
13321 Clear something magical that the SV represents. See \f(CW"sv_magic"\fR.
13322 .RS 4
13323 .Sp
13324 .Vb 1
13325 \& int mg_clear(SV *sv)
13326 .Ve
13327 .RE
13328 .RS 4
13329 .RE
13330 .ie n .IP """mg_copy""" 4
13331 .el .IP \f(CWmg_copy\fR 4
13332 .IX Xref "mg_copy"
13333 .IX Item "mg_copy"
13334 Copies the magic from one SV to another. See \f(CW"sv_magic"\fR.
13335 .RS 4
13336 .Sp
13337 .Vb 1
13338 \& int mg_copy(SV *sv, SV *nsv, const char *key, I32 klen)
13339 .Ve
13340 .RE
13341 .RS 4
13342 .RE
13343 .ie n .IP """MGf_COPY""" 4
13344 .el .IP \f(CWMGf_COPY\fR 4
13345 .IX Item "MGf_COPY"
13346 .PD 0
13347 .ie n .IP """MGf_DUP""" 4
13348 .el .IP \f(CWMGf_DUP\fR 4
13349 .IX Item "MGf_DUP"
13350 .ie n .IP """MGf_LOCAL""" 4
13351 .el .IP \f(CWMGf_LOCAL\fR 4
13352 .IX Item "MGf_LOCAL"
13353 .PD
13354 Described in perlguts.
13355 .ie n .IP """mg_find""" 4
13356 .el .IP \f(CWmg_find\fR 4
13357 .IX Xref "mg_find"
13358 .IX Item "mg_find"
13359 Finds the magic pointer for \f(CW\*(C`type\*(C'\fR matching the SV. See \f(CW"sv_magic"\fR.
13360 .RS 4
13361 .Sp
13362 .Vb 1
13363 \& MAGIC * mg_find(const SV *sv, int type)
13364 .Ve
13365 .RE
13366 .RS 4
13367 .RE
13368 .ie n .IP """mg_findext""" 4
13369 .el .IP \f(CWmg_findext\fR 4
13370 .IX Xref "mg_findext"
13371 .IX Item "mg_findext"
13372 Finds the magic pointer of \f(CW\*(C`type\*(C'\fR with the given \f(CW\*(C`vtbl\*(C'\fR for the \f(CW\*(C`SV\*(C'\fR. See
13373 \&\f(CW"sv_magicext"\fR.
13374 .RS 4
13375 .Sp
13376 .Vb 1
13377 \& MAGIC * mg_findext(const SV *sv, int type, const MGVTBL *vtbl)
13378 .Ve
13379 .RE
13380 .RS 4
13381 .RE
13382 .ie n .IP """mg_free""" 4
13383 .el .IP \f(CWmg_free\fR 4
13384 .IX Xref "mg_free"
13385 .IX Item "mg_free"
13386 Free any magic storage used by the SV. See \f(CW"sv_magic"\fR.
13387 .RS 4
13388 .Sp
13389 .Vb 1
13390 \& int mg_free(SV *sv)
13391 .Ve
13392 .RE
13393 .RS 4
13394 .RE
13395 .ie n .IP """mg_freeext""" 4
13396 .el .IP \f(CWmg_freeext\fR 4
13397 .IX Xref "mg_freeext"
13398 .IX Item "mg_freeext"
13399 Remove any magic of type \f(CW\*(C`how\*(C'\fR using virtual table \f(CW\*(C`vtbl\*(C'\fR from the
13400 SV \f(CW\*(C`sv\*(C'\fR. See "sv_magic".
13401 .Sp
13402 \&\f(CW\*(C`mg_freeext(sv, how, NULL)\*(C'\fR is equivalent to \f(CW\*(C`mg_free_type(sv, how)\*(C'\fR.
13403 .RS 4
13404 .Sp
13405 .Vb 1
13406 \& void mg_freeext(SV *sv, int how, const MGVTBL *vtbl)
13407 .Ve
13408 .RE
13409 .RS 4
13410 .RE
13411 .ie n .IP """mg_free_type""" 4
13412 .el .IP \f(CWmg_free_type\fR 4
13413 .IX Xref "mg_free_type"
13414 .IX Item "mg_free_type"
13415 Remove any magic of type \f(CW\*(C`how\*(C'\fR from the SV \f(CW\*(C`sv\*(C'\fR. See "sv_magic".
13416 .RS 4
13417 .Sp
13418 .Vb 1
13419 \& void mg_free_type(SV *sv, int how)
13420 .Ve
13421 .RE
13422 .RS 4
13423 .RE
13424 .ie n .IP """mg_get""" 4
13425 .el .IP \f(CWmg_get\fR 4
13426 .IX Xref "mg_get"
13427 .IX Item "mg_get"
13428 Do magic before a value is retrieved from the SV. The type of SV must
13429 be >= \f(CW\*(C`SVt_PVMG\*(C'\fR. See \f(CW"sv_magic"\fR.
13430 .RS 4
13431 .Sp
13432 .Vb 1
13433 \& int mg_get(SV *sv)
13434 .Ve
13435 .RE
13436 .RS 4
13437 .RE
13438 .ie n .IP """mg_magical""" 4
13439 .el .IP \f(CWmg_magical\fR 4
13440 .IX Xref "mg_magical"
13441 .IX Item "mg_magical"
13442 Turns on the magical status of an SV. See \f(CW"sv_magic"\fR.
13443 .RS 4
13444 .Sp
13445 .Vb 1
13446 \& void mg_magical(SV *sv)
13447 .Ve
13448 .RE
13449 .RS 4
13450 .RE
13451 .ie n .IP """mg_set""" 4
13452 .el .IP \f(CWmg_set\fR 4
13453 .IX Xref "mg_set"
13454 .IX Item "mg_set"
13455 Do magic after a value is assigned to the SV. See \f(CW"sv_magic"\fR.
13456 .RS 4
13457 .Sp
13458 .Vb 1
13459 \& int mg_set(SV *sv)
13460 .Ve
13461 .RE
13462 .RS 4
13463 .RE
13464 .ie n .IP """MGVTBL""" 4
13465 .el .IP \f(CWMGVTBL\fR 4
13466 .IX Item "MGVTBL"
13467 Described in perlguts.
13468 .ie n .IP """PERL_MAGIC_arylen""" 4
13469 .el .IP \f(CWPERL_MAGIC_arylen\fR 4
13470 .IX Item "PERL_MAGIC_arylen"
13471 .PD 0
13472 .ie n .IP """PERL_MAGIC_arylen_p""" 4
13473 .el .IP \f(CWPERL_MAGIC_arylen_p\fR 4
13474 .IX Item "PERL_MAGIC_arylen_p"
13475 .ie n .IP """PERL_MAGIC_backref""" 4
13476 .el .IP \f(CWPERL_MAGIC_backref\fR 4
13477 .IX Item "PERL_MAGIC_backref"
13478 .ie n .IP """PERL_MAGIC_bm""" 4
13479 .el .IP \f(CWPERL_MAGIC_bm\fR 4
13480 .IX Item "PERL_MAGIC_bm"
13481 .ie n .IP """PERL_MAGIC_checkcall""" 4
13482 .el .IP \f(CWPERL_MAGIC_checkcall\fR 4
13483 .IX Item "PERL_MAGIC_checkcall"
13484 .ie n .IP """PERL_MAGIC_collxfrm""" 4
13485 .el .IP \f(CWPERL_MAGIC_collxfrm\fR 4
13486 .IX Item "PERL_MAGIC_collxfrm"
13487 .ie n .IP """PERL_MAGIC_dbfile""" 4
13488 .el .IP \f(CWPERL_MAGIC_dbfile\fR 4
13489 .IX Item "PERL_MAGIC_dbfile"
13490 .ie n .IP """PERL_MAGIC_dbline""" 4
13491 .el .IP \f(CWPERL_MAGIC_dbline\fR 4
13492 .IX Item "PERL_MAGIC_dbline"
13493 .ie n .IP """PERL_MAGIC_debugvar""" 4
13494 .el .IP \f(CWPERL_MAGIC_debugvar\fR 4
13495 .IX Item "PERL_MAGIC_debugvar"
13496 .ie n .IP """PERL_MAGIC_defelem""" 4
13497 .el .IP \f(CWPERL_MAGIC_defelem\fR 4
13498 .IX Item "PERL_MAGIC_defelem"
13499 .ie n .IP """PERL_MAGIC_destruct""" 4
13500 .el .IP \f(CWPERL_MAGIC_destruct\fR 4
13501 .IX Item "PERL_MAGIC_destruct"
13502 .ie n .IP """PERL_MAGIC_env""" 4
13503 .el .IP \f(CWPERL_MAGIC_env\fR 4
13504 .IX Item "PERL_MAGIC_env"
13505 .ie n .IP """PERL_MAGIC_envelem""" 4
13506 .el .IP \f(CWPERL_MAGIC_envelem\fR 4
13507 .IX Item "PERL_MAGIC_envelem"
13508 .ie n .IP """PERL_MAGIC_ext""" 4
13509 .el .IP \f(CWPERL_MAGIC_ext\fR 4
13510 .IX Item "PERL_MAGIC_ext"
13511 .ie n .IP """PERL_MAGIC_extvalue""" 4
13512 .el .IP \f(CWPERL_MAGIC_extvalue\fR 4
13513 .IX Item "PERL_MAGIC_extvalue"
13514 .ie n .IP """PERL_MAGIC_fm""" 4
13515 .el .IP \f(CWPERL_MAGIC_fm\fR 4
13516 .IX Item "PERL_MAGIC_fm"
13517 .ie n .IP """PERL_MAGIC_hints""" 4
13518 .el .IP \f(CWPERL_MAGIC_hints\fR 4
13519 .IX Item "PERL_MAGIC_hints"
13520 .ie n .IP """PERL_MAGIC_hintselem""" 4
13521 .el .IP \f(CWPERL_MAGIC_hintselem\fR 4
13522 .IX Item "PERL_MAGIC_hintselem"
13523 .ie n .IP """PERL_MAGIC_hook""" 4
13524 .el .IP \f(CWPERL_MAGIC_hook\fR 4
13525 .IX Item "PERL_MAGIC_hook"
13526 .ie n .IP """PERL_MAGIC_hookelem""" 4
13527 .el .IP \f(CWPERL_MAGIC_hookelem\fR 4
13528 .IX Item "PERL_MAGIC_hookelem"
13529 .ie n .IP """PERL_MAGIC_isa""" 4
13530 .el .IP \f(CWPERL_MAGIC_isa\fR 4
13531 .IX Item "PERL_MAGIC_isa"
13532 .ie n .IP """PERL_MAGIC_isaelem""" 4
13533 .el .IP \f(CWPERL_MAGIC_isaelem\fR 4
13534 .IX Item "PERL_MAGIC_isaelem"
13535 .ie n .IP """PERL_MAGIC_lvref""" 4
13536 .el .IP \f(CWPERL_MAGIC_lvref\fR 4
13537 .IX Item "PERL_MAGIC_lvref"
13538 .ie n .IP """PERL_MAGIC_nkeys""" 4
13539 .el .IP \f(CWPERL_MAGIC_nkeys\fR 4
13540 .IX Item "PERL_MAGIC_nkeys"
13541 .ie n .IP """PERL_MAGIC_nonelem""" 4
13542 .el .IP \f(CWPERL_MAGIC_nonelem\fR 4
13543 .IX Item "PERL_MAGIC_nonelem"
13544 .ie n .IP """PERL_MAGIC_overload_table""" 4
13545 .el .IP \f(CWPERL_MAGIC_overload_table\fR 4
13546 .IX Item "PERL_MAGIC_overload_table"
13547 .ie n .IP """PERL_MAGIC_pos""" 4
13548 .el .IP \f(CWPERL_MAGIC_pos\fR 4
13549 .IX Item "PERL_MAGIC_pos"
13550 .ie n .IP """PERL_MAGIC_qr""" 4
13551 .el .IP \f(CWPERL_MAGIC_qr\fR 4
13552 .IX Item "PERL_MAGIC_qr"
13553 .ie n .IP """PERL_MAGIC_regdata""" 4
13554 .el .IP \f(CWPERL_MAGIC_regdata\fR 4
13555 .IX Item "PERL_MAGIC_regdata"
13556 .ie n .IP """PERL_MAGIC_regdatum""" 4
13557 .el .IP \f(CWPERL_MAGIC_regdatum\fR 4
13558 .IX Item "PERL_MAGIC_regdatum"
13559 .ie n .IP """PERL_MAGIC_regex_global""" 4
13560 .el .IP \f(CWPERL_MAGIC_regex_global\fR 4
13561 .IX Item "PERL_MAGIC_regex_global"
13562 .ie n .IP """PERL_MAGIC_rhash""" 4
13563 .el .IP \f(CWPERL_MAGIC_rhash\fR 4
13564 .IX Item "PERL_MAGIC_rhash"
13565 .ie n .IP """PERL_MAGIC_shared""" 4
13566 .el .IP \f(CWPERL_MAGIC_shared\fR 4
13567 .IX Item "PERL_MAGIC_shared"
13568 .ie n .IP """PERL_MAGIC_shared_scalar""" 4
13569 .el .IP \f(CWPERL_MAGIC_shared_scalar\fR 4
13570 .IX Item "PERL_MAGIC_shared_scalar"
13571 .ie n .IP """PERL_MAGIC_sig""" 4
13572 .el .IP \f(CWPERL_MAGIC_sig\fR 4
13573 .IX Item "PERL_MAGIC_sig"
13574 .ie n .IP """PERL_MAGIC_sigelem""" 4
13575 .el .IP \f(CWPERL_MAGIC_sigelem\fR 4
13576 .IX Item "PERL_MAGIC_sigelem"
13577 .ie n .IP """PERL_MAGIC_substr""" 4
13578 .el .IP \f(CWPERL_MAGIC_substr\fR 4
13579 .IX Item "PERL_MAGIC_substr"
13580 .ie n .IP """PERL_MAGIC_sv""" 4
13581 .el .IP \f(CWPERL_MAGIC_sv\fR 4
13582 .IX Item "PERL_MAGIC_sv"
13583 .ie n .IP """PERL_MAGIC_symtab""" 4
13584 .el .IP \f(CWPERL_MAGIC_symtab\fR 4
13585 .IX Item "PERL_MAGIC_symtab"
13586 .ie n .IP """PERL_MAGIC_taint""" 4
13587 .el .IP \f(CWPERL_MAGIC_taint\fR 4
13588 .IX Item "PERL_MAGIC_taint"
13589 .ie n .IP """PERL_MAGIC_tied""" 4
13590 .el .IP \f(CWPERL_MAGIC_tied\fR 4
13591 .IX Item "PERL_MAGIC_tied"
13592 .ie n .IP """PERL_MAGIC_tiedelem""" 4
13593 .el .IP \f(CWPERL_MAGIC_tiedelem\fR 4
13594 .IX Item "PERL_MAGIC_tiedelem"
13595 .ie n .IP """PERL_MAGIC_tiedscalar""" 4
13596 .el .IP \f(CWPERL_MAGIC_tiedscalar\fR 4
13597 .IX Item "PERL_MAGIC_tiedscalar"
13598 .ie n .IP """PERL_MAGIC_utf8""" 4
13599 .el .IP \f(CWPERL_MAGIC_utf8\fR 4
13600 .IX Item "PERL_MAGIC_utf8"
13601 .ie n .IP """PERL_MAGIC_uvar""" 4
13602 .el .IP \f(CWPERL_MAGIC_uvar\fR 4
13603 .IX Item "PERL_MAGIC_uvar"
13604 .ie n .IP """PERL_MAGIC_uvar_elem""" 4
13605 .el .IP \f(CWPERL_MAGIC_uvar_elem\fR 4
13606 .IX Item "PERL_MAGIC_uvar_elem"
13607 .ie n .IP """PERL_MAGIC_vec""" 4
13608 .el .IP \f(CWPERL_MAGIC_vec\fR 4
13609 .IX Item "PERL_MAGIC_vec"
13610 .ie n .IP """PERL_MAGIC_vstring""" 4
13611 .el .IP \f(CWPERL_MAGIC_vstring\fR 4
13612 .IX Item "PERL_MAGIC_vstring"
13613 .PD
13614 Described in perlguts.
13615 .ie n .IP """SvTIED_obj""" 4
13616 .el .IP \f(CWSvTIED_obj\fR 4
13617 .IX Item "SvTIED_obj"
13618 Described in perlinterp.
13619 .RS 4
13620 .Sp
13621 .Vb 1
13622 \& SvTIED_obj(SV *sv, MAGIC *mg)
13623 .Ve
13624 .RE
13625 .RS 4
13626 .RE
13627 .SH "Memory Management"
13628 .IX Header "Memory Management"
13629 .ie n .IP """dump_mstats""" 4
13630 .el .IP \f(CWdump_mstats\fR 4
13631 .IX Xref "dump_mstats"
13632 .IX Item "dump_mstats"
13633 When enabled by compiling with \f(CW\*(C`\-DDEBUGGING_MSTATS\*(C'\fR, print out statistics
13634 about malloc as two lines of numbers, one showing the length of the free list
13635 for each size category, the second showing the number of mallocs\ \-\ frees for
13636 each size category.
13637 .Sp
13638 \&\f(CW\*(C`s\*(C'\fR, if not NULL, is used as a phrase to include in the output, such as
13639 "after\ compilation".
13640 .RS 4
13641 .Sp
13642 .Vb 1
13643 \& void dump_mstats(const char *s)
13644 .Ve
13645 .RE
13646 .RS 4
13647 .RE
13648 .ie n .IP """HASATTRIBUTE_MALLOC""" 4
13649 .el .IP \f(CWHASATTRIBUTE_MALLOC\fR 4
13650 .IX Xref "HASATTRIBUTE_MALLOC"
13651 .IX Item "HASATTRIBUTE_MALLOC"
13652 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for malloc-style functions.
13653 .ie n .IP """HAS_MALLOC_GOOD_SIZE""" 4
13654 .el .IP \f(CWHAS_MALLOC_GOOD_SIZE\fR 4
13655 .IX Xref "HAS_MALLOC_GOOD_SIZE"
13656 .IX Item "HAS_MALLOC_GOOD_SIZE"
13657 This symbol, if defined, indicates that the \f(CW\*(C`malloc_good_size\*(C'\fR
13658 routine is available for use.
13659 .ie n .IP """HAS_MALLOC_SIZE""" 4
13660 .el .IP \f(CWHAS_MALLOC_SIZE\fR 4
13661 .IX Xref "HAS_MALLOC_SIZE"
13662 .IX Item "HAS_MALLOC_SIZE"
13663 This symbol, if defined, indicates that the \f(CW\*(C`malloc_size\*(C'\fR
13664 routine is available for use.
13665 .ie n .IP """I_MALLOCMALLOC""" 4
13666 .el .IP \f(CWI_MALLOCMALLOC\fR 4
13667 .IX Xref "I_MALLOCMALLOC"
13668 .IX Item "I_MALLOCMALLOC"
13669 This symbol, if defined, indicates to the C program that it should
13670 include \fImalloc/malloc.h\fR.
13671 .RS 4
13672 .Sp
13673 .Vb 3
13674 \& #ifdef I_MALLOCMALLOC
13675 \& #include <mallocmalloc.h>
13676 \& #endif
13677 .Ve
13678 .RE
13679 .RS 4
13680 .RE
13681 .ie n .IP """MYMALLOC""" 4
13682 .el .IP \f(CWMYMALLOC\fR 4
13683 .IX Xref "MYMALLOC"
13684 .IX Item "MYMALLOC"
13685 This symbol, if defined, indicates that we're using our own malloc.
13686 .ie n .IP """Newx""" 4
13687 .el .IP \f(CWNewx\fR 4
13688 .IX Item "Newx"
13689 .PD 0
13690 .ie n .IP """safemalloc""" 4
13691 .el .IP \f(CWsafemalloc\fR 4
13692 .IX Xref "Newx safemalloc"
13693 .IX Item "safemalloc"
13694 .PD
13695 The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function.
13696 .Sp
13697 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
13698 .Sp
13699 In 5.9.3, \fBNewx()\fR and friends replace the older \fBNew()\fR API, and drops
13700 the first parameter, \fIx\fR, a debug aid which allowed callers to identify
13701 themselves. This aid has been superseded by a new build option,
13702 PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips). The older API is still
13703 there for use in XS modules supporting older perls.
13704 .RS 4
13705 .Sp
13706 .Vb 2
13707 \& void Newx (void* ptr, int nitems, type)
13708 \& void* safemalloc(size_t size)
13709 .Ve
13710 .RE
13711 .RS 4
13712 .RE
13713 .ie n .IP """Newxc""" 4
13714 .el .IP \f(CWNewxc\fR 4
13715 .IX Xref "Newxc"
13716 .IX Item "Newxc"
13717 The XSUB-writer's interface to the C \f(CW\*(C`malloc\*(C'\fR function, with
13718 cast. See also \f(CW"Newx"\fR.
13719 .Sp
13720 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
13721 .RS 4
13722 .Sp
13723 .Vb 1
13724 \& void Newxc(void* ptr, int nitems, type, cast)
13725 .Ve
13726 .RE
13727 .RS 4
13728 .RE
13729 .ie n .IP """Newxz""" 4
13730 .el .IP \f(CWNewxz\fR 4
13731 .IX Item "Newxz"
13732 .PD 0
13733 .ie n .IP """safecalloc""" 4
13734 .el .IP \f(CWsafecalloc\fR 4
13735 .IX Xref "Newxz safecalloc"
13736 .IX Item "safecalloc"
13737 .PD
13738 The XSUB-writer's interface to the C \f(CW\*(C`calloc\*(C'\fR function. The allocated
13739 memory is zeroed with \f(CW\*(C`memzero\*(C'\fR. See also \f(CW"Newx"\fR.
13740 .Sp
13741 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
13742 .RS 4
13743 .Sp
13744 .Vb 2
13745 \& void Newxz (void* ptr, int nitems, type)
13746 \& void* safecalloc(size_t nitems, size_t item_size)
13747 .Ve
13748 .RE
13749 .RS 4
13750 .RE
13751 .ie n .IP """PERL_MALLOC_WRAP""" 4
13752 .el .IP \f(CWPERL_MALLOC_WRAP\fR 4
13753 .IX Xref "PERL_MALLOC_WRAP"
13754 .IX Item "PERL_MALLOC_WRAP"
13755 This symbol, if defined, indicates that we'd like malloc wrap checks.
13756 .ie n .IP """Renew""" 4
13757 .el .IP \f(CWRenew\fR 4
13758 .IX Item "Renew"
13759 .PD 0
13760 .ie n .IP """saferealloc""" 4
13761 .el .IP \f(CWsaferealloc\fR 4
13762 .IX Xref "Renew saferealloc"
13763 .IX Item "saferealloc"
13764 .PD
13765 The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function.
13766 .Sp
13767 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
13768 .RS 4
13769 .Sp
13770 .Vb 2
13771 \& void Renew (void* ptr, int nitems, type)
13772 \& void* saferealloc(void *ptr, size_t size)
13773 .Ve
13774 .RE
13775 .RS 4
13776 .RE
13777 .ie n .IP """Renewc""" 4
13778 .el .IP \f(CWRenewc\fR 4
13779 .IX Xref "Renewc"
13780 .IX Item "Renewc"
13781 The XSUB-writer's interface to the C \f(CW\*(C`realloc\*(C'\fR function, with
13782 cast.
13783 .Sp
13784 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
13785 .RS 4
13786 .Sp
13787 .Vb 1
13788 \& void Renewc(void* ptr, int nitems, type, cast)
13789 .Ve
13790 .RE
13791 .RS 4
13792 .RE
13793 .ie n .IP """Safefree""" 4
13794 .el .IP \f(CWSafefree\fR 4
13795 .IX Xref "Safefree"
13796 .IX Item "Safefree"
13797 The XSUB-writer's interface to the C \f(CW\*(C`free\*(C'\fR function.
13798 .Sp
13799 This should \fBONLY\fR be used on memory obtained using "Newx" and friends.
13800 .RS 4
13801 .Sp
13802 .Vb 1
13803 \& void Safefree(void* ptr)
13804 .Ve
13805 .RE
13806 .RS 4
13807 .RE
13808 .ie n .IP """safesyscalloc""" 4
13809 .el .IP \f(CWsafesyscalloc\fR 4
13810 .IX Xref "safesyscalloc"
13811 .IX Item "safesyscalloc"
13812 Safe version of system's \fBcalloc()\fR
13813 .RS 4
13814 .Sp
13815 .Vb 1
13816 \& Malloc_t safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
13817 .Ve
13818 .RE
13819 .RS 4
13820 .RE
13821 .ie n .IP """safesysfree""" 4
13822 .el .IP \f(CWsafesysfree\fR 4
13823 .IX Xref "safesysfree"
13824 .IX Item "safesysfree"
13825 Safe version of system's \fBfree()\fR
13826 .RS 4
13827 .Sp
13828 .Vb 1
13829 \& Free_t safesysfree(Malloc_t where)
13830 .Ve
13831 .RE
13832 .RS 4
13833 .RE
13834 .ie n .IP """safesysmalloc""" 4
13835 .el .IP \f(CWsafesysmalloc\fR 4
13836 .IX Xref "safesysmalloc"
13837 .IX Item "safesysmalloc"
13838 Paranoid version of system's \fBmalloc()\fR
13839 .RS 4
13840 .Sp
13841 .Vb 1
13842 \& Malloc_t safesysmalloc(MEM_SIZE nbytes)
13843 .Ve
13844 .RE
13845 .RS 4
13846 .RE
13847 .ie n .IP """safesysrealloc""" 4
13848 .el .IP \f(CWsafesysrealloc\fR 4
13849 .IX Xref "safesysrealloc"
13850 .IX Item "safesysrealloc"
13851 Paranoid version of system's \fBrealloc()\fR
13852 .RS 4
13853 .Sp
13854 .Vb 1
13855 \& Malloc_t safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
13856 .Ve
13857 .RE
13858 .RS 4
13859 .RE
13860 .SH MRO
13861 .IX Header "MRO"
13862 These functions are related to the method resolution order of perl classes
13863 Also see perlmroapi.
13864 .ie n .IP """HvMROMETA""" 4
13865 .el .IP \f(CWHvMROMETA\fR 4
13866 .IX Item "HvMROMETA"
13867 Described in perlmroapi.
13868 .RS 4
13869 .Sp
13870 .Vb 1
13871 \& struct mro_meta * HvMROMETA(HV *hv)
13872 .Ve
13873 .RE
13874 .RS 4
13875 .RE
13876 .ie n .IP """mro_get_from_name""" 4
13877 .el .IP \f(CWmro_get_from_name\fR 4
13878 .IX Xref "mro_get_from_name"
13879 .IX Item "mro_get_from_name"
13880 Returns the previously registered mro with the given \f(CW\*(C`name\*(C'\fR, or NULL if not
13881 registered. See "\f(CW\*(C`mro_register\*(C'\fR".
13882 .Sp
13883 NOTE: \f(CW\*(C`mro_get_from_name\*(C'\fR must be explicitly called as
13884 \&\f(CW\*(C`Perl_mro_get_from_name\*(C'\fR
13885 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
13886 .RS 4
13887 .Sp
13888 .Vb 1
13889 \& const struct mro_alg * Perl_mro_get_from_name(pTHX_ SV *name)
13890 .Ve
13891 .RE
13892 .RS 4
13893 .RE
13894 .ie n .IP """mro_get_linear_isa""" 4
13895 .el .IP \f(CWmro_get_linear_isa\fR 4
13896 .IX Xref "mro_get_linear_isa"
13897 .IX Item "mro_get_linear_isa"
13898 Returns the mro linearisation for the given stash. By default, this
13899 will be whatever \f(CW\*(C`mro_get_linear_isa_dfs\*(C'\fR returns unless some
13900 other MRO is in effect for the stash. The return value is a
13901 read-only AV* whose values are string SVs giving class names.
13902 .Sp
13903 You are responsible for \f(CWSvREFCNT_inc()\fR on the
13904 return value if you plan to store it anywhere
13905 semi-permanently (otherwise it might be deleted
13906 out from under you the next time the cache is
13907 invalidated).
13908 .RS 4
13909 .Sp
13910 .Vb 1
13911 \& AV * mro_get_linear_isa(HV *stash)
13912 .Ve
13913 .RE
13914 .RS 4
13915 .RE
13916 .ie n .IP """MRO_GET_PRIVATE_DATA""" 4
13917 .el .IP \f(CWMRO_GET_PRIVATE_DATA\fR 4
13918 .IX Item "MRO_GET_PRIVATE_DATA"
13919 Described in perlmroapi.
13920 .RS 4
13921 .Sp
13922 .Vb 2
13923 \& SV* MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
13924 \& const struct mro_alg *const which)
13925 .Ve
13926 .RE
13927 .RS 4
13928 .RE
13929 .ie n .IP """mro_method_changed_in""" 4
13930 .el .IP \f(CWmro_method_changed_in\fR 4
13931 .IX Xref "mro_method_changed_in"
13932 .IX Item "mro_method_changed_in"
13933 Invalidates method caching on any child classes
13934 of the given stash, so that they might notice
13935 the changes in this one.
13936 .Sp
13937 Ideally, all instances of \f(CW\*(C`PL_sub_generation++\*(C'\fR in
13938 perl source outside of \fImro.c\fR should be
13939 replaced by calls to this.
13940 .Sp
13941 Perl automatically handles most of the common
13942 ways a method might be redefined. However, there
13943 are a few ways you could change a method in a stash
13944 without the cache code noticing, in which case you
13945 need to call this method afterwards:
13946 .Sp
13947 1) Directly manipulating the stash HV entries from
13948 XS code.
13949 .Sp
13950 2) Assigning a reference to a readonly scalar
13951 constant into a stash entry in order to create
13952 a constant subroutine (like \fIconstant.pm\fR
13953 does).
13954 .Sp
13955 This same method is available from pure perl
13956 via, \f(CWmro::method_changed_in(classname)\fR.
13957 .RS 4
13958 .Sp
13959 .Vb 1
13960 \& void mro_method_changed_in(HV *stash)
13961 .Ve
13962 .RE
13963 .RS 4
13964 .RE
13965 .ie n .IP """mro_register""" 4
13966 .el .IP \f(CWmro_register\fR 4
13967 .IX Xref "mro_register"
13968 .IX Item "mro_register"
13969 Registers a custom mro plugin. See perlmroapi for details on this and other
13970 mro functions.
13971 .Sp
13972 NOTE: \f(CW\*(C`mro_register\*(C'\fR must be explicitly called as
13973 \&\f(CW\*(C`Perl_mro_register\*(C'\fR
13974 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
13975 .RS 4
13976 .Sp
13977 .Vb 1
13978 \& void Perl_mro_register(pTHX_ const struct mro_alg *mro)
13979 .Ve
13980 .RE
13981 .RS 4
13982 .RE
13983 .ie n .IP """mro_set_mro""" 4
13984 .el .IP \f(CWmro_set_mro\fR 4
13985 .IX Xref "mro_set_mro"
13986 .IX Item "mro_set_mro"
13987 Set \f(CW\*(C`meta\*(C'\fR to the value contained in the registered mro plugin whose name is
13988 \&\f(CW\*(C`name\*(C'\fR.
13989 .Sp
13990 Croaks if \f(CW\*(C`name\*(C'\fR hasn't been registered
13991 .Sp
13992 NOTE: \f(CW\*(C`mro_set_mro\*(C'\fR must be explicitly called as
13993 \&\f(CW\*(C`Perl_mro_set_mro\*(C'\fR
13994 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
13995 .RS 4
13996 .Sp
13997 .Vb 2
13998 \& void Perl_mro_set_mro(pTHX_ struct mro_meta * const meta,
13999 \& SV * const name)
14000 .Ve
14001 .RE
14002 .RS 4
14003 .RE
14004 .ie n .IP """mro_set_private_data""" 4
14005 .el .IP \f(CWmro_set_private_data\fR 4
14006 .IX Item "mro_set_private_data"
14007 Described in perlmroapi.
14008 .Sp
14009 NOTE: \f(CW\*(C`mro_set_private_data\*(C'\fR must be explicitly called as
14010 \&\f(CW\*(C`Perl_mro_set_private_data\*(C'\fR
14011 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
14012 .RS 4
14013 .Sp
14014 .Vb 4
14015 \& SV * Perl_mro_set_private_data(pTHX_
14016 \& struct mro_meta * const smeta,
14017 \& const struct mro_alg * const which,
14018 \& SV * const data)
14019 .Ve
14020 .RE
14021 .RS 4
14022 .RE
14023 .SH "Multicall Functions"
14024 .IX Header "Multicall Functions"
14025 .ie n .IP """dMULTICALL""" 4
14026 .el .IP \f(CWdMULTICALL\fR 4
14027 .IX Xref "dMULTICALL"
14028 .IX Item "dMULTICALL"
14029 Declare local variables for a multicall. See "LIGHTWEIGHT CALLBACKS" in perlcall.
14030 .RS 4
14031 .Sp
14032 .Vb 1
14033 \& dMULTICALL;
14034 .Ve
14035 .RE
14036 .RS 4
14037 .RE
14038 .ie n .IP """MULTICALL""" 4
14039 .el .IP \f(CWMULTICALL\fR 4
14040 .IX Xref "MULTICALL"
14041 .IX Item "MULTICALL"
14042 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in perlcall.
14043 .RS 4
14044 .Sp
14045 .Vb 1
14046 \& MULTICALL;
14047 .Ve
14048 .RE
14049 .RS 4
14050 .RE
14051 .ie n .IP """POP_MULTICALL""" 4
14052 .el .IP \f(CWPOP_MULTICALL\fR 4
14053 .IX Xref "POP_MULTICALL"
14054 .IX Item "POP_MULTICALL"
14055 Closing bracket for a lightweight callback.
14056 See "LIGHTWEIGHT CALLBACKS" in perlcall.
14057 .RS 4
14058 .Sp
14059 .Vb 1
14060 \& POP_MULTICALL;
14061 .Ve
14062 .RE
14063 .RS 4
14064 .RE
14065 .ie n .IP """PUSH_MULTICALL""" 4
14066 .el .IP \f(CWPUSH_MULTICALL\fR 4
14067 .IX Xref "PUSH_MULTICALL"
14068 .IX Item "PUSH_MULTICALL"
14069 Opening bracket for a lightweight callback.
14070 See "LIGHTWEIGHT CALLBACKS" in perlcall.
14071 .RS 4
14072 .Sp
14073 .Vb 1
14074 \& PUSH_MULTICALL(CV* the_cv);
14075 .Ve
14076 .RE
14077 .RS 4
14078 .RE
14079 .SH "Numeric Functions"
14080 .IX Xref "IS_NUMBER_GREATER_THAN_UV_MAX IS_NUMBER_INFINITY IS_NUMBER_IN_UV IS_NUMBER_NAN IS_NUMBER_NEG IS_NUMBER_NOT_INT PERL_SCAN_ALLOW_UNDERSCORES PERL_SCAN_DISALLOW_PREFIX PERL_SCAN_GREATER_THAN_UV_MAX PERL_SCAN_SILENT_ILLDIGIT PERL_SCAN_TRAILING"
14081 .IX Header "Numeric Functions"
14082 .ie n .IP """Atol""" 4
14083 .el .IP \f(CWAtol\fR 4
14084 .IX Item "Atol"
14085 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Atol\*(C'\fR
14086 from a future release of Perl. Do not use it for
14087 new code; remove it from existing code.
14088 .Sp
14089 Described in perlhacktips.
14090 .RS 4
14091 .Sp
14092 .Vb 1
14093 \& Atol(const char * nptr)
14094 .Ve
14095 .RE
14096 .RS 4
14097 .RE
14098 .ie n .IP """Atoul""" 4
14099 .el .IP \f(CWAtoul\fR 4
14100 .IX Item "Atoul"
14101 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Atoul\*(C'\fR
14102 from a future release of Perl. Do not use it for
14103 new code; remove it from existing code.
14104 .Sp
14105 Described in perlhacktips.
14106 .RS 4
14107 .Sp
14108 .Vb 1
14109 \& Atoul(const char * nptr)
14110 .Ve
14111 .RE
14112 .RS 4
14113 .RE
14114 .ie n .IP """Drand01""" 4
14115 .el .IP \f(CWDrand01\fR 4
14116 .IX Xref "Drand01"
14117 .IX Item "Drand01"
14118 This macro is to be used to generate uniformly distributed
14119 random numbers over the range [0., 1.[. You may have to supply
14120 an 'extern double \f(CWdrand48()\fR;' in your program since SunOS 4.1.3
14121 doesn't provide you with anything relevant in its headers.
14122 See \f(CW"HAS_DRAND48_PROTO"\fR.
14123 .RS 4
14124 .Sp
14125 .Vb 1
14126 \& double Drand01()
14127 .Ve
14128 .RE
14129 .RS 4
14130 .RE
14131 .ie n .IP """Gconvert""" 4
14132 .el .IP \f(CWGconvert\fR 4
14133 .IX Xref "Gconvert"
14134 .IX Item "Gconvert"
14135 This preprocessor macro is defined to convert a floating point
14136 number to a string without a trailing decimal point. This
14137 emulates the behavior of \f(CWsprintf("%g")\fR, but is sometimes much more
14138 efficient. If \f(CWgconvert()\fR is not available, but \f(CWgcvt()\fR drops the
14139 trailing decimal point, then \f(CWgcvt()\fR is used. If all else fails,
14140 a macro using \f(CWsprintf("%g")\fR is used. Arguments for the Gconvert
14141 macro are: value, number of digits, whether trailing zeros should
14142 be retained, and the output buffer.
14143 The usual values are:
14144 .Sp
14145 .Vb 3
14146 \& d_Gconvert=\*(Aqgconvert((x),(n),(t),(b))\*(Aq
14147 \& d_Gconvert=\*(Aqgcvt((x),(n),(b))\*(Aq
14148 \& d_Gconvert=\*(Aqsprintf((b),"%.*g",(n),(x))\*(Aq
14149 .Ve
14150 .Sp
14151 The last two assume trailing zeros should not be kept.
14152 .RS 4
14153 .Sp
14154 .Vb 1
14155 \& char * Gconvert(double x, Size_t n, bool t, char * b)
14156 .Ve
14157 .RE
14158 .RS 4
14159 .RE
14160 .ie n .IP """grok_atoUV""" 4
14161 .el .IP \f(CWgrok_atoUV\fR 4
14162 .IX Xref "grok_atoUV"
14163 .IX Item "grok_atoUV"
14164 parse a string, looking for a decimal unsigned integer.
14165 .Sp
14166 On entry, \f(CW\*(C`pv\*(C'\fR points to the beginning of the string;
14167 \&\f(CW\*(C`valptr\*(C'\fR points to a UV that will receive the converted value, if found;
14168 \&\f(CW\*(C`endptr\*(C'\fR is either NULL or points to a variable that points to one byte
14169 beyond the point in \f(CW\*(C`pv\*(C'\fR that this routine should examine.
14170 If \f(CW\*(C`endptr\*(C'\fR is NULL, \f(CW\*(C`pv\*(C'\fR is assumed to be NUL-terminated.
14171 .Sp
14172 Returns FALSE if \f(CW\*(C`pv\*(C'\fR doesn't represent a valid unsigned integer value (with
14173 no leading zeros). Otherwise it returns TRUE, and sets \f(CW*valptr\fR to that
14174 value.
14175 .Sp
14176 If you constrain the portion of \f(CW\*(C`pv\*(C'\fR that is looked at by this function (by
14177 passing a non-NULL \f(CW\*(C`endptr\*(C'\fR), and if the initial bytes of that portion form a
14178 valid value, it will return TRUE, setting \f(CW*endptr\fR to the byte following the
14179 final digit of the value. But if there is no constraint at what's looked at,
14180 all of \f(CW\*(C`pv\*(C'\fR must be valid in order for TRUE to be returned. \f(CW*endptr\fR is
14181 unchanged from its value on input if FALSE is returned;
14182 .Sp
14183 The only characters this accepts are the decimal digits '0'..'9'.
14184 .Sp
14185 As opposed to \fBatoi\fR\|(3) or \fBstrtol\fR\|(3), \f(CW\*(C`grok_atoUV\*(C'\fR does NOT allow optional
14186 leading whitespace, nor negative inputs. If such features are required, the
14187 calling code needs to explicitly implement those.
14188 .Sp
14189 Note that this function returns FALSE for inputs that would overflow a UV,
14190 or have leading zeros. Thus a single \f(CW0\fR is accepted, but not \f(CW00\fR nor
14191 \&\f(CW01\fR, \f(CW002\fR, \fIetc\fR.
14192 .Sp
14193 Background: \f(CW\*(C`atoi\*(C'\fR has severe problems with illegal inputs, it cannot be
14194 used for incremental parsing, and therefore should be avoided
14195 \&\f(CW\*(C`atoi\*(C'\fR and \f(CW\*(C`strtol\*(C'\fR are also affected by locale settings, which can also be
14196 seen as a bug (global state controlled by user environment).
14197 .RS 4
14198 .Sp
14199 .Vb 1
14200 \& bool grok_atoUV(const char *pv, UV *valptr, const char **endptr)
14201 .Ve
14202 .RE
14203 .RS 4
14204 .RE
14205 .ie n .IP """grok_bin""" 4
14206 .el .IP \f(CWgrok_bin\fR 4
14207 .IX Xref "grok_bin"
14208 .IX Item "grok_bin"
14209 converts a string representing a binary number to numeric form.
14210 .Sp
14211 On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
14212 conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The
14213 scan stops at the end of the string, or at just before the first invalid
14214 character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
14215 encountering an invalid character (except NUL) will also trigger a warning. On
14216 return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
14217 gives output flags.
14218 .Sp
14219 If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
14220 and nothing is written to \f(CW*result\fR. If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_bin\*(C'\fR
14221 returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
14222 and writes an approximation of the correct value into \f(CW*result\fR (which is an
14223 NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
14224 .Sp
14225 The binary number may optionally be prefixed with \f(CW"0b"\fR or \f(CW"b"\fR unless
14226 \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry.
14227 .Sp
14228 If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
14229 digits may be separated from each other by a single underscore; also a single
14230 leading underscore is accepted.
14231 .RS 4
14232 .Sp
14233 .Vb 2
14234 \& UV grok_bin(const char *start, STRLEN *len_p, I32 *flags,
14235 \& NV *result)
14236 .Ve
14237 .RE
14238 .RS 4
14239 .RE
14240 .ie n .IP """grok_hex""" 4
14241 .el .IP \f(CWgrok_hex\fR 4
14242 .IX Xref "grok_hex"
14243 .IX Item "grok_hex"
14244 converts a string representing a hex number to numeric form.
14245 .Sp
14246 On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
14247 conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The
14248 scan stops at the end of the string, or at just before the first invalid
14249 character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
14250 encountering an invalid character (except NUL) will also trigger a warning. On
14251 return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
14252 gives output flags.
14253 .Sp
14254 If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
14255 and nothing is written to \f(CW*result\fR. If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_hex\*(C'\fR
14256 returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
14257 and writes an approximation of the correct value into \f(CW*result\fR (which is an
14258 NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
14259 .Sp
14260 The hex number may optionally be prefixed with \f(CW"0x"\fR or \f(CW"x"\fR unless
14261 \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry.
14262 .Sp
14263 If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
14264 digits may be separated from each other by a single underscore; also a single
14265 leading underscore is accepted.
14266 .RS 4
14267 .Sp
14268 .Vb 2
14269 \& UV grok_hex(const char *start, STRLEN *len_p, I32 *flags,
14270 \& NV *result)
14271 .Ve
14272 .RE
14273 .RS 4
14274 .RE
14275 .ie n .IP """grok_infnan""" 4
14276 .el .IP \f(CWgrok_infnan\fR 4
14277 .IX Xref "grok_infnan"
14278 .IX Item "grok_infnan"
14279 Helper for \f(CWgrok_number()\fR, accepts various ways of spelling "infinity"
14280 or "not a number", and returns one of the following flag combinations:
14281 .Sp
14282 .Vb 5
14283 \& IS_NUMBER_INFINITY
14284 \& IS_NUMBER_NAN
14285 \& IS_NUMBER_INFINITY | IS_NUMBER_NEG
14286 \& IS_NUMBER_NAN | IS_NUMBER_NEG
14287 \& 0
14288 .Ve
14289 .Sp
14290 possibly |\-ed with \f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR.
14291 .Sp
14292 If an infinity or a not-a-number is recognized, \f(CW*sp\fR will point to
14293 one byte past the end of the recognized string. If the recognition fails,
14294 zero is returned, and \f(CW*sp\fR will not move.
14295 .RS 4
14296 .Sp
14297 .Vb 1
14298 \& int grok_infnan(const char **sp, const char *send)
14299 .Ve
14300 .RE
14301 .RS 4
14302 .RE
14303 .ie n .IP """grok_number""" 4
14304 .el .IP \f(CWgrok_number\fR 4
14305 .IX Xref "grok_number"
14306 .IX Item "grok_number"
14307 Identical to \f(CWgrok_number_flags()\fR with \f(CW\*(C`flags\*(C'\fR set to zero.
14308 .RS 4
14309 .Sp
14310 .Vb 1
14311 \& int grok_number(const char *pv, STRLEN len, UV *valuep)
14312 .Ve
14313 .RE
14314 .RS 4
14315 .RE
14316 .ie n .IP """grok_number_flags""" 4
14317 .el .IP \f(CWgrok_number_flags\fR 4
14318 .IX Xref "grok_number_flags"
14319 .IX Item "grok_number_flags"
14320 Recognise (or not) a number. The type of the number is returned
14321 (0 if unrecognised), otherwise it is a bit-ORed combination of
14322 \&\f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR, \f(CW\*(C`IS_NUMBER_GREATER_THAN_UV_MAX\*(C'\fR, \f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR,
14323 \&\f(CW\*(C`IS_NUMBER_NEG\*(C'\fR, \f(CW\*(C`IS_NUMBER_INFINITY\*(C'\fR, \f(CW\*(C`IS_NUMBER_NAN\*(C'\fR (defined in perl.h).
14324 .Sp
14325 If the value of the number can fit in a UV, it is returned in \f(CW*valuep\fR.
14326 \&\f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR will be set to indicate that \f(CW*valuep\fR is valid, \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR
14327 will never be set unless \f(CW*valuep\fR is valid, but \f(CW*valuep\fR may have been assigned
14328 to during processing even though \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR is not set on return.
14329 If \f(CW\*(C`valuep\*(C'\fR is \f(CW\*(C`NULL\*(C'\fR, \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR will be set for the same cases as when
14330 \&\f(CW\*(C`valuep\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR, but no actual assignment (or SEGV) will occur.
14331 .Sp
14332 \&\f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR will be set with \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR if trailing decimals were
14333 seen (in which case \f(CW*valuep\fR gives the true value truncated to an integer), and
14334 \&\f(CW\*(C`IS_NUMBER_NEG\*(C'\fR if the number is negative (in which case \f(CW*valuep\fR holds the
14335 absolute value). \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR is not set if \f(CW\*(C`e\*(C'\fR notation was used or the
14336 number is larger than a UV.
14337 .Sp
14338 \&\f(CW\*(C`flags\*(C'\fR allows only \f(CW\*(C`PERL_SCAN_TRAILING\*(C'\fR, which allows for trailing
14339 non-numeric text on an otherwise successful \fIgrok\fR, setting
14340 \&\f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR on the result.
14341 .RS 4
14342 .Sp
14343 .Vb 2
14344 \& int grok_number_flags(const char *pv, STRLEN len, UV *valuep,
14345 \& U32 flags)
14346 .Ve
14347 .RE
14348 .RS 4
14349 .RE
14350 .ie n .IP """GROK_NUMERIC_RADIX""" 4
14351 .el .IP \f(CWGROK_NUMERIC_RADIX\fR 4
14352 .IX Xref "GROK_NUMERIC_RADIX"
14353 .IX Item "GROK_NUMERIC_RADIX"
14354 A synonym for "grok_numeric_radix"
14355 .RS 4
14356 .Sp
14357 .Vb 1
14358 \& bool GROK_NUMERIC_RADIX(NN const char **sp, NN const char *send)
14359 .Ve
14360 .RE
14361 .RS 4
14362 .RE
14363 .ie n .IP """grok_numeric_radix""" 4
14364 .el .IP \f(CWgrok_numeric_radix\fR 4
14365 .IX Xref "grok_numeric_radix"
14366 .IX Item "grok_numeric_radix"
14367 Scan and skip for a numeric decimal separator (radix).
14368 .RS 4
14369 .Sp
14370 .Vb 1
14371 \& bool grok_numeric_radix(const char **sp, const char *send)
14372 .Ve
14373 .RE
14374 .RS 4
14375 .RE
14376 .ie n .IP """grok_oct""" 4
14377 .el .IP \f(CWgrok_oct\fR 4
14378 .IX Xref "grok_oct"
14379 .IX Item "grok_oct"
14380 converts a string representing an octal number to numeric form.
14381 .Sp
14382 On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
14383 conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The
14384 scan stops at the end of the string, or at just before the first invalid
14385 character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
14386 encountering an invalid character (except NUL) will also trigger a warning. On
14387 return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
14388 gives output flags.
14389 .Sp
14390 If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
14391 and nothing is written to \f(CW*result\fR. If the value is > \f(CW\*(C`UV_MAX\*(C'\fR, \f(CW\*(C`grok_oct\*(C'\fR
14392 returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
14393 and writes an approximation of the correct value into \f(CW*result\fR (which is an
14394 NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
14395 .Sp
14396 If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
14397 digits may be separated from each other by a single underscore; also a single
14398 leading underscore is accepted.
14399 .Sp
14400 The \f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR flag is always treated as being set for
14401 this function.
14402 .RS 4
14403 .Sp
14404 .Vb 2
14405 \& UV grok_oct(const char *start, STRLEN *len_p, I32 *flags,
14406 \& NV *result)
14407 .Ve
14408 .RE
14409 .RS 4
14410 .RE
14411 .ie n .IP """isinfnan""" 4
14412 .el .IP \f(CWisinfnan\fR 4
14413 .IX Xref "isinfnan"
14414 .IX Item "isinfnan"
14415 \&\f(CWPerl_isinfnan()\fR is a utility function that returns true if the NV
14416 argument is either an infinity or a \f(CW\*(C`NaN\*(C'\fR, false otherwise. To test
14417 in more detail, use \f(CWPerl_isinf()\fR and \f(CWPerl_isnan()\fR.
14418 .Sp
14419 This is also the logical inverse of \fBPerl_isfinite()\fR.
14420 .RS 4
14421 .Sp
14422 .Vb 1
14423 \& bool isinfnan(NV nv)
14424 .Ve
14425 .RE
14426 .RS 4
14427 .RE
14428 .ie n .IP """my_atof""" 4
14429 .el .IP \f(CWmy_atof\fR 4
14430 .IX Xref "my_atof"
14431 .IX Item "my_atof"
14432 \&\f(CW\*(C`atof\*(C'\fR(3), but properly works with Perl locale handling, accepting a dot
14433 radix character always, but also the current locale's radix character if and
14434 only if called from within the lexical scope of a Perl \f(CW\*(C`use locale\*(C'\fR statement.
14435 .Sp
14436 N.B. \f(CW\*(C`s\*(C'\fR must be NUL terminated.
14437 .RS 4
14438 .Sp
14439 .Vb 1
14440 \& NV my_atof(const char *s)
14441 .Ve
14442 .RE
14443 .RS 4
14444 .RE
14445 .ie n .IP """my_strtod""" 4
14446 .el .IP \f(CWmy_strtod\fR 4
14447 .IX Xref "my_strtod"
14448 .IX Item "my_strtod"
14449 This function is equivalent to the libc \fBstrtod()\fR function, and is available
14450 even on platforms that lack plain \fBstrtod()\fR. Its return value is the best
14451 available precision depending on platform capabilities and \fIConfigure\fR
14452 options.
14453 .Sp
14454 It properly handles the locale radix character, meaning it expects a dot except
14455 when called from within the scope of \f(CW\*(C`use\ locale\*(C'\fR, in which case the radix
14456 character should be that specified by the current locale.
14457 .Sp
14458 The synonym \fBStrtod()\fR may be used instead.
14459 .RS 4
14460 .Sp
14461 .Vb 1
14462 \& NV my_strtod(const char * const s, char **e)
14463 .Ve
14464 .RE
14465 .RS 4
14466 .RE
14467 .ie n .IP """PERL_ABS""" 4
14468 .el .IP \f(CWPERL_ABS\fR 4
14469 .IX Xref "PERL_ABS"
14470 .IX Item "PERL_ABS"
14471 Typeless \f(CW\*(C`abs\*(C'\fR or \f(CW\*(C`fabs\*(C'\fR, \fIetc\fR. (The usage below indicates it is for
14472 integers, but it works for any type.) Use instead of these, since the C
14473 library ones force their argument to be what it is expecting, potentially
14474 leading to disaster. But also beware that this evaluates its argument twice,
14475 so no \f(CW\*(C`x++\*(C'\fR.
14476 .RS 4
14477 .Sp
14478 .Vb 1
14479 \& int PERL_ABS(int x)
14480 .Ve
14481 .RE
14482 .RS 4
14483 .RE
14484 .ie n .IP """Perl_acos""" 4
14485 .el .IP \f(CWPerl_acos\fR 4
14486 .IX Item "Perl_acos"
14487 .PD 0
14488 .ie n .IP """Perl_asin""" 4
14489 .el .IP \f(CWPerl_asin\fR 4
14490 .IX Item "Perl_asin"
14491 .ie n .IP """Perl_atan""" 4
14492 .el .IP \f(CWPerl_atan\fR 4
14493 .IX Item "Perl_atan"
14494 .ie n .IP """Perl_atan2""" 4
14495 .el .IP \f(CWPerl_atan2\fR 4
14496 .IX Item "Perl_atan2"
14497 .ie n .IP """Perl_ceil""" 4
14498 .el .IP \f(CWPerl_ceil\fR 4
14499 .IX Item "Perl_ceil"
14500 .ie n .IP """Perl_cos""" 4
14501 .el .IP \f(CWPerl_cos\fR 4
14502 .IX Item "Perl_cos"
14503 .ie n .IP """Perl_cosh""" 4
14504 .el .IP \f(CWPerl_cosh\fR 4
14505 .IX Item "Perl_cosh"
14506 .ie n .IP """Perl_exp""" 4
14507 .el .IP \f(CWPerl_exp\fR 4
14508 .IX Item "Perl_exp"
14509 .ie n .IP """Perl_floor""" 4
14510 .el .IP \f(CWPerl_floor\fR 4
14511 .IX Item "Perl_floor"
14512 .ie n .IP """Perl_fmod""" 4
14513 .el .IP \f(CWPerl_fmod\fR 4
14514 .IX Item "Perl_fmod"
14515 .ie n .IP """Perl_frexp""" 4
14516 .el .IP \f(CWPerl_frexp\fR 4
14517 .IX Item "Perl_frexp"
14518 .ie n .IP """Perl_isfinite""" 4
14519 .el .IP \f(CWPerl_isfinite\fR 4
14520 .IX Item "Perl_isfinite"
14521 .ie n .IP """Perl_isinf""" 4
14522 .el .IP \f(CWPerl_isinf\fR 4
14523 .IX Item "Perl_isinf"
14524 .ie n .IP """Perl_isnan""" 4
14525 .el .IP \f(CWPerl_isnan\fR 4
14526 .IX Item "Perl_isnan"
14527 .ie n .IP """Perl_ldexp""" 4
14528 .el .IP \f(CWPerl_ldexp\fR 4
14529 .IX Item "Perl_ldexp"
14530 .ie n .IP """Perl_log""" 4
14531 .el .IP \f(CWPerl_log\fR 4
14532 .IX Item "Perl_log"
14533 .ie n .IP """Perl_log10""" 4
14534 .el .IP \f(CWPerl_log10\fR 4
14535 .IX Item "Perl_log10"
14536 .ie n .IP """Perl_modf""" 4
14537 .el .IP \f(CWPerl_modf\fR 4
14538 .IX Item "Perl_modf"
14539 .ie n .IP """Perl_pow""" 4
14540 .el .IP \f(CWPerl_pow\fR 4
14541 .IX Item "Perl_pow"
14542 .ie n .IP """Perl_sin""" 4
14543 .el .IP \f(CWPerl_sin\fR 4
14544 .IX Item "Perl_sin"
14545 .ie n .IP """Perl_sinh""" 4
14546 .el .IP \f(CWPerl_sinh\fR 4
14547 .IX Item "Perl_sinh"
14548 .ie n .IP """Perl_sqrt""" 4
14549 .el .IP \f(CWPerl_sqrt\fR 4
14550 .IX Item "Perl_sqrt"
14551 .ie n .IP """Perl_tan""" 4
14552 .el .IP \f(CWPerl_tan\fR 4
14553 .IX Item "Perl_tan"
14554 .ie n .IP """Perl_tanh""" 4
14555 .el .IP \f(CWPerl_tanh\fR 4
14556 .IX Xref "Perl_acos Perl_asin Perl_atan Perl_atan2 Perl_ceil Perl_cos Perl_cosh Perl_exp Perl_floor Perl_fmod Perl_frexp Perl_isfinite Perl_isinf Perl_isnan Perl_ldexp Perl_log Perl_log10 Perl_modf Perl_pow Perl_sin Perl_sinh Perl_sqrt Perl_tan Perl_tanh"
14557 .IX Item "Perl_tanh"
14558 .PD
14559 These perform the corresponding mathematical operation on the operand(s), using
14560 the libc function designed for the task that has just enough precision for an
14561 NV on this platform. If no such function with sufficient precision exists,
14562 the highest precision one available is used.
14563 .RS 4
14564 .Sp
14565 .Vb 10
14566 \& NV Perl_acos (NV x)
14567 \& NV Perl_asin (NV x)
14568 \& NV Perl_atan (NV x)
14569 \& NV Perl_atan2 (NV x, NV y)
14570 \& NV Perl_ceil (NV x)
14571 \& NV Perl_cos (NV x)
14572 \& NV Perl_cosh (NV x)
14573 \& NV Perl_exp (NV x)
14574 \& NV Perl_floor (NV x)
14575 \& NV Perl_fmod (NV x, NV y)
14576 \& NV Perl_frexp (NV x, int *exp)
14577 \& IV Perl_isfinite(NV x)
14578 \& IV Perl_isinf (NV x)
14579 \& IV Perl_isnan (NV x)
14580 \& NV Perl_ldexp (NV x, int exp)
14581 \& NV Perl_log (NV x)
14582 \& NV Perl_log10 (NV x)
14583 \& NV Perl_modf (NV x, NV *iptr)
14584 \& NV Perl_pow (NV x, NV y)
14585 \& NV Perl_sin (NV x)
14586 \& NV Perl_sinh (NV x)
14587 \& NV Perl_sqrt (NV x)
14588 \& NV Perl_tan (NV x)
14589 \& NV Perl_tanh (NV x)
14590 .Ve
14591 .RE
14592 .RS 4
14593 .RE
14594 .ie n .IP """Perl_signbit""" 4
14595 .el .IP \f(CWPerl_signbit\fR 4
14596 .IX Xref "Perl_signbit"
14597 .IX Item "Perl_signbit"
14598 NOTE: \f(CW\*(C`Perl_signbit\*(C'\fR is \fBexperimental\fR and may change or be
14599 removed without notice.
14600 .Sp
14601 Return a non-zero integer if the sign bit on an NV is set, and 0 if
14602 it is not.
14603 .Sp
14604 If \fIConfigure\fR detects this system has a \f(CWsignbit()\fR that will work with
14605 our NVs, then we just use it via the \f(CW\*(C`#define\*(C'\fR in \fIperl.h\fR. Otherwise,
14606 fall back on this implementation. The main use of this function
14607 is catching \f(CW\-0.0\fR.
14608 .Sp
14609 \&\f(CW\*(C`Configure\*(C'\fR notes: This function is called \f(CW\*(AqPerl_signbit\*(Aq\fR instead of a
14610 plain \f(CW\*(Aqsignbit\*(Aq\fR because it is easy to imagine a system having a \f(CWsignbit()\fR
14611 function or macro that doesn't happen to work with our particular choice
14612 of NVs. We shouldn't just re\-\f(CW\*(C`#define\*(C'\fR \f(CW\*(C`signbit\*(C'\fR as \f(CW\*(C`Perl_signbit\*(C'\fR and expect
14613 the standard system headers to be happy. Also, this is a no-context
14614 function (no \f(CW\*(C`pTHX_\*(C'\fR) because \f(CWPerl_signbit()\fR is usually re\-\f(CW\*(C`#defined\*(C'\fR in
14615 \&\fIperl.h\fR as a simple macro call to the system's \f(CWsignbit()\fR.
14616 Users should just always call \f(CWPerl_signbit()\fR.
14617 .RS 4
14618 .Sp
14619 .Vb 1
14620 \& int Perl_signbit(NV f)
14621 .Ve
14622 .RE
14623 .RS 4
14624 .RE
14625 .ie n .IP """PL_hexdigit""" 4
14626 .el .IP \f(CWPL_hexdigit\fR 4
14627 .IX Xref "PL_hexdigit"
14628 .IX Item "PL_hexdigit"
14629 This array, indexed by an integer, converts that value into the character that
14630 represents it. For example, if the input is 8, the return will be a string
14631 whose first character is '8'. What is actually returned is a pointer into a
14632 string. All you are interested in is the first character of that string. To
14633 get uppercase letters (for the values 10..15), add 16 to the index. Hence,
14634 \&\f(CW\*(C`PL_hexdigit[11]\*(C'\fR is \f(CW\*(Aqb\*(Aq\fR, and \f(CW\*(C`PL_hexdigit[11+16]\*(C'\fR is \f(CW\*(AqB\*(Aq\fR. Adding 16
14635 to an index whose representation is '0'..'9' yields the same as not adding 16.
14636 Indices outside the range 0..31 result in (bad) undedefined behavior.
14637 .ie n .IP """READ_XDIGIT""" 4
14638 .el .IP \f(CWREAD_XDIGIT\fR 4
14639 .IX Xref "READ_XDIGIT"
14640 .IX Item "READ_XDIGIT"
14641 Returns the value of an ASCII-range hex digit and advances the string pointer.
14642 Behaviour is only well defined when isXDIGIT(*str) is true.
14643 .RS 4
14644 .Sp
14645 .Vb 1
14646 \& U8 READ_XDIGIT(char str*)
14647 .Ve
14648 .RE
14649 .RS 4
14650 .RE
14651 .ie n .IP """scan_bin""" 4
14652 .el .IP \f(CWscan_bin\fR 4
14653 .IX Xref "scan_bin"
14654 .IX Item "scan_bin"
14655 For backwards compatibility. Use \f(CW\*(C`grok_bin\*(C'\fR instead.
14656 .RS 4
14657 .Sp
14658 .Vb 1
14659 \& NV scan_bin(const char *start, STRLEN len, STRLEN *retlen)
14660 .Ve
14661 .RE
14662 .RS 4
14663 .RE
14664 .ie n .IP """scan_hex""" 4
14665 .el .IP \f(CWscan_hex\fR 4
14666 .IX Xref "scan_hex"
14667 .IX Item "scan_hex"
14668 For backwards compatibility. Use \f(CW\*(C`grok_hex\*(C'\fR instead.
14669 .RS 4
14670 .Sp
14671 .Vb 1
14672 \& NV scan_hex(const char *start, STRLEN len, STRLEN *retlen)
14673 .Ve
14674 .RE
14675 .RS 4
14676 .RE
14677 .ie n .IP """scan_oct""" 4
14678 .el .IP \f(CWscan_oct\fR 4
14679 .IX Xref "scan_oct"
14680 .IX Item "scan_oct"
14681 For backwards compatibility. Use \f(CW\*(C`grok_oct\*(C'\fR instead.
14682 .RS 4
14683 .Sp
14684 .Vb 1
14685 \& NV scan_oct(const char *start, STRLEN len, STRLEN *retlen)
14686 .Ve
14687 .RE
14688 .RS 4
14689 .RE
14690 .ie n .IP """seedDrand01""" 4
14691 .el .IP \f(CWseedDrand01\fR 4
14692 .IX Xref "seedDrand01"
14693 .IX Item "seedDrand01"
14694 This symbol defines the macro to be used in seeding the
14695 random number generator (see \f(CW"Drand01"\fR).
14696 .RS 4
14697 .Sp
14698 .Vb 1
14699 \& void seedDrand01(Rand_seed_t x)
14700 .Ve
14701 .RE
14702 .RS 4
14703 .RE
14704 .ie n .IP """Strtod""" 4
14705 .el .IP \f(CWStrtod\fR 4
14706 .IX Xref "Strtod"
14707 .IX Item "Strtod"
14708 This is a synonym for "my_strtod".
14709 .RS 4
14710 .Sp
14711 .Vb 1
14712 \& NV Strtod(NN const char * const s, NULLOK char ** e)
14713 .Ve
14714 .RE
14715 .RS 4
14716 .RE
14717 .ie n .IP """Strtol""" 4
14718 .el .IP \f(CWStrtol\fR 4
14719 .IX Xref "Strtol"
14720 .IX Item "Strtol"
14721 Platform and configuration independent \f(CW\*(C`strtol\*(C'\fR. This expands to the
14722 appropriate \f(CW\*(C`strotol\*(C'\fR\-like function based on the platform and \fIConfigure\fR
14723 options>. For example it could expand to \f(CW\*(C`strtoll\*(C'\fR or \f(CW\*(C`strtoq\*(C'\fR instead of
14724 \&\f(CW\*(C`strtol\*(C'\fR.
14725 .RS 4
14726 .Sp
14727 .Vb 1
14728 \& NV Strtol(NN const char * const s, NULLOK char ** e, int base)
14729 .Ve
14730 .RE
14731 .RS 4
14732 .RE
14733 .ie n .IP """Strtoul""" 4
14734 .el .IP \f(CWStrtoul\fR 4
14735 .IX Xref "Strtoul"
14736 .IX Item "Strtoul"
14737 Platform and configuration independent \f(CW\*(C`strtoul\*(C'\fR. This expands to the
14738 appropriate \f(CW\*(C`strotoul\*(C'\fR\-like function based on the platform and \fIConfigure\fR
14739 options>. For example it could expand to \f(CW\*(C`strtoull\*(C'\fR or \f(CW\*(C`strtouq\*(C'\fR instead of
14740 \&\f(CW\*(C`strtoul\*(C'\fR.
14741 .RS 4
14742 .Sp
14743 .Vb 1
14744 \& NV Strtoul(NN const char * const s, NULLOK char ** e, int base)
14745 .Ve
14746 .RE
14747 .RS 4
14748 .RE
14749 .SH Optrees
14750 .IX Xref "CALL_CHECKER_REQUIRE_GV OPf_KIDS OPpEARLY_CV OPpENTERSUB_AMPER RV2CVOPCV_MARK_EARLY RV2CVOPCV_RETURN_NAME_GV"
14751 .IX Header "Optrees"
14752 .ie n .IP """alloccopstash""" 4
14753 .el .IP \f(CWalloccopstash\fR 4
14754 .IX Xref "alloccopstash"
14755 .IX Item "alloccopstash"
14756 NOTE: \f(CW\*(C`alloccopstash\*(C'\fR is \fBexperimental\fR and may change or be
14757 removed without notice.
14758 .Sp
14759 Available only under threaded builds, this function allocates an entry in
14760 \&\f(CW\*(C`PL_stashpad\*(C'\fR for the stash passed to it.
14761 .RS 4
14762 .Sp
14763 .Vb 1
14764 \& PADOFFSET alloccopstash(HV *hv)
14765 .Ve
14766 .RE
14767 .RS 4
14768 .RE
14769 .ie n .IP """BINOP""" 4
14770 .el .IP \f(CWBINOP\fR 4
14771 .IX Item "BINOP"
14772 Described in perlguts.
14773 .ie n .IP """block_end""" 4
14774 .el .IP \f(CWblock_end\fR 4
14775 .IX Xref "block_end"
14776 .IX Item "block_end"
14777 Handles compile-time scope exit. \f(CW\*(C`floor\*(C'\fR
14778 is the savestack index returned by
14779 \&\f(CW\*(C`block_start\*(C'\fR, and \f(CW\*(C`seq\*(C'\fR is the body of the block. Returns the block,
14780 possibly modified.
14781 .RS 4
14782 .Sp
14783 .Vb 1
14784 \& OP * block_end(I32 floor, OP *seq)
14785 .Ve
14786 .RE
14787 .RS 4
14788 .RE
14789 .ie n .IP """block_start""" 4
14790 .el .IP \f(CWblock_start\fR 4
14791 .IX Xref "block_start"
14792 .IX Item "block_start"
14793 Handles compile-time scope entry.
14794 Arranges for hints to be restored on block
14795 exit and also handles pad sequence numbers to make lexical variables scope
14796 right. Returns a savestack index for use with \f(CW\*(C`block_end\*(C'\fR.
14797 .RS 4
14798 .Sp
14799 .Vb 1
14800 \& int block_start(int full)
14801 .Ve
14802 .RE
14803 .RS 4
14804 .RE
14805 .ie n .IP """ck_entersub_args_list""" 4
14806 .el .IP \f(CWck_entersub_args_list\fR 4
14807 .IX Xref "ck_entersub_args_list"
14808 .IX Item "ck_entersub_args_list"
14809 Performs the default fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR
14810 op tree. This consists of applying list context to each of the
14811 argument ops. This is the standard treatment used on a call marked
14812 with \f(CW\*(C`&\*(C'\fR, or a method call, or a call through a subroutine reference,
14813 or any other call where the callee can't be identified at compile time,
14814 or a call where the callee has no prototype.
14815 .RS 4
14816 .Sp
14817 .Vb 1
14818 \& OP * ck_entersub_args_list(OP *entersubop)
14819 .Ve
14820 .RE
14821 .RS 4
14822 .RE
14823 .ie n .IP """ck_entersub_args_proto""" 4
14824 .el .IP \f(CWck_entersub_args_proto\fR 4
14825 .IX Xref "ck_entersub_args_proto"
14826 .IX Item "ck_entersub_args_proto"
14827 Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree
14828 based on a subroutine prototype. This makes various modifications to
14829 the argument ops, from applying context up to inserting \f(CW\*(C`refgen\*(C'\fR ops,
14830 and checking the number and syntactic types of arguments, as directed by
14831 the prototype. This is the standard treatment used on a subroutine call,
14832 not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time
14833 and has a prototype.
14834 .Sp
14835 \&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call.
14836 It may be a normal defined scalar, of which the string value will be used.
14837 Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
14838 that has been cast to \f(CW\*(C`SV*\*(C'\fR) which has a prototype. The prototype
14839 supplied, in whichever form, does not need to match the actual callee
14840 referenced by the op tree.
14841 .Sp
14842 If the argument ops disagree with the prototype, for example by having
14843 an unacceptable number of arguments, a valid op tree is returned anyway.
14844 The error is reflected in the parser state, normally resulting in a single
14845 exception at the top level of parsing which covers all the compilation
14846 errors that occurred. In the error message, the callee is referred to
14847 by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter.
14848 .RS 4
14849 .Sp
14850 .Vb 2
14851 \& OP * ck_entersub_args_proto(OP *entersubop, GV *namegv,
14852 \& SV *protosv)
14853 .Ve
14854 .RE
14855 .RS 4
14856 .RE
14857 .ie n .IP """ck_entersub_args_proto_or_list""" 4
14858 .el .IP \f(CWck_entersub_args_proto_or_list\fR 4
14859 .IX Xref "ck_entersub_args_proto_or_list"
14860 .IX Item "ck_entersub_args_proto_or_list"
14861 Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree either
14862 based on a subroutine prototype or using default list-context processing.
14863 This is the standard treatment used on a subroutine call, not marked
14864 with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time.
14865 .Sp
14866 \&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call,
14867 or indicates that there is no prototype. It may be a normal scalar,
14868 in which case if it is defined then the string value will be used
14869 as a prototype, and if it is undefined then there is no prototype.
14870 Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
14871 that has been cast to \f(CW\*(C`SV*\*(C'\fR), of which the prototype will be used if it
14872 has one. The prototype (or lack thereof) supplied, in whichever form,
14873 does not need to match the actual callee referenced by the op tree.
14874 .Sp
14875 If the argument ops disagree with the prototype, for example by having
14876 an unacceptable number of arguments, a valid op tree is returned anyway.
14877 The error is reflected in the parser state, normally resulting in a single
14878 exception at the top level of parsing which covers all the compilation
14879 errors that occurred. In the error message, the callee is referred to
14880 by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter.
14881 .RS 4
14882 .Sp
14883 .Vb 2
14884 \& OP * ck_entersub_args_proto_or_list(OP *entersubop, GV *namegv,
14885 \& SV *protosv)
14886 .Ve
14887 .RE
14888 .RS 4
14889 .RE
14890 .ie n .IP """cv_const_sv""" 4
14891 .el .IP \f(CWcv_const_sv\fR 4
14892 .IX Xref "cv_const_sv"
14893 .IX Item "cv_const_sv"
14894 If \f(CW\*(C`cv\*(C'\fR is a constant sub eligible for inlining, returns the constant
14895 value returned by the sub. Otherwise, returns \f(CW\*(C`NULL\*(C'\fR.
14896 .Sp
14897 Constant subs can be created with \f(CW\*(C`newCONSTSUB\*(C'\fR or as described in
14898 "Constant Functions" in perlsub.
14899 .RS 4
14900 .Sp
14901 .Vb 1
14902 \& SV * cv_const_sv(const CV * const cv)
14903 .Ve
14904 .RE
14905 .RS 4
14906 .RE
14907 .ie n .IP """cv_get_call_checker""" 4
14908 .el .IP \f(CWcv_get_call_checker\fR 4
14909 .IX Xref "cv_get_call_checker"
14910 .IX Item "cv_get_call_checker"
14911 The original form of "cv_get_call_checker_flags", which does not return
14912 checker flags. When using a checker function returned by this function,
14913 it is only safe to call it with a genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument.
14914 .RS 4
14915 .Sp
14916 .Vb 2
14917 \& void cv_get_call_checker(CV *cv, Perl_call_checker *ckfun_p,
14918 \& SV **ckobj_p)
14919 .Ve
14920 .RE
14921 .RS 4
14922 .RE
14923 .ie n .IP """cv_get_call_checker_flags""" 4
14924 .el .IP \f(CWcv_get_call_checker_flags\fR 4
14925 .IX Xref "cv_get_call_checker_flags"
14926 .IX Item "cv_get_call_checker_flags"
14927 Retrieves the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR.
14928 Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
14929 subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
14930 at compile time as \f(CW\*(C`cv\*(C'\fR.
14931 .Sp
14932 The C\-level function pointer is returned in \f(CW*ckfun_p\fR, an SV argument
14933 for it is returned in \f(CW*ckobj_p\fR, and control flags are returned in
14934 \&\f(CW*ckflags_p\fR. The function is intended to be called in this manner:
14935 .Sp
14936 .Vb 1
14937 \& entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
14938 .Ve
14939 .Sp
14940 In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
14941 which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies
14942 the name that should be used by the check function to refer
14943 to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
14944 It is permitted to apply the check function in non-standard situations,
14945 such as to a call to a different subroutine or to a method call.
14946 .Sp
14947 \&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV. If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
14948 bit is clear in \f(CW*ckflags_p\fR, it is permitted to pass a CV or other SV
14949 instead, anything that can be used as the first argument to "cv_name".
14950 If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW*ckflags_p\fR then the
14951 check function requires \f(CW\*(C`namegv\*(C'\fR to be a genuine GV.
14952 .Sp
14953 By default, the check function is
14954 Perl_ck_entersub_args_proto_or_list,
14955 the SV parameter is \f(CW\*(C`cv\*(C'\fR itself, and the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
14956 flag is clear. This implements standard prototype processing. It can
14957 be changed, for a particular subroutine, by "cv_set_call_checker_flags".
14958 .Sp
14959 If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW\*(C`gflags\*(C'\fR then it
14960 indicates that the caller only knows about the genuine GV version of
14961 \&\f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit will always be set in
14962 \&\f(CW*ckflags_p\fR, regardless of the check function's recorded requirements.
14963 If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is clear in \f(CW\*(C`gflags\*(C'\fR then it
14964 indicates the caller knows about the possibility of passing something
14965 other than a GV as \f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit may
14966 be either set or clear in \f(CW*ckflags_p\fR, indicating the check function's
14967 recorded requirements.
14968 .Sp
14969 \&\f(CW\*(C`gflags\*(C'\fR is a bitset passed into \f(CW\*(C`cv_get_call_checker_flags\*(C'\fR, in which
14970 only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit currently has a defined meaning
14971 (for which see above). All other bits should be clear.
14972 .RS 4
14973 .Sp
14974 .Vb 3
14975 \& void cv_get_call_checker_flags(CV *cv, U32 gflags,
14976 \& Perl_call_checker *ckfun_p,
14977 \& SV **ckobj_p, U32 *ckflags_p)
14978 .Ve
14979 .RE
14980 .RS 4
14981 .RE
14982 .ie n .IP """cv_set_call_checker""" 4
14983 .el .IP \f(CWcv_set_call_checker\fR 4
14984 .IX Xref "cv_set_call_checker"
14985 .IX Item "cv_set_call_checker"
14986 The original form of "cv_set_call_checker_flags", which passes it the
14987 \&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR flag for backward-compatibility. The effect
14988 of that flag setting is that the check function is guaranteed to get a
14989 genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument.
14990 .RS 4
14991 .Sp
14992 .Vb 2
14993 \& void cv_set_call_checker(CV *cv, Perl_call_checker ckfun,
14994 \& SV *ckobj)
14995 .Ve
14996 .RE
14997 .RS 4
14998 .RE
14999 .ie n .IP """cv_set_call_checker_flags""" 4
15000 .el .IP \f(CWcv_set_call_checker_flags\fR 4
15001 .IX Xref "cv_set_call_checker_flags"
15002 .IX Item "cv_set_call_checker_flags"
15003 Sets the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR.
15004 Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
15005 subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
15006 at compile time as \f(CW\*(C`cv\*(C'\fR.
15007 .Sp
15008 The C\-level function pointer is supplied in \f(CW\*(C`ckfun\*(C'\fR, an SV argument for
15009 it is supplied in \f(CW\*(C`ckobj\*(C'\fR, and control flags are supplied in \f(CW\*(C`ckflags\*(C'\fR.
15010 The function should be defined like this:
15011 .Sp
15012 .Vb 1
15013 \& STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
15014 .Ve
15015 .Sp
15016 It is intended to be called in this manner:
15017 .Sp
15018 .Vb 1
15019 \& entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
15020 .Ve
15021 .Sp
15022 In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
15023 which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies
15024 the name that should be used by the check function to refer
15025 to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
15026 It is permitted to apply the check function in non-standard situations,
15027 such as to a call to a different subroutine or to a method call.
15028 .Sp
15029 \&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV. For efficiency, perl may pass a
15030 CV or other SV instead. Whatever is passed can be used as the first
15031 argument to "cv_name". You can force perl to pass a GV by including
15032 \&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR in the \f(CW\*(C`ckflags\*(C'\fR.
15033 .Sp
15034 \&\f(CW\*(C`ckflags\*(C'\fR is a bitset, in which only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
15035 bit currently has a defined meaning (for which see above). All other
15036 bits should be clear.
15037 .Sp
15038 The current setting for a particular CV can be retrieved by
15039 "cv_get_call_checker_flags".
15040 .RS 4
15041 .Sp
15042 .Vb 2
15043 \& void cv_set_call_checker_flags(CV *cv, Perl_call_checker ckfun,
15044 \& SV *ckobj, U32 ckflags)
15045 .Ve
15046 .RE
15047 .RS 4
15048 .RE
15049 .ie n .IP """finalize_optree""" 4
15050 .el .IP \f(CWfinalize_optree\fR 4
15051 .IX Xref "finalize_optree"
15052 .IX Item "finalize_optree"
15053 This function finalizes the optree. Should be called directly after
15054 the complete optree is built. It does some additional
15055 checking which can't be done in the normal \f(CW\*(C`ck_\*(C'\fRxxx functions and makes
15056 the tree thread-safe.
15057 .RS 4
15058 .Sp
15059 .Vb 1
15060 \& void finalize_optree(OP *o)
15061 .Ve
15062 .RE
15063 .RS 4
15064 .RE
15065 .ie n .IP """forbid_outofblock_ops""" 4
15066 .el .IP \f(CWforbid_outofblock_ops\fR 4
15067 .IX Xref "forbid_outofblock_ops"
15068 .IX Item "forbid_outofblock_ops"
15069 NOTE: \f(CW\*(C`forbid_outofblock_ops\*(C'\fR is \fBexperimental\fR and may change or be
15070 removed without notice.
15071 .Sp
15072 Checks an optree that implements a block, to ensure there are no control-flow
15073 ops that attempt to leave the block. Any \f(CW\*(C`OP_RETURN\*(C'\fR is forbidden, as is any
15074 \&\f(CW\*(C`OP_GOTO\*(C'\fR. Loops are analysed, so any LOOPEX op (\f(CW\*(C`OP_NEXT\*(C'\fR, \f(CW\*(C`OP_LAST\*(C'\fR or
15075 \&\f(CW\*(C`OP_REDO\*(C'\fR) that affects a loop that contains it within the block are
15076 permitted, but those that do not are forbidden.
15077 .Sp
15078 If any of these forbidden constructions are detected, an exception is thrown
15079 by using the op name and the blockname argument to construct a suitable
15080 message.
15081 .Sp
15082 This function alone is not sufficient to ensure the optree does not perform
15083 any of these forbidden activities during runtime, as it might call a different
15084 function that performs a non-local LOOPEX, or a string\-\fBeval()\fR that performs a
15085 \&\f(CW\*(C`goto\*(C'\fR, or various other things. It is intended purely as a compile-time
15086 check for those that could be detected statically. Additional runtime checks
15087 may be required depending on the circumstance it is used for.
15088 .Sp
15089 Note currently that \fIall\fR \f(CW\*(C`OP_GOTO\*(C'\fR ops are forbidden, even in cases where
15090 they might otherwise be safe to execute. This may be permitted in a later
15091 version.
15092 .RS 4
15093 .Sp
15094 .Vb 1
15095 \& void forbid_outofblock_ops(OP *o, const char *blockname)
15096 .Ve
15097 .RE
15098 .RS 4
15099 .RE
15100 .ie n .IP """LINKLIST""" 4
15101 .el .IP \f(CWLINKLIST\fR 4
15102 .IX Xref "LINKLIST"
15103 .IX Item "LINKLIST"
15104 Given the root of an optree, link the tree in execution order using the
15105 \&\f(CW\*(C`op_next\*(C'\fR pointers and return the first op executed. If this has
15106 already been done, it will not be redone, and \f(CW\*(C`o\->op_next\*(C'\fR will be
15107 returned. If \f(CW\*(C`o\->op_next\*(C'\fR is not already set, \f(CW\*(C`o\*(C'\fR should be at
15108 least an \f(CW\*(C`UNOP\*(C'\fR.
15109 .RS 4
15110 .Sp
15111 .Vb 1
15112 \& OP* LINKLIST(OP *o)
15113 .Ve
15114 .RE
15115 .RS 4
15116 .RE
15117 .ie n .IP """LISTOP""" 4
15118 .el .IP \f(CWLISTOP\fR 4
15119 .IX Item "LISTOP"
15120 Described in perlguts.
15121 .ie n .IP """LOGOP""" 4
15122 .el .IP \f(CWLOGOP\fR 4
15123 .IX Item "LOGOP"
15124 Described in perlguts.
15125 .ie n .IP """LOOP""" 4
15126 .el .IP \f(CWLOOP\fR 4
15127 .IX Item "LOOP"
15128 Described in perlguts.
15129 .ie n .IP """newANONATTRSUB""" 4
15130 .el .IP \f(CWnewANONATTRSUB\fR 4
15131 .IX Xref "newANONATTRSUB"
15132 .IX Item "newANONATTRSUB"
15133 Construct a nameless (anonymous) Perl subroutine, also performing some
15134 surrounding jobs.
15135 .Sp
15136 This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter
15137 set to FALSE, and its \f(CW\*(C`o\*(C'\fR parameter to NULL.
15138 For more details, see "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
15139 .RS 4
15140 .Sp
15141 .Vb 1
15142 \& OP * newANONATTRSUB(I32 floor, OP *proto, OP *attrs, OP *block)
15143 .Ve
15144 .RE
15145 .RS 4
15146 .RE
15147 .ie n .IP """newANONHASH""" 4
15148 .el .IP \f(CWnewANONHASH\fR 4
15149 .IX Xref "newANONHASH"
15150 .IX Item "newANONHASH"
15151 Constructs, checks, and returns an anonymous hash op.
15152 .RS 4
15153 .Sp
15154 .Vb 1
15155 \& OP * newANONHASH(OP *o)
15156 .Ve
15157 .RE
15158 .RS 4
15159 .RE
15160 .ie n .IP """newANONLIST""" 4
15161 .el .IP \f(CWnewANONLIST\fR 4
15162 .IX Xref "newANONLIST"
15163 .IX Item "newANONLIST"
15164 Constructs, checks, and returns an anonymous list op.
15165 .RS 4
15166 .Sp
15167 .Vb 1
15168 \& OP * newANONLIST(OP *o)
15169 .Ve
15170 .RE
15171 .RS 4
15172 .RE
15173 .ie n .IP """newANONSUB""" 4
15174 .el .IP \f(CWnewANONSUB\fR 4
15175 .IX Xref "newANONSUB"
15176 .IX Item "newANONSUB"
15177 Construct a nameless (anonymous) Perl subroutine without attributes, also
15178 performing some surrounding jobs.
15179 .Sp
15180 This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter
15181 set to FALSE, and its \f(CW\*(C`o\*(C'\fR and \f(CW\*(C`attrs\*(C'\fR parameters to NULL.
15182 For more details, see "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
15183 .RS 4
15184 .Sp
15185 .Vb 1
15186 \& OP * newANONSUB(I32 floor, OP *proto, OP *block)
15187 .Ve
15188 .RE
15189 .RS 4
15190 .RE
15191 .ie n .IP """newARGDEFELEMOP""" 4
15192 .el .IP \f(CWnewARGDEFELEMOP\fR 4
15193 .IX Xref "newARGDEFELEMOP"
15194 .IX Item "newARGDEFELEMOP"
15195 Constructs and returns a new \f(CW\*(C`OP_ARGDEFELEM\*(C'\fR op which provides a defaulting
15196 expression given by \f(CW\*(C`expr\*(C'\fR for the signature parameter at the index given
15197 by \f(CW\*(C`argindex\*(C'\fR. The expression optree is consumed by this function and
15198 becomes part of the returned optree.
15199 .RS 4
15200 .Sp
15201 .Vb 1
15202 \& OP * newARGDEFELEMOP(I32 flags, OP *expr, I32 argindex)
15203 .Ve
15204 .RE
15205 .RS 4
15206 .RE
15207 .ie n .IP """newASSIGNOP""" 4
15208 .el .IP \f(CWnewASSIGNOP\fR 4
15209 .IX Xref "newASSIGNOP"
15210 .IX Item "newASSIGNOP"
15211 Constructs, checks, and returns an assignment op. \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR
15212 supply the parameters of the assignment; they are consumed by this
15213 function and become part of the constructed op tree.
15214 .Sp
15215 If \f(CW\*(C`optype\*(C'\fR is \f(CW\*(C`OP_ANDASSIGN\*(C'\fR, \f(CW\*(C`OP_ORASSIGN\*(C'\fR, or \f(CW\*(C`OP_DORASSIGN\*(C'\fR, then
15216 a suitable conditional optree is constructed. If \f(CW\*(C`optype\*(C'\fR is the opcode
15217 of a binary operator, such as \f(CW\*(C`OP_BIT_OR\*(C'\fR, then an op is constructed that
15218 performs the binary operation and assigns the result to the left argument.
15219 Either way, if \f(CW\*(C`optype\*(C'\fR is non-zero then \f(CW\*(C`flags\*(C'\fR has no effect.
15220 .Sp
15221 If \f(CW\*(C`optype\*(C'\fR is zero, then a plain scalar or list assignment is
15222 constructed. Which type of assignment it is is automatically determined.
15223 \&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR
15224 will be set automatically, and, shifted up eight bits, the eight bits
15225 of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically
15226 set as required.
15227 .RS 4
15228 .Sp
15229 .Vb 1
15230 \& OP * newASSIGNOP(I32 flags, OP *left, I32 optype, OP *right)
15231 .Ve
15232 .RE
15233 .RS 4
15234 .RE
15235 .ie n .IP """newATTRSUB""" 4
15236 .el .IP \f(CWnewATTRSUB\fR 4
15237 .IX Xref "newATTRSUB"
15238 .IX Item "newATTRSUB"
15239 Construct a Perl subroutine, also performing some surrounding jobs,
15240 returning a pointer to the constructed subroutine.
15241 .Sp
15242 This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter
15243 set to FALSE. This means that if \f(CW\*(C`o\*(C'\fR is null, the new sub will be anonymous;
15244 otherwise the name will be derived from \f(CW\*(C`o\*(C'\fR in the way described (as with all
15245 other details) in "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
15246 .RS 4
15247 .Sp
15248 .Vb 2
15249 \& CV * newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs,
15250 \& OP *block)
15251 .Ve
15252 .RE
15253 .RS 4
15254 .RE
15255 .ie n .IP """newAVREF""" 4
15256 .el .IP \f(CWnewAVREF\fR 4
15257 .IX Xref "newAVREF"
15258 .IX Item "newAVREF"
15259 Constructs, checks, and returns an arrary reference op.
15260 .RS 4
15261 .Sp
15262 .Vb 1
15263 \& OP * newAVREF(OP *o)
15264 .Ve
15265 .RE
15266 .RS 4
15267 .RE
15268 .ie n .IP """newBINOP""" 4
15269 .el .IP \f(CWnewBINOP\fR 4
15270 .IX Xref "newBINOP"
15271 .IX Item "newBINOP"
15272 Constructs, checks, and returns an op of any binary type. \f(CW\*(C`type\*(C'\fR
15273 is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except
15274 that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits,
15275 the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or
15276 2 is automatically set as required. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR supply up to
15277 two ops to be the direct children of the binary op; they are consumed
15278 by this function and become part of the constructed op tree.
15279 .RS 4
15280 .Sp
15281 .Vb 1
15282 \& OP * newBINOP(I32 type, I32 flags, OP *first, OP *last)
15283 .Ve
15284 .RE
15285 .RS 4
15286 .RE
15287 .ie n .IP """newCONDOP""" 4
15288 .el .IP \f(CWnewCONDOP\fR 4
15289 .IX Xref "newCONDOP"
15290 .IX Item "newCONDOP"
15291 Constructs, checks, and returns a conditional-expression (\f(CW\*(C`cond_expr\*(C'\fR)
15292 op. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR
15293 will be set automatically, and, shifted up eight bits, the eight bits of
15294 \&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is automatically set.
15295 \&\f(CW\*(C`first\*(C'\fR supplies the expression selecting between the two branches,
15296 and \f(CW\*(C`trueop\*(C'\fR and \f(CW\*(C`falseop\*(C'\fR supply the branches; they are consumed by
15297 this function and become part of the constructed op tree.
15298 .RS 4
15299 .Sp
15300 .Vb 1
15301 \& OP * newCONDOP(I32 flags, OP *first, OP *trueop, OP *falseop)
15302 .Ve
15303 .RE
15304 .RS 4
15305 .RE
15306 .ie n .IP """newCONSTSUB""" 4
15307 .el .IP \f(CWnewCONSTSUB\fR 4
15308 .IX Item "newCONSTSUB"
15309 .PD 0
15310 .ie n .IP """newCONSTSUB_flags""" 4
15311 .el .IP \f(CWnewCONSTSUB_flags\fR 4
15312 .IX Xref "newCONSTSUB newCONSTSUB_flags"
15313 .IX Item "newCONSTSUB_flags"
15314 .PD
15315 Construct a constant subroutine, also performing some surrounding
15316 jobs. A scalar constant-valued subroutine is eligible for inlining
15317 at compile-time, and in Perl code can be created by \f(CW\*(C`sub\ FOO\ ()\ {\ 123\ }\*(C'\fR. Other kinds of constant subroutine have other treatment.
15318 .Sp
15319 The subroutine will have an empty prototype and will ignore any arguments
15320 when called. Its constant behaviour is determined by \f(CW\*(C`sv\*(C'\fR. If \f(CW\*(C`sv\*(C'\fR
15321 is null, the subroutine will yield an empty list. If \f(CW\*(C`sv\*(C'\fR points to a
15322 scalar, the subroutine will always yield that scalar. If \f(CW\*(C`sv\*(C'\fR points
15323 to an array, the subroutine will always yield a list of the elements of
15324 that array in list context, or the number of elements in the array in
15325 scalar context. This function takes ownership of one counted reference
15326 to the scalar or array, and will arrange for the object to live as long
15327 as the subroutine does. If \f(CW\*(C`sv\*(C'\fR points to a scalar then the inlining
15328 assumes that the value of the scalar will never change, so the caller
15329 must ensure that the scalar is not subsequently written to. If \f(CW\*(C`sv\*(C'\fR
15330 points to an array then no such assumption is made, so it is ostensibly
15331 safe to mutate the array or its elements, but whether this is really
15332 supported has not been determined.
15333 .Sp
15334 The subroutine will have \f(CW\*(C`CvFILE\*(C'\fR set according to \f(CW\*(C`PL_curcop\*(C'\fR.
15335 Other aspects of the subroutine will be left in their default state.
15336 The caller is free to mutate the subroutine beyond its initial state
15337 after this function has returned.
15338 .Sp
15339 If \f(CW\*(C`name\*(C'\fR is null then the subroutine will be anonymous, with its
15340 \&\f(CW\*(C`CvGV\*(C'\fR referring to an \f(CW\*(C`_\|_ANON_\|_\*(C'\fR glob. If \f(CW\*(C`name\*(C'\fR is non-null then the
15341 subroutine will be named accordingly, referenced by the appropriate glob.
15342 .Sp
15343 \&\f(CW\*(C`name\*(C'\fR is a string, giving a sigilless symbol name.
15344 For \f(CW\*(C`/newCONSTSUB\*(C'\fR, \f(CW\*(C`name\*(C'\fR is NUL-terminated, interpreted as Latin\-1.
15345 .Sp
15346 For \f(CW\*(C`/newCONSTSUB_flags\*(C'\fR, \f(CW\*(C`name\*(C'\fR has length \f(CW\*(C`len\*(C'\fR bytes, hence may contain
15347 embedded NULs. It is interpreted as UTF\-8 if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SVf_UTF8\*(C'\fR bit
15348 set, and Latin\-1 otherwise. \f(CW\*(C`flags\*(C'\fR should not have bits set other than
15349 \&\f(CW\*(C`SVf_UTF8\*(C'\fR.
15350 .Sp
15351 The name may be either qualified or unqualified. If the
15352 name is unqualified then it defaults to being in the stash specified by
15353 \&\f(CW\*(C`stash\*(C'\fR if that is non-null, or to \f(CW\*(C`PL_curstash\*(C'\fR if \f(CW\*(C`stash\*(C'\fR is null.
15354 The symbol is always added to the stash if necessary, with \f(CW\*(C`GV_ADDMULTI\*(C'\fR
15355 semantics.
15356 .Sp
15357 If there is already a subroutine of the specified name, then the new sub
15358 will replace the existing one in the glob. A warning may be generated
15359 about the redefinition.
15360 .Sp
15361 If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or
15362 \&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic
15363 running of phase-related subroutines. In this case the relevant glob will
15364 be left not containing any subroutine, even if it did contain one before.
15365 Execution of the subroutine will likely be a no-op, unless \f(CW\*(C`sv\*(C'\fR was
15366 a tied array or the caller modified the subroutine in some interesting
15367 way before it was executed. In the case of \f(CW\*(C`BEGIN\*(C'\fR, the treatment is
15368 buggy: the sub will be executed when only half built, and may be deleted
15369 prematurely, possibly causing a crash.
15370 .Sp
15371 The function returns a pointer to the constructed subroutine. If the sub
15372 is anonymous then ownership of one counted reference to the subroutine
15373 is transferred to the caller. If the sub is named then the caller does
15374 not get ownership of a reference. In most such cases, where the sub
15375 has a non-phase name, the sub will be alive at the point it is returned
15376 by virtue of being contained in the glob that names it. A phase-named
15377 subroutine will usually be alive by virtue of the reference owned by
15378 the phase's automatic run queue. A \f(CW\*(C`BEGIN\*(C'\fR subroutine may have been
15379 destroyed already by the time this function returns, but currently bugs
15380 occur in that case before the caller gets control. It is the caller's
15381 responsibility to ensure that it knows which of these situations applies.
15382 .RS 4
15383 .Sp
15384 .Vb 3
15385 \& CV * newCONSTSUB (HV *stash, const char *name, SV *sv)
15386 \& CV * newCONSTSUB_flags(HV *stash, const char *name, STRLEN len,
15387 \& U32 flags, SV *sv)
15388 .Ve
15389 .RE
15390 .RS 4
15391 .RE
15392 .ie n .IP """newCVREF""" 4
15393 .el .IP \f(CWnewCVREF\fR 4
15394 .IX Xref "newCVREF"
15395 .IX Item "newCVREF"
15396 Constructs, checks, and returns a code reference op.
15397 .RS 4
15398 .Sp
15399 .Vb 1
15400 \& OP * newCVREF(I32 flags, OP *o)
15401 .Ve
15402 .RE
15403 .RS 4
15404 .RE
15405 .ie n .IP """newDEFEROP""" 4
15406 .el .IP \f(CWnewDEFEROP\fR 4
15407 .IX Xref "newDEFEROP"
15408 .IX Item "newDEFEROP"
15409 NOTE: \f(CW\*(C`newDEFEROP\*(C'\fR is \fBexperimental\fR and may change or be
15410 removed without notice.
15411 .Sp
15412 Constructs and returns a deferred-block statement that implements the
15413 \&\f(CW\*(C`defer\*(C'\fR semantics. The \f(CW\*(C`block\*(C'\fR optree is consumed by this function and
15414 becomes part of the returned optree.
15415 .Sp
15416 The \f(CW\*(C`flags\*(C'\fR argument carries additional flags to set on the returned op,
15417 including the \f(CW\*(C`op_private\*(C'\fR field.
15418 .RS 4
15419 .Sp
15420 .Vb 1
15421 \& OP * newDEFEROP(I32 flags, OP *block)
15422 .Ve
15423 .RE
15424 .RS 4
15425 .RE
15426 .ie n .IP """newDEFSVOP""" 4
15427 .el .IP \f(CWnewDEFSVOP\fR 4
15428 .IX Xref "newDEFSVOP"
15429 .IX Item "newDEFSVOP"
15430 Constructs and returns an op to access \f(CW$_\fR.
15431 .RS 4
15432 .Sp
15433 .Vb 1
15434 \& OP * newDEFSVOP()
15435 .Ve
15436 .RE
15437 .RS 4
15438 .RE
15439 .ie n .IP """newFOROP""" 4
15440 .el .IP \f(CWnewFOROP\fR 4
15441 .IX Xref "newFOROP"
15442 .IX Item "newFOROP"
15443 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`foreach\*(C'\fR
15444 loop (iteration through a list of values). This is a heavyweight loop,
15445 with structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR and suchlike.
15446 .Sp
15447 \&\f(CW\*(C`sv\*(C'\fR optionally supplies the variable(s) that will be aliased to each
15448 item in turn; if null, it defaults to \f(CW$_\fR.
15449 \&\f(CW\*(C`expr\*(C'\fR supplies the list of values to iterate over. \f(CW\*(C`block\*(C'\fR supplies
15450 the main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR
15451 block that operates as a second half of the body. All of these optree
15452 inputs are consumed by this function and become part of the constructed
15453 op tree.
15454 .Sp
15455 \&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the \f(CW\*(C`leaveloop\*(C'\fR
15456 op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for
15457 the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set
15458 automatically.
15459 .RS 4
15460 .Sp
15461 .Vb 1
15462 \& OP * newFOROP(I32 flags, OP *sv, OP *expr, OP *block, OP *cont)
15463 .Ve
15464 .RE
15465 .RS 4
15466 .RE
15467 .ie n .IP """newGIVENOP""" 4
15468 .el .IP \f(CWnewGIVENOP\fR 4
15469 .IX Xref "newGIVENOP"
15470 .IX Item "newGIVENOP"
15471 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`given\*(C'\fR block.
15472 \&\f(CW\*(C`cond\*(C'\fR supplies the expression to whose value \f(CW$_\fR will be locally
15473 aliased, and \f(CW\*(C`block\*(C'\fR supplies the body of the \f(CW\*(C`given\*(C'\fR construct; they
15474 are consumed by this function and become part of the constructed op tree.
15475 \&\f(CW\*(C`defsv_off\*(C'\fR must be zero (it used to identity the pad slot of lexical \f(CW$_\fR).
15476 .RS 4
15477 .Sp
15478 .Vb 1
15479 \& OP * newGIVENOP(OP *cond, OP *block, PADOFFSET defsv_off)
15480 .Ve
15481 .RE
15482 .RS 4
15483 .RE
15484 .ie n .IP """newGVOP""" 4
15485 .el .IP \f(CWnewGVOP\fR 4
15486 .IX Xref "newGVOP"
15487 .IX Item "newGVOP"
15488 Constructs, checks, and returns an op of any type that involves an
15489 embedded reference to a GV. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the
15490 eight bits of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`gv\*(C'\fR identifies the GV that the op should
15491 reference; calling this function does not transfer ownership of any
15492 reference to it.
15493 .RS 4
15494 .Sp
15495 .Vb 1
15496 \& OP * newGVOP(I32 type, I32 flags, GV *gv)
15497 .Ve
15498 .RE
15499 .RS 4
15500 .RE
15501 .ie n .IP """newGVREF""" 4
15502 .el .IP \f(CWnewGVREF\fR 4
15503 .IX Xref "newGVREF"
15504 .IX Item "newGVREF"
15505 Constructs, checks, and returns a glob reference op.
15506 .RS 4
15507 .Sp
15508 .Vb 1
15509 \& OP * newGVREF(I32 type, OP *o)
15510 .Ve
15511 .RE
15512 .RS 4
15513 .RE
15514 .ie n .IP """newHVREF""" 4
15515 .el .IP \f(CWnewHVREF\fR 4
15516 .IX Xref "newHVREF"
15517 .IX Item "newHVREF"
15518 Constructs, checks, and returns a hash reference op.
15519 .RS 4
15520 .Sp
15521 .Vb 1
15522 \& OP * newHVREF(OP *o)
15523 .Ve
15524 .RE
15525 .RS 4
15526 .RE
15527 .ie n .IP """newLISTOP""" 4
15528 .el .IP \f(CWnewLISTOP\fR 4
15529 .IX Xref "newLISTOP"
15530 .IX Item "newLISTOP"
15531 Constructs, checks, and returns an op of any list type. \f(CW\*(C`type\*(C'\fR is
15532 the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
15533 \&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR
15534 supply up to two ops to be direct children of the list op; they are
15535 consumed by this function and become part of the constructed op tree.
15536 .Sp
15537 For most list operators, the check function expects all the kid ops to be
15538 present already, so calling \f(CW\*(C`newLISTOP(OP_JOIN, ...)\*(C'\fR (e.g.) is not
15539 appropriate. What you want to do in that case is create an op of type
15540 \&\f(CW\*(C`OP_LIST\*(C'\fR, append more children to it, and then call "op_convert_list".
15541 See "op_convert_list" for more information.
15542 .Sp
15543 If a compiletime-known fixed list of child ops is required, the
15544 "newLISTOPn" function can be used as a convenient shortcut, avoiding the
15545 need to create a temporary plain \f(CW\*(C`OP_LIST\*(C'\fR in a new variable.
15546 .RS 4
15547 .Sp
15548 .Vb 1
15549 \& OP * newLISTOP(I32 type, I32 flags, OP *first, OP *last)
15550 .Ve
15551 .RE
15552 .RS 4
15553 .RE
15554 .ie n .IP """newLISTOPn""" 4
15555 .el .IP \f(CWnewLISTOPn\fR 4
15556 .IX Xref "newLISTOPn"
15557 .IX Item "newLISTOPn"
15558 Constructs, checks, and returns an op of any list type. \f(CW\*(C`type\*(C'\fR is
15559 the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
15560 \&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required. The variable number of
15561 arguments after \f(CW\*(C`flags\*(C'\fR must all be OP pointers, terminated by a final
15562 \&\f(CW\*(C`NULL\*(C'\fR pointer. These will all be consumed as direct children of the list
15563 op and become part of the constructed op tree.
15564 .Sp
15565 Do not forget to end the arguments list with a \f(CW\*(C`NULL\*(C'\fR pointer.
15566 .Sp
15567 This function is useful as a shortcut to performing the sequence of
15568 \&\f(CWnewLISTOP()\fR, \f(CWop_append_elem()\fR on each element and final
15569 \&\f(CWop_convert_list()\fR in the case where a compiletime-known fixed sequence of
15570 child ops is required. If a variable number of elements are required, or for
15571 splicing in an entire sub-list of child ops, see instead "newLISTOP" and
15572 "op_convert_list".
15573 .RS 4
15574 .Sp
15575 .Vb 1
15576 \& OP * newLISTOPn(I32 type, I32 flags, ...)
15577 .Ve
15578 .RE
15579 .RS 4
15580 .RE
15581 .ie n .IP """newLOGOP""" 4
15582 .el .IP \f(CWnewLOGOP\fR 4
15583 .IX Xref "newLOGOP"
15584 .IX Item "newLOGOP"
15585 Constructs, checks, and returns a logical (flow control) op. \f(CW\*(C`type\*(C'\fR
15586 is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except
15587 that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits,
15588 the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is
15589 automatically set. \f(CW\*(C`first\*(C'\fR supplies the expression controlling the
15590 flow, and \f(CW\*(C`other\*(C'\fR supplies the side (alternate) chain of ops; they are
15591 consumed by this function and become part of the constructed op tree.
15592 .RS 4
15593 .Sp
15594 .Vb 1
15595 \& OP * newLOGOP(I32 optype, I32 flags, OP *first, OP *other)
15596 .Ve
15597 .RE
15598 .RS 4
15599 .RE
15600 .ie n .IP """newLOOPEX""" 4
15601 .el .IP \f(CWnewLOOPEX\fR 4
15602 .IX Xref "newLOOPEX"
15603 .IX Item "newLOOPEX"
15604 Constructs, checks, and returns a loop-exiting op (such as \f(CW\*(C`goto\*(C'\fR
15605 or \f(CW\*(C`last\*(C'\fR). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`label\*(C'\fR supplies the parameter
15606 determining the target of the op; it is consumed by this function and
15607 becomes part of the constructed op tree.
15608 .RS 4
15609 .Sp
15610 .Vb 1
15611 \& OP * newLOOPEX(I32 type, OP *label)
15612 .Ve
15613 .RE
15614 .RS 4
15615 .RE
15616 .ie n .IP """newLOOPOP""" 4
15617 .el .IP \f(CWnewLOOPOP\fR 4
15618 .IX Xref "newLOOPOP"
15619 .IX Item "newLOOPOP"
15620 Constructs, checks, and returns an op tree expressing a loop. This is
15621 only a loop in the control flow through the op tree; it does not have
15622 the heavyweight loop structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR
15623 and suchlike. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the
15624 top-level op, except that some bits will be set automatically as required.
15625 \&\f(CW\*(C`expr\*(C'\fR supplies the expression controlling loop iteration, and \f(CW\*(C`block\*(C'\fR
15626 supplies the body of the loop; they are consumed by this function and
15627 become part of the constructed op tree. \f(CW\*(C`debuggable\*(C'\fR is currently
15628 unused and should always be 1.
15629 .RS 4
15630 .Sp
15631 .Vb 1
15632 \& OP * newLOOPOP(I32 flags, I32 debuggable, OP *expr, OP *block)
15633 .Ve
15634 .RE
15635 .RS 4
15636 .RE
15637 .ie n .IP """newMETHOP""" 4
15638 .el .IP \f(CWnewMETHOP\fR 4
15639 .IX Xref "newMETHOP"
15640 .IX Item "newMETHOP"
15641 Constructs, checks, and returns an op of method type with a method name
15642 evaluated at runtime. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight
15643 bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically,
15644 and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that
15645 the bit with value 1 is automatically set. \f(CW\*(C`dynamic_meth\*(C'\fR supplies an
15646 op which evaluates method name; it is consumed by this function and
15647 become part of the constructed op tree.
15648 Supported optypes: \f(CW\*(C`OP_METHOD\*(C'\fR.
15649 .RS 4
15650 .Sp
15651 .Vb 1
15652 \& OP * newMETHOP(I32 type, I32 flags, OP *dynamic_meth)
15653 .Ve
15654 .RE
15655 .RS 4
15656 .RE
15657 .ie n .IP """newMETHOP_named""" 4
15658 .el .IP \f(CWnewMETHOP_named\fR 4
15659 .IX Xref "newMETHOP_named"
15660 .IX Item "newMETHOP_named"
15661 Constructs, checks, and returns an op of method type with a constant
15662 method name. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of
15663 \&\f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits of
15664 \&\f(CW\*(C`op_private\*(C'\fR. \f(CW\*(C`const_meth\*(C'\fR supplies a constant method name;
15665 it must be a shared COW string.
15666 Supported optypes: \f(CW\*(C`OP_METHOD_NAMED\*(C'\fR.
15667 .RS 4
15668 .Sp
15669 .Vb 1
15670 \& OP * newMETHOP_named(I32 type, I32 flags, SV * const_meth)
15671 .Ve
15672 .RE
15673 .RS 4
15674 .RE
15675 .ie n .IP """newNULLLIST""" 4
15676 .el .IP \f(CWnewNULLLIST\fR 4
15677 .IX Xref "newNULLLIST"
15678 .IX Item "newNULLLIST"
15679 Constructs, checks, and returns a new \f(CW\*(C`stub\*(C'\fR op, which represents an
15680 empty list expression.
15681 .RS 4
15682 .Sp
15683 .Vb 1
15684 \& OP * newNULLLIST()
15685 .Ve
15686 .RE
15687 .RS 4
15688 .RE
15689 .ie n .IP """newOP""" 4
15690 .el .IP \f(CWnewOP\fR 4
15691 .IX Xref "newOP"
15692 .IX Item "newOP"
15693 Constructs, checks, and returns an op of any base type (any type that
15694 has no extra fields). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the
15695 eight bits of \f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits
15696 of \f(CW\*(C`op_private\*(C'\fR.
15697 .RS 4
15698 .Sp
15699 .Vb 1
15700 \& OP * newOP(I32 optype, I32 flags)
15701 .Ve
15702 .RE
15703 .RS 4
15704 .RE
15705 .ie n .IP """newPADOP""" 4
15706 .el .IP \f(CWnewPADOP\fR 4
15707 .IX Xref "newPADOP"
15708 .IX Item "newPADOP"
15709 Constructs, checks, and returns an op of any type that involves a
15710 reference to a pad element. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the
15711 eight bits of \f(CW\*(C`op_flags\*(C'\fR. A pad slot is automatically allocated, and
15712 is populated with \f(CW\*(C`sv\*(C'\fR; this function takes ownership of one reference
15713 to it.
15714 .Sp
15715 This function only exists if Perl has been compiled to use ithreads.
15716 .RS 4
15717 .Sp
15718 .Vb 1
15719 \& OP * newPADOP(I32 type, I32 flags, SV *sv)
15720 .Ve
15721 .RE
15722 .RS 4
15723 .RE
15724 .ie n .IP """newPMOP""" 4
15725 .el .IP \f(CWnewPMOP\fR 4
15726 .IX Xref "newPMOP"
15727 .IX Item "newPMOP"
15728 Constructs, checks, and returns an op of any pattern matching type.
15729 \&\f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR
15730 and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR.
15731 .RS 4
15732 .Sp
15733 .Vb 1
15734 \& OP * newPMOP(I32 type, I32 flags)
15735 .Ve
15736 .RE
15737 .RS 4
15738 .RE
15739 .ie n .IP """newPVOP""" 4
15740 .el .IP \f(CWnewPVOP\fR 4
15741 .IX Xref "newPVOP"
15742 .IX Item "newPVOP"
15743 Constructs, checks, and returns an op of any type that involves an
15744 embedded C\-level pointer (PV). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives
15745 the eight bits of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`pv\*(C'\fR supplies the C\-level pointer.
15746 Depending on the op type, the memory referenced by \f(CW\*(C`pv\*(C'\fR may be freed
15747 when the op is destroyed. If the op is of a freeing type, \f(CW\*(C`pv\*(C'\fR must
15748 have been allocated using \f(CW\*(C`PerlMemShared_malloc\*(C'\fR.
15749 .RS 4
15750 .Sp
15751 .Vb 1
15752 \& OP * newPVOP(I32 type, I32 flags, char *pv)
15753 .Ve
15754 .RE
15755 .RS 4
15756 .RE
15757 .ie n .IP """newRANGE""" 4
15758 .el .IP \f(CWnewRANGE\fR 4
15759 .IX Xref "newRANGE"
15760 .IX Item "newRANGE"
15761 Constructs and returns a \f(CW\*(C`range\*(C'\fR op, with subordinate \f(CW\*(C`flip\*(C'\fR and
15762 \&\f(CW\*(C`flop\*(C'\fR ops. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the
15763 \&\f(CW\*(C`flip\*(C'\fR op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR
15764 for both the \f(CW\*(C`flip\*(C'\fR and \f(CW\*(C`range\*(C'\fR ops, except that the bit with value
15765 1 is automatically set. \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR supply the expressions
15766 controlling the endpoints of the range; they are consumed by this function
15767 and become part of the constructed op tree.
15768 .RS 4
15769 .Sp
15770 .Vb 1
15771 \& OP * newRANGE(I32 flags, OP *left, OP *right)
15772 .Ve
15773 .RE
15774 .RS 4
15775 .RE
15776 .ie n .IP """newSLICEOP""" 4
15777 .el .IP \f(CWnewSLICEOP\fR 4
15778 .IX Xref "newSLICEOP"
15779 .IX Item "newSLICEOP"
15780 Constructs, checks, and returns an \f(CW\*(C`lslice\*(C'\fR (list slice) op. \f(CW\*(C`flags\*(C'\fR
15781 gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will
15782 be set automatically, and, shifted up eight bits, the eight bits of
15783 \&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically
15784 set as required. \f(CW\*(C`listval\*(C'\fR and \f(CW\*(C`subscript\*(C'\fR supply the parameters of
15785 the slice; they are consumed by this function and become part of the
15786 constructed op tree.
15787 .RS 4
15788 .Sp
15789 .Vb 1
15790 \& OP * newSLICEOP(I32 flags, OP *subscript, OP *listop)
15791 .Ve
15792 .RE
15793 .RS 4
15794 .RE
15795 .ie n .IP """newSTATEOP""" 4
15796 .el .IP \f(CWnewSTATEOP\fR 4
15797 .IX Xref "newSTATEOP"
15798 .IX Item "newSTATEOP"
15799 Constructs a state op (COP). The state op is normally a \f(CW\*(C`nextstate\*(C'\fR op,
15800 but will be a \f(CW\*(C`dbstate\*(C'\fR op if debugging is enabled for currently-compiled
15801 code. The state op is populated from \f(CW\*(C`PL_curcop\*(C'\fR (or \f(CW\*(C`PL_compiling\*(C'\fR).
15802 If \f(CW\*(C`label\*(C'\fR is non-null, it supplies the name of a label to attach to
15803 the state op; this function takes ownership of the memory pointed at by
15804 \&\f(CW\*(C`label\*(C'\fR, and will free it. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR
15805 for the state op.
15806 .Sp
15807 If \f(CW\*(C`o\*(C'\fR is null, the state op is returned. Otherwise the state op is
15808 combined with \f(CW\*(C`o\*(C'\fR into a \f(CW\*(C`lineseq\*(C'\fR list op, which is returned. \f(CW\*(C`o\*(C'\fR
15809 is consumed by this function and becomes part of the returned op tree.
15810 .RS 4
15811 .Sp
15812 .Vb 1
15813 \& OP * newSTATEOP(I32 flags, char *label, OP *o)
15814 .Ve
15815 .RE
15816 .RS 4
15817 .RE
15818 .ie n .IP """newSUB""" 4
15819 .el .IP \f(CWnewSUB\fR 4
15820 .IX Xref "newSUB"
15821 .IX Item "newSUB"
15822 Construct a Perl subroutine without attributes, and also performing some
15823 surrounding jobs, returning a pointer to the constructed subroutine.
15824 .Sp
15825 This is the same as "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern with its \f(CW\*(C`o_is_gv\*(C'\fR parameter
15826 set to FALSE, and its \f(CW\*(C`attrs\*(C'\fR parameter to NULL. This means that if \f(CW\*(C`o\*(C'\fR is
15827 null, the new sub will be anonymous; otherwise the name will be derived from
15828 \&\f(CW\*(C`o\*(C'\fR in the way described (as with all other details) in
15829 "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
15830 .RS 4
15831 .Sp
15832 .Vb 1
15833 \& CV * newSUB(I32 floor, OP *o, OP *proto, OP *block)
15834 .Ve
15835 .RE
15836 .RS 4
15837 .RE
15838 .ie n .IP """newSVOP""" 4
15839 .el .IP \f(CWnewSVOP\fR 4
15840 .IX Xref "newSVOP"
15841 .IX Item "newSVOP"
15842 Constructs, checks, and returns an op of any type that involves an
15843 embedded SV. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits
15844 of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`sv\*(C'\fR gives the SV to embed in the op; this function
15845 takes ownership of one reference to it.
15846 .RS 4
15847 .Sp
15848 .Vb 1
15849 \& OP * newSVOP(I32 type, I32 flags, SV *sv)
15850 .Ve
15851 .RE
15852 .RS 4
15853 .RE
15854 .ie n .IP """newSVREF""" 4
15855 .el .IP \f(CWnewSVREF\fR 4
15856 .IX Xref "newSVREF"
15857 .IX Item "newSVREF"
15858 Constructs, checks, and returns a scalar reference op.
15859 .RS 4
15860 .Sp
15861 .Vb 1
15862 \& OP * newSVREF(OP *o)
15863 .Ve
15864 .RE
15865 .RS 4
15866 .RE
15867 .ie n .IP """newTRYCATCHOP""" 4
15868 .el .IP \f(CWnewTRYCATCHOP\fR 4
15869 .IX Xref "newTRYCATCHOP"
15870 .IX Item "newTRYCATCHOP"
15871 NOTE: \f(CW\*(C`newTRYCATCHOP\*(C'\fR is \fBexperimental\fR and may change or be
15872 removed without notice.
15873 .Sp
15874 Constructs and returns a conditional execution statement that implements
15875 the \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR semantics. First the op tree in \f(CW\*(C`tryblock\*(C'\fR is executed,
15876 inside a context that traps exceptions. If an exception occurs then the
15877 optree in \f(CW\*(C`catchblock\*(C'\fR is executed, with the trapped exception set into the
15878 lexical variable given by \f(CW\*(C`catchvar\*(C'\fR (which must be an op of type
15879 \&\f(CW\*(C`OP_PADSV\*(C'\fR). All the optrees are consumed by this function and become part
15880 of the returned op tree.
15881 .Sp
15882 The \f(CW\*(C`flags\*(C'\fR argument is currently ignored.
15883 .RS 4
15884 .Sp
15885 .Vb 2
15886 \& OP * newTRYCATCHOP(I32 flags, OP *tryblock, OP *catchvar,
15887 \& OP *catchblock)
15888 .Ve
15889 .RE
15890 .RS 4
15891 .RE
15892 .ie n .IP """newUNOP""" 4
15893 .el .IP \f(CWnewUNOP\fR 4
15894 .IX Xref "newUNOP"
15895 .IX Item "newUNOP"
15896 Constructs, checks, and returns an op of any unary type. \f(CW\*(C`type\*(C'\fR is
15897 the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
15898 \&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required, and, shifted up eight
15899 bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1
15900 is automatically set. \f(CW\*(C`first\*(C'\fR supplies an optional op to be the direct
15901 child of the unary op; it is consumed by this function and become part
15902 of the constructed op tree.
15903 .RS 4
15904 .Sp
15905 .Vb 1
15906 \& OP * newUNOP(I32 type, I32 flags, OP *first)
15907 .Ve
15908 .RE
15909 .RS 4
15910 .RE
15911 .ie n .IP """newUNOP_AUX""" 4
15912 .el .IP \f(CWnewUNOP_AUX\fR 4
15913 .IX Xref "newUNOP_AUX"
15914 .IX Item "newUNOP_AUX"
15915 Similar to \f(CW\*(C`newUNOP\*(C'\fR, but creates an \f(CW\*(C`UNOP_AUX\*(C'\fR struct instead, with \f(CW\*(C`op_aux\*(C'\fR
15916 initialised to \f(CW\*(C`aux\*(C'\fR
15917 .RS 4
15918 .Sp
15919 .Vb 2
15920 \& OP * newUNOP_AUX(I32 type, I32 flags, OP *first,
15921 \& UNOP_AUX_item *aux)
15922 .Ve
15923 .RE
15924 .RS 4
15925 .RE
15926 .ie n .IP """newWHENOP""" 4
15927 .el .IP \f(CWnewWHENOP\fR 4
15928 .IX Xref "newWHENOP"
15929 .IX Item "newWHENOP"
15930 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`when\*(C'\fR block.
15931 \&\f(CW\*(C`cond\*(C'\fR supplies the test expression, and \f(CW\*(C`block\*(C'\fR supplies the block
15932 that will be executed if the test evaluates to true; they are consumed
15933 by this function and become part of the constructed op tree. \f(CW\*(C`cond\*(C'\fR
15934 will be interpreted DWIMically, often as a comparison against \f(CW$_\fR,
15935 and may be null to generate a \f(CW\*(C`default\*(C'\fR block.
15936 .RS 4
15937 .Sp
15938 .Vb 1
15939 \& OP * newWHENOP(OP *cond, OP *block)
15940 .Ve
15941 .RE
15942 .RS 4
15943 .RE
15944 .ie n .IP """newWHILEOP""" 4
15945 .el .IP \f(CWnewWHILEOP\fR 4
15946 .IX Xref "newWHILEOP"
15947 .IX Item "newWHILEOP"
15948 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`while\*(C'\fR loop.
15949 This is a heavyweight loop, with structure that allows exiting the loop
15950 by \f(CW\*(C`last\*(C'\fR and suchlike.
15951 .Sp
15952 \&\f(CW\*(C`loop\*(C'\fR is an optional preconstructed \f(CW\*(C`enterloop\*(C'\fR op to use in the
15953 loop; if it is null then a suitable op will be constructed automatically.
15954 \&\f(CW\*(C`expr\*(C'\fR supplies the loop's controlling expression. \f(CW\*(C`block\*(C'\fR supplies the
15955 main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR block
15956 that operates as a second half of the body. All of these optree inputs
15957 are consumed by this function and become part of the constructed op tree.
15958 .Sp
15959 \&\f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the \f(CW\*(C`leaveloop\*(C'\fR
15960 op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for
15961 the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set
15962 automatically. \f(CW\*(C`debuggable\*(C'\fR is currently unused and should always be 1.
15963 \&\f(CW\*(C`has_my\*(C'\fR can be supplied as true to force the
15964 loop body to be enclosed in its own scope.
15965 .RS 4
15966 .Sp
15967 .Vb 2
15968 \& OP * newWHILEOP(I32 flags, I32 debuggable, LOOP *loop, OP *expr,
15969 \& OP *block, OP *cont, I32 has_my)
15970 .Ve
15971 .RE
15972 .RS 4
15973 .RE
15974 .ie n .IP """newXS""" 4
15975 .el .IP \f(CWnewXS\fR 4
15976 .IX Xref "newXS"
15977 .IX Item "newXS"
15978 Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. \f(CW\*(C`filename\*(C'\fR needs to be
15979 static storage, as it is used directly as \fBCvFILE()\fR, without a copy being made.
15980 .ie n .IP """OA_BASEOP""" 4
15981 .el .IP \f(CWOA_BASEOP\fR 4
15982 .IX Item "OA_BASEOP"
15983 .PD 0
15984 .ie n .IP """OA_BINOP""" 4
15985 .el .IP \f(CWOA_BINOP\fR 4
15986 .IX Item "OA_BINOP"
15987 .ie n .IP """OA_COP""" 4
15988 .el .IP \f(CWOA_COP\fR 4
15989 .IX Item "OA_COP"
15990 .ie n .IP """OA_LISTOP""" 4
15991 .el .IP \f(CWOA_LISTOP\fR 4
15992 .IX Item "OA_LISTOP"
15993 .ie n .IP """OA_LOGOP""" 4
15994 .el .IP \f(CWOA_LOGOP\fR 4
15995 .IX Item "OA_LOGOP"
15996 .ie n .IP """OA_LOOP""" 4
15997 .el .IP \f(CWOA_LOOP\fR 4
15998 .IX Item "OA_LOOP"
15999 .ie n .IP """OA_PADOP""" 4
16000 .el .IP \f(CWOA_PADOP\fR 4
16001 .IX Item "OA_PADOP"
16002 .ie n .IP """OA_PMOP""" 4
16003 .el .IP \f(CWOA_PMOP\fR 4
16004 .IX Item "OA_PMOP"
16005 .ie n .IP """OA_PVOP_OR_SVOP""" 4
16006 .el .IP \f(CWOA_PVOP_OR_SVOP\fR 4
16007 .IX Item "OA_PVOP_OR_SVOP"
16008 .ie n .IP """OA_SVOP""" 4
16009 .el .IP \f(CWOA_SVOP\fR 4
16010 .IX Item "OA_SVOP"
16011 .ie n .IP """OA_UNOP""" 4
16012 .el .IP \f(CWOA_UNOP\fR 4
16013 .IX Item "OA_UNOP"
16014 .PD
16015 Described in perlguts.
16016 .ie n .IP """OP""" 4
16017 .el .IP \f(CWOP\fR 4
16018 .IX Item "OP"
16019 Described in perlguts.
16020 .ie n .IP """op_append_elem""" 4
16021 .el .IP \f(CWop_append_elem\fR 4
16022 .IX Xref "op_append_elem"
16023 .IX Item "op_append_elem"
16024 Append an item to the list of ops contained directly within a list-type
16025 op, returning the lengthened list. \f(CW\*(C`first\*(C'\fR is the list-type op,
16026 and \f(CW\*(C`last\*(C'\fR is the op to append to the list. \f(CW\*(C`optype\*(C'\fR specifies the
16027 intended opcode for the list. If \f(CW\*(C`first\*(C'\fR is not already a list of the
16028 right type, it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR
16029 is null, the other is returned unchanged.
16030 .RS 4
16031 .Sp
16032 .Vb 1
16033 \& OP * op_append_elem(I32 optype, OP *first, OP *last)
16034 .Ve
16035 .RE
16036 .RS 4
16037 .RE
16038 .ie n .IP """op_append_list""" 4
16039 .el .IP \f(CWop_append_list\fR 4
16040 .IX Xref "op_append_list"
16041 .IX Item "op_append_list"
16042 Concatenate the lists of ops contained directly within two list-type ops,
16043 returning the combined list. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR are the list-type ops
16044 to concatenate. \f(CW\*(C`optype\*(C'\fR specifies the intended opcode for the list.
16045 If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is not already a list of the right type,
16046 it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null,
16047 the other is returned unchanged.
16048 .RS 4
16049 .Sp
16050 .Vb 1
16051 \& OP * op_append_list(I32 optype, OP *first, OP *last)
16052 .Ve
16053 .RE
16054 .RS 4
16055 .RE
16056 .ie n .IP """OP_CLASS""" 4
16057 .el .IP \f(CWOP_CLASS\fR 4
16058 .IX Xref "OP_CLASS"
16059 .IX Item "OP_CLASS"
16060 Return the class of the provided OP: that is, which of the *OP
16061 structures it uses. For core ops this currently gets the information out
16062 of \f(CW\*(C`PL_opargs\*(C'\fR, which does not always accurately reflect the type used;
16063 in v5.26 onwards, see also the function \f(CW"op_class"\fR which can do a better
16064 job of determining the used type.
16065 .Sp
16066 For custom ops the type is returned from the registration, and it is up
16067 to the registree to ensure it is accurate. The value returned will be
16068 one of the \f(CW\*(C`OA_\*(C'\fR* constants from \fIop.h\fR.
16069 .RS 4
16070 .Sp
16071 .Vb 1
16072 \& U32 OP_CLASS(OP *o)
16073 .Ve
16074 .RE
16075 .RS 4
16076 .RE
16077 .ie n .IP """op_contextualize""" 4
16078 .el .IP \f(CWop_contextualize\fR 4
16079 .IX Xref "op_contextualize"
16080 .IX Item "op_contextualize"
16081 Applies a syntactic context to an op tree representing an expression.
16082 \&\f(CW\*(C`o\*(C'\fR is the op tree, and \f(CW\*(C`context\*(C'\fR must be \f(CW\*(C`G_SCALAR\*(C'\fR, \f(CW\*(C`G_LIST\*(C'\fR,
16083 or \f(CW\*(C`G_VOID\*(C'\fR to specify the context to apply. The modified op tree
16084 is returned.
16085 .RS 4
16086 .Sp
16087 .Vb 1
16088 \& OP * op_contextualize(OP *o, I32 context)
16089 .Ve
16090 .RE
16091 .RS 4
16092 .RE
16093 .ie n .IP """op_convert_list""" 4
16094 .el .IP \f(CWop_convert_list\fR 4
16095 .IX Xref "op_convert_list"
16096 .IX Item "op_convert_list"
16097 Converts \f(CW\*(C`o\*(C'\fR into a list op if it is not one already, and then converts it
16098 into the specified \f(CW\*(C`type\*(C'\fR, calling its check function, allocating a target if
16099 it needs one, and folding constants.
16100 .Sp
16101 A list-type op is usually constructed one kid at a time via \f(CW\*(C`newLISTOP\*(C'\fR,
16102 \&\f(CW\*(C`op_prepend_elem\*(C'\fR and \f(CW\*(C`op_append_elem\*(C'\fR. Then finally it is passed to
16103 \&\f(CW\*(C`op_convert_list\*(C'\fR to make it the right type.
16104 .RS 4
16105 .Sp
16106 .Vb 1
16107 \& OP * op_convert_list(I32 optype, I32 flags, OP *o)
16108 .Ve
16109 .RE
16110 .RS 4
16111 .RE
16112 .ie n .IP """OP_DESC""" 4
16113 .el .IP \f(CWOP_DESC\fR 4
16114 .IX Xref "OP_DESC"
16115 .IX Item "OP_DESC"
16116 Return a short description of the provided OP.
16117 .RS 4
16118 .Sp
16119 .Vb 1
16120 \& const char * OP_DESC(OP *o)
16121 .Ve
16122 .RE
16123 .RS 4
16124 .RE
16125 .ie n .IP """op_force_list""" 4
16126 .el .IP \f(CWop_force_list\fR 4
16127 .IX Xref "op_force_list"
16128 .IX Item "op_force_list"
16129 Promotes o and any siblings to be an \f(CW\*(C`OP_LIST\*(C'\fR if it is not already. If
16130 a new \f(CW\*(C`OP_LIST\*(C'\fR op was created, its first child will be \f(CW\*(C`OP_PUSHMARK\*(C'\fR.
16131 The returned node itself will be nulled, leaving only its children.
16132 .Sp
16133 This is often what you want to do before putting the optree into list
16134 context; as
16135 .Sp
16136 .Vb 1
16137 \& o = op_contextualize(op_force_list(o), G_LIST);
16138 .Ve
16139 .RS 4
16140 .Sp
16141 .Vb 1
16142 \& OP * op_force_list(OP *o)
16143 .Ve
16144 .RE
16145 .RS 4
16146 .RE
16147 .ie n .IP """op_free""" 4
16148 .el .IP \f(CWop_free\fR 4
16149 .IX Xref "op_free"
16150 .IX Item "op_free"
16151 Free an op and its children. Only use this when an op is no longer linked
16152 to from any optree.
16153 .Sp
16154 Remember that any op with \f(CW\*(C`OPf_KIDS\*(C'\fR set is expected to have a valid
16155 \&\f(CW\*(C`op_first\*(C'\fR pointer. If you are attempting to free an op but preserve its
16156 child op, make sure to clear that flag before calling \f(CWop_free()\fR. For
16157 example:
16158 .Sp
16159 .Vb 3
16160 \& OP *kid = o\->op_first; o\->op_first = NULL;
16161 \& o\->op_flags &= ~OPf_KIDS;
16162 \& op_free(o);
16163 .Ve
16164 .RS 4
16165 .Sp
16166 .Vb 1
16167 \& void op_free(OP *arg)
16168 .Ve
16169 .RE
16170 .RS 4
16171 .RE
16172 .ie n .IP """OpHAS_SIBLING""" 4
16173 .el .IP \f(CWOpHAS_SIBLING\fR 4
16174 .IX Xref "OpHAS_SIBLING"
16175 .IX Item "OpHAS_SIBLING"
16176 Returns true if \f(CW\*(C`o\*(C'\fR has a sibling
16177 .RS 4
16178 .Sp
16179 .Vb 1
16180 \& bool OpHAS_SIBLING(OP *o)
16181 .Ve
16182 .RE
16183 .RS 4
16184 .RE
16185 .ie n .IP """OpLASTSIB_set""" 4
16186 .el .IP \f(CWOpLASTSIB_set\fR 4
16187 .IX Xref "OpLASTSIB_set"
16188 .IX Item "OpLASTSIB_set"
16189 Marks \f(CW\*(C`o\*(C'\fR as having no further siblings and marks
16190 o as having the specified parent. See also \f(CW"OpMORESIB_set"\fR and
16191 \&\f(CW\*(C`OpMAYBESIB_set\*(C'\fR. For a higher-level interface, see
16192 \&\f(CW"op_sibling_splice"\fR.
16193 .RS 4
16194 .Sp
16195 .Vb 1
16196 \& void OpLASTSIB_set(OP *o, OP *parent)
16197 .Ve
16198 .RE
16199 .RS 4
16200 .RE
16201 .ie n .IP """op_linklist""" 4
16202 .el .IP \f(CWop_linklist\fR 4
16203 .IX Xref "op_linklist"
16204 .IX Item "op_linklist"
16205 This function is the implementation of the "LINKLIST" macro. It should
16206 not be called directly.
16207 .RS 4
16208 .Sp
16209 .Vb 1
16210 \& OP * op_linklist(OP *o)
16211 .Ve
16212 .RE
16213 .RS 4
16214 .RE
16215 .ie n .IP """op_lvalue""" 4
16216 .el .IP \f(CWop_lvalue\fR 4
16217 .IX Xref "op_lvalue"
16218 .IX Item "op_lvalue"
16219 NOTE: \f(CW\*(C`op_lvalue\*(C'\fR is \fBexperimental\fR and may change or be
16220 removed without notice.
16221 .Sp
16222 Propagate lvalue ("modifiable") context to an op and its children.
16223 \&\f(CW\*(C`type\*(C'\fR represents the context type, roughly based on the type of op that
16224 would do the modifying, although \f(CWlocal()\fR is represented by \f(CW\*(C`OP_NULL\*(C'\fR,
16225 because it has no op type of its own (it is signalled by a flag on
16226 the lvalue op).
16227 .Sp
16228 This function detects things that can't be modified, such as \f(CW\*(C`$x+1\*(C'\fR, and
16229 generates errors for them. For example, \f(CW\*(C`$x+1 = 2\*(C'\fR would cause it to be
16230 called with an op of type \f(CW\*(C`OP_ADD\*(C'\fR and a \f(CW\*(C`type\*(C'\fR argument of \f(CW\*(C`OP_SASSIGN\*(C'\fR.
16231 .Sp
16232 It also flags things that need to behave specially in an lvalue context,
16233 such as \f(CW\*(C`$$x = 5\*(C'\fR which might have to vivify a reference in \f(CW$x\fR.
16234 .RS 4
16235 .Sp
16236 .Vb 1
16237 \& OP * op_lvalue(OP *o, I32 type)
16238 .Ve
16239 .RE
16240 .RS 4
16241 .RE
16242 .ie n .IP """OpMAYBESIB_set""" 4
16243 .el .IP \f(CWOpMAYBESIB_set\fR 4
16244 .IX Xref "OpMAYBESIB_set"
16245 .IX Item "OpMAYBESIB_set"
16246 Conditionally does \f(CW\*(C`OpMORESIB_set\*(C'\fR or \f(CW\*(C`OpLASTSIB_set\*(C'\fR depending on whether
16247 \&\f(CW\*(C`sib\*(C'\fR is non-null. For a higher-level interface, see \f(CW"op_sibling_splice"\fR.
16248 .RS 4
16249 .Sp
16250 .Vb 1
16251 \& void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
16252 .Ve
16253 .RE
16254 .RS 4
16255 .RE
16256 .ie n .IP """OpMORESIB_set""" 4
16257 .el .IP \f(CWOpMORESIB_set\fR 4
16258 .IX Xref "OpMORESIB_set"
16259 .IX Item "OpMORESIB_set"
16260 Sets the sibling of \f(CW\*(C`o\*(C'\fR to the non-zero value \f(CW\*(C`sib\*(C'\fR. See also \f(CW"OpLASTSIB_set"\fR
16261 and \f(CW"OpMAYBESIB_set"\fR. For a higher-level interface, see
16262 \&\f(CW"op_sibling_splice"\fR.
16263 .RS 4
16264 .Sp
16265 .Vb 1
16266 \& void OpMORESIB_set(OP *o, OP *sib)
16267 .Ve
16268 .RE
16269 .RS 4
16270 .RE
16271 .ie n .IP """OP_NAME""" 4
16272 .el .IP \f(CWOP_NAME\fR 4
16273 .IX Xref "OP_NAME"
16274 .IX Item "OP_NAME"
16275 Return the name of the provided OP. For core ops this looks up the name
16276 from the op_type; for custom ops from the op_ppaddr.
16277 .RS 4
16278 .Sp
16279 .Vb 1
16280 \& const char * OP_NAME(OP *o)
16281 .Ve
16282 .RE
16283 .RS 4
16284 .RE
16285 .ie n .IP """op_null""" 4
16286 .el .IP \f(CWop_null\fR 4
16287 .IX Xref "op_null"
16288 .IX Item "op_null"
16289 Neutralizes an op when it is no longer needed, but is still linked to from
16290 other ops.
16291 .RS 4
16292 .Sp
16293 .Vb 1
16294 \& void op_null(OP *o)
16295 .Ve
16296 .RE
16297 .RS 4
16298 .RE
16299 .ie n .IP """op_parent""" 4
16300 .el .IP \f(CWop_parent\fR 4
16301 .IX Xref "op_parent"
16302 .IX Item "op_parent"
16303 Returns the parent OP of \f(CW\*(C`o\*(C'\fR, if it has a parent. Returns \f(CW\*(C`NULL\*(C'\fR otherwise.
16304 .RS 4
16305 .Sp
16306 .Vb 1
16307 \& OP * op_parent(OP *o)
16308 .Ve
16309 .RE
16310 .RS 4
16311 .RE
16312 .ie n .IP """op_prepend_elem""" 4
16313 .el .IP \f(CWop_prepend_elem\fR 4
16314 .IX Xref "op_prepend_elem"
16315 .IX Item "op_prepend_elem"
16316 Prepend an item to the list of ops contained directly within a list-type
16317 op, returning the lengthened list. \f(CW\*(C`first\*(C'\fR is the op to prepend to the
16318 list, and \f(CW\*(C`last\*(C'\fR is the list-type op. \f(CW\*(C`optype\*(C'\fR specifies the intended
16319 opcode for the list. If \f(CW\*(C`last\*(C'\fR is not already a list of the right type,
16320 it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null,
16321 the other is returned unchanged.
16322 .RS 4
16323 .Sp
16324 .Vb 1
16325 \& OP * op_prepend_elem(I32 optype, OP *first, OP *last)
16326 .Ve
16327 .RE
16328 .RS 4
16329 .RE
16330 .ie n .IP """op_scope""" 4
16331 .el .IP \f(CWop_scope\fR 4
16332 .IX Xref "op_scope"
16333 .IX Item "op_scope"
16334 NOTE: \f(CW\*(C`op_scope\*(C'\fR is \fBexperimental\fR and may change or be
16335 removed without notice.
16336 .Sp
16337 Wraps up an op tree with some additional ops so that at runtime a dynamic
16338 scope will be created. The original ops run in the new dynamic scope,
16339 and then, provided that they exit normally, the scope will be unwound.
16340 The additional ops used to create and unwind the dynamic scope will
16341 normally be an \f(CW\*(C`enter\*(C'\fR/\f(CW\*(C`leave\*(C'\fR pair, but a \f(CW\*(C`scope\*(C'\fR op may be used
16342 instead if the ops are simple enough to not need the full dynamic scope
16343 structure.
16344 .RS 4
16345 .Sp
16346 .Vb 1
16347 \& OP * op_scope(OP *o)
16348 .Ve
16349 .RE
16350 .RS 4
16351 .RE
16352 .ie n .IP """OpSIBLING""" 4
16353 .el .IP \f(CWOpSIBLING\fR 4
16354 .IX Xref "OpSIBLING"
16355 .IX Item "OpSIBLING"
16356 Returns the sibling of \f(CW\*(C`o\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if there is no sibling
16357 .RS 4
16358 .Sp
16359 .Vb 1
16360 \& OP* OpSIBLING(OP *o)
16361 .Ve
16362 .RE
16363 .RS 4
16364 .RE
16365 .ie n .IP """op_sibling_splice""" 4
16366 .el .IP \f(CWop_sibling_splice\fR 4
16367 .IX Xref "op_sibling_splice"
16368 .IX Item "op_sibling_splice"
16369 A general function for editing the structure of an existing chain of
16370 op_sibling nodes. By analogy with the perl-level \f(CWsplice()\fR function, allows
16371 you to delete zero or more sequential nodes, replacing them with zero or
16372 more different nodes. Performs the necessary op_first/op_last
16373 housekeeping on the parent node and op_sibling manipulation on the
16374 children. The last deleted node will be marked as the last node by
16375 updating the op_sibling/op_sibparent or op_moresib field as appropriate.
16376 .Sp
16377 Note that op_next is not manipulated, and nodes are not freed; that is the
16378 responsibility of the caller. It also won't create a new list op for an
16379 empty list etc; use higher-level functions like \fBop_append_elem()\fR for that.
16380 .Sp
16381 \&\f(CW\*(C`parent\*(C'\fR is the parent node of the sibling chain. It may passed as \f(CW\*(C`NULL\*(C'\fR if
16382 the splicing doesn't affect the first or last op in the chain.
16383 .Sp
16384 \&\f(CW\*(C`start\*(C'\fR is the node preceding the first node to be spliced. Node(s)
16385 following it will be deleted, and ops will be inserted after it. If it is
16386 \&\f(CW\*(C`NULL\*(C'\fR, the first node onwards is deleted, and nodes are inserted at the
16387 beginning.
16388 .Sp
16389 \&\f(CW\*(C`del_count\*(C'\fR is the number of nodes to delete. If zero, no nodes are deleted.
16390 If \-1 or greater than or equal to the number of remaining kids, all
16391 remaining kids are deleted.
16392 .Sp
16393 \&\f(CW\*(C`insert\*(C'\fR is the first of a chain of nodes to be inserted in place of the nodes.
16394 If \f(CW\*(C`NULL\*(C'\fR, no nodes are inserted.
16395 .Sp
16396 The head of the chain of deleted ops is returned, or \f(CW\*(C`NULL\*(C'\fR if no ops were
16397 deleted.
16398 .Sp
16399 For example:
16400 .Sp
16401 .Vb 2
16402 \& action before after returns
16403 \& \-\-\-\-\-\- \-\-\-\-\- \-\-\-\-\- \-\-\-\-\-\-\-
16404 \&
16405 \& P P
16406 \& splice(P, A, 2, X\-Y\-Z) | | B\-C
16407 \& A\-B\-C\-D A\-X\-Y\-Z\-D
16408 \&
16409 \& P P
16410 \& splice(P, NULL, 1, X\-Y) | | A
16411 \& A\-B\-C\-D X\-Y\-B\-C\-D
16412 \&
16413 \& P P
16414 \& splice(P, NULL, 3, NULL) | | A\-B\-C
16415 \& A\-B\-C\-D D
16416 \&
16417 \& P P
16418 \& splice(P, B, 0, X\-Y) | | NULL
16419 \& A\-B\-C\-D A\-B\-X\-Y\-C\-D
16420 .Ve
16421 .Sp
16422 For lower-level direct manipulation of \f(CW\*(C`op_sibparent\*(C'\fR and \f(CW\*(C`op_moresib\*(C'\fR,
16423 see \f(CW"OpMORESIB_set"\fR, \f(CW"OpLASTSIB_set"\fR, \f(CW"OpMAYBESIB_set"\fR.
16424 .RS 4
16425 .Sp
16426 .Vb 2
16427 \& OP * op_sibling_splice(OP *parent, OP *start, int del_count,
16428 \& OP *insert)
16429 .Ve
16430 .RE
16431 .RS 4
16432 .RE
16433 .ie n .IP """optimize_optree""" 4
16434 .el .IP \f(CWoptimize_optree\fR 4
16435 .IX Xref "optimize_optree"
16436 .IX Item "optimize_optree"
16437 This function applies some optimisations to the optree in top-down order.
16438 It is called before the peephole optimizer, which processes ops in
16439 execution order. Note that \fBfinalize_optree()\fR also does a top-down scan,
16440 but is called *after* the peephole optimizer.
16441 .RS 4
16442 .Sp
16443 .Vb 1
16444 \& void optimize_optree(OP *o)
16445 .Ve
16446 .RE
16447 .RS 4
16448 .RE
16449 .ie n .IP """OP_TYPE_IS""" 4
16450 .el .IP \f(CWOP_TYPE_IS\fR 4
16451 .IX Xref "OP_TYPE_IS"
16452 .IX Item "OP_TYPE_IS"
16453 Returns true if the given OP is not a \f(CW\*(C`NULL\*(C'\fR pointer
16454 and if it is of the given type.
16455 .Sp
16456 The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT\*(C'\fR is also available
16457 as well as \f(CW\*(C`OP_TYPE_IS_NN\*(C'\fR and \f(CW\*(C`OP_TYPE_ISNT_NN\*(C'\fR which elide
16458 the NULL pointer check.
16459 .RS 4
16460 .Sp
16461 .Vb 1
16462 \& bool OP_TYPE_IS(OP *o, Optype type)
16463 .Ve
16464 .RE
16465 .RS 4
16466 .RE
16467 .ie n .IP """OP_TYPE_IS_OR_WAS""" 4
16468 .el .IP \f(CWOP_TYPE_IS_OR_WAS\fR 4
16469 .IX Xref "OP_TYPE_IS_OR_WAS"
16470 .IX Item "OP_TYPE_IS_OR_WAS"
16471 Returns true if the given OP is not a NULL pointer and
16472 if it is of the given type or used to be before being
16473 replaced by an OP of type OP_NULL.
16474 .Sp
16475 The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT\*(C'\fR
16476 is also available as well as \f(CW\*(C`OP_TYPE_IS_OR_WAS_NN\*(C'\fR
16477 and \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT_NN\*(C'\fR which elide
16478 the \f(CW\*(C`NULL\*(C'\fR pointer check.
16479 .RS 4
16480 .Sp
16481 .Vb 1
16482 \& bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
16483 .Ve
16484 .RE
16485 .RS 4
16486 .RE
16487 .ie n .IP """op_wrap_finally""" 4
16488 .el .IP \f(CWop_wrap_finally\fR 4
16489 .IX Xref "op_wrap_finally"
16490 .IX Item "op_wrap_finally"
16491 NOTE: \f(CW\*(C`op_wrap_finally\*(C'\fR is \fBexperimental\fR and may change or be
16492 removed without notice.
16493 .Sp
16494 Wraps the given \f(CW\*(C`block\*(C'\fR optree fragment in its own scoped block, arranging
16495 for the \f(CW\*(C`finally\*(C'\fR optree fragment to be invoked when leaving that block for
16496 any reason. Both optree fragments are consumed and the combined result is
16497 returned.
16498 .RS 4
16499 .Sp
16500 .Vb 1
16501 \& OP * op_wrap_finally(OP *block, OP *finally)
16502 .Ve
16503 .RE
16504 .RS 4
16505 .RE
16506 .ie n .IP """peep_t""" 4
16507 .el .IP \f(CWpeep_t\fR 4
16508 .IX Item "peep_t"
16509 Described in perlguts.
16510 .ie n .IP """Perl_cpeep_t""" 4
16511 .el .IP \f(CWPerl_cpeep_t\fR 4
16512 .IX Item "Perl_cpeep_t"
16513 Described in perlguts.
16514 .ie n .IP """PL_opfreehook""" 4
16515 .el .IP \f(CWPL_opfreehook\fR 4
16516 .IX Xref "PL_opfreehook"
16517 .IX Item "PL_opfreehook"
16518 When non\-\f(CW\*(C`NULL\*(C'\fR, the function pointed by this variable will be called each time an OP is freed with the corresponding OP as the argument.
16519 This allows extensions to free any extra attribute they have locally attached to an OP.
16520 It is also assured to first fire for the parent OP and then for its kids.
16521 .Sp
16522 When you replace this variable, it is considered a good practice to store the possibly previously installed hook and that you recall it inside your own.
16523 .Sp
16524 On threaded perls, each thread has an independent copy of this variable;
16525 each initialized at creation time with the current value of the creating
16526 thread's copy.
16527 .RS 4
16528 .Sp
16529 .Vb 1
16530 \& Perl_ophook_t PL_opfreehook
16531 .Ve
16532 .RE
16533 .RS 4
16534 .RE
16535 .ie n .IP """PL_peepp""" 4
16536 .el .IP \f(CWPL_peepp\fR 4
16537 .IX Xref "PL_peepp"
16538 .IX Item "PL_peepp"
16539 Pointer to the per-subroutine peephole optimiser. This is a function
16540 that gets called at the end of compilation of a Perl subroutine (or
16541 equivalently independent piece of Perl code) to perform fixups of
16542 some ops and to perform small-scale optimisations. The function is
16543 called once for each subroutine that is compiled, and is passed, as sole
16544 parameter, a pointer to the op that is the entry point to the subroutine.
16545 It modifies the op tree in place.
16546 .Sp
16547 The peephole optimiser should never be completely replaced. Rather,
16548 add code to it by wrapping the existing optimiser. The basic way to do
16549 this can be seen in "Compile pass 3: peephole optimization" in perlguts.
16550 If the new code wishes to operate on ops throughout the subroutine's
16551 structure, rather than just at the top level, it is likely to be more
16552 convenient to wrap the "PL_rpeepp" hook.
16553 .Sp
16554 On threaded perls, each thread has an independent copy of this variable;
16555 each initialized at creation time with the current value of the creating
16556 thread's copy.
16557 .RS 4
16558 .Sp
16559 .Vb 1
16560 \& peep_t PL_peepp
16561 .Ve
16562 .RE
16563 .RS 4
16564 .RE
16565 .ie n .IP """PL_rpeepp""" 4
16566 .el .IP \f(CWPL_rpeepp\fR 4
16567 .IX Xref "PL_rpeepp"
16568 .IX Item "PL_rpeepp"
16569 Pointer to the recursive peephole optimiser. This is a function
16570 that gets called at the end of compilation of a Perl subroutine (or
16571 equivalently independent piece of Perl code) to perform fixups of some
16572 ops and to perform small-scale optimisations. The function is called
16573 once for each chain of ops linked through their \f(CW\*(C`op_next\*(C'\fR fields;
16574 it is recursively called to handle each side chain. It is passed, as
16575 sole parameter, a pointer to the op that is at the head of the chain.
16576 It modifies the op tree in place.
16577 .Sp
16578 The peephole optimiser should never be completely replaced. Rather,
16579 add code to it by wrapping the existing optimiser. The basic way to do
16580 this can be seen in "Compile pass 3: peephole optimization" in perlguts.
16581 If the new code wishes to operate only on ops at a subroutine's top level,
16582 rather than throughout the structure, it is likely to be more convenient
16583 to wrap the "PL_peepp" hook.
16584 .Sp
16585 On threaded perls, each thread has an independent copy of this variable;
16586 each initialized at creation time with the current value of the creating
16587 thread's copy.
16588 .RS 4
16589 .Sp
16590 .Vb 1
16591 \& peep_t PL_rpeepp
16592 .Ve
16593 .RE
16594 .RS 4
16595 .RE
16596 .ie n .IP """PMOP""" 4
16597 .el .IP \f(CWPMOP\fR 4
16598 .IX Item "PMOP"
16599 Described in perlguts.
16600 .ie n .IP """rv2cv_op_cv""" 4
16601 .el .IP \f(CWrv2cv_op_cv\fR 4
16602 .IX Xref "rv2cv_op_cv"
16603 .IX Item "rv2cv_op_cv"
16604 Examines an op, which is expected to identify a subroutine at runtime,
16605 and attempts to determine at compile time which subroutine it identifies.
16606 This is normally used during Perl compilation to determine whether
16607 a prototype can be applied to a function call. \f(CW\*(C`cvop\*(C'\fR is the op
16608 being considered, normally an \f(CW\*(C`rv2cv\*(C'\fR op. A pointer to the identified
16609 subroutine is returned, if it could be determined statically, and a null
16610 pointer is returned if it was not possible to determine statically.
16611 .Sp
16612 Currently, the subroutine can be identified statically if the RV that the
16613 \&\f(CW\*(C`rv2cv\*(C'\fR is to operate on is provided by a suitable \f(CW\*(C`gv\*(C'\fR or \f(CW\*(C`const\*(C'\fR op.
16614 A \f(CW\*(C`gv\*(C'\fR op is suitable if the GV's CV slot is populated. A \f(CW\*(C`const\*(C'\fR op is
16615 suitable if the constant value must be an RV pointing to a CV. Details of
16616 this process may change in future versions of Perl. If the \f(CW\*(C`rv2cv\*(C'\fR op
16617 has the \f(CW\*(C`OPpENTERSUB_AMPER\*(C'\fR flag set then no attempt is made to identify
16618 the subroutine statically: this flag is used to suppress compile-time
16619 magic on a subroutine call, forcing it to use default runtime behaviour.
16620 .Sp
16621 If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_MARK_EARLY\*(C'\fR set, then the handling
16622 of a GV reference is modified. If a GV was examined and its CV slot was
16623 found to be empty, then the \f(CW\*(C`gv\*(C'\fR op has the \f(CW\*(C`OPpEARLY_CV\*(C'\fR flag set.
16624 If the op is not optimised away, and the CV slot is later populated with
16625 a subroutine having a prototype, that flag eventually triggers the warning
16626 "called too early to check prototype".
16627 .Sp
16628 If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_RETURN_NAME_GV\*(C'\fR set, then instead
16629 of returning a pointer to the subroutine it returns a pointer to the
16630 GV giving the most appropriate name for the subroutine in this context.
16631 Normally this is just the \f(CW\*(C`CvGV\*(C'\fR of the subroutine, but for an anonymous
16632 (\f(CW\*(C`CvANON\*(C'\fR) subroutine that is referenced through a GV it will be the
16633 referencing GV. The resulting \f(CW\*(C`GV*\*(C'\fR is cast to \f(CW\*(C`CV*\*(C'\fR to be returned.
16634 A null pointer is returned as usual if there is no statically-determinable
16635 subroutine.
16636 .RS 4
16637 .Sp
16638 .Vb 1
16639 \& CV * rv2cv_op_cv(OP *cvop, U32 flags)
16640 .Ve
16641 .RE
16642 .RS 4
16643 .RE
16644 .ie n .IP """UNOP""" 4
16645 .el .IP \f(CWUNOP\fR 4
16646 .IX Item "UNOP"
16647 Described in perlguts.
16648 .ie n .IP """XOP""" 4
16649 .el .IP \f(CWXOP\fR 4
16650 .IX Item "XOP"
16651 Described in perlguts.
16652 .SH "Pack and Unpack"
16653 .IX Header "Pack and Unpack"
16654 .ie n .IP """packlist""" 4
16655 .el .IP \f(CWpacklist\fR 4
16656 .IX Xref "packlist"
16657 .IX Item "packlist"
16658 The engine implementing \f(CWpack()\fR Perl function.
16659 .RS 4
16660 .Sp
16661 .Vb 2
16662 \& void packlist(SV *cat, const char *pat, const char *patend,
16663 \& SV **beglist, SV **endlist)
16664 .Ve
16665 .RE
16666 .RS 4
16667 .RE
16668 .ie n .IP """unpackstring""" 4
16669 .el .IP \f(CWunpackstring\fR 4
16670 .IX Xref "unpackstring"
16671 .IX Item "unpackstring"
16672 The engine implementing the \f(CWunpack()\fR Perl function.
16673 .Sp
16674 Using the template \f(CW\*(C`pat..patend\*(C'\fR, this function unpacks the string
16675 \&\f(CW\*(C`s..strend\*(C'\fR into a number of mortal SVs, which it pushes onto the perl
16676 argument (\f(CW@_\fR) stack (so you will need to issue a \f(CW\*(C`PUTBACK\*(C'\fR before and
16677 \&\f(CW\*(C`SPAGAIN\*(C'\fR after the call to this function). It returns the number of
16678 pushed elements.
16679 .Sp
16680 The \f(CW\*(C`strend\*(C'\fR and \f(CW\*(C`patend\*(C'\fR pointers should point to the byte following the
16681 last character of each string.
16682 .Sp
16683 Although this function returns its values on the perl argument stack, it
16684 doesn't take any parameters from that stack (and thus in particular
16685 there's no need to do a \f(CW\*(C`PUSHMARK\*(C'\fR before calling it, unlike "call_pv" for
16686 example).
16687 .RS 4
16688 .Sp
16689 .Vb 3
16690 \& SSize_t unpackstring(const char *pat, const char *patend,
16691 \& const char *s, const char *strend,
16692 \& U32 flags)
16693 .Ve
16694 .RE
16695 .RS 4
16696 .RE
16697 .SH "Pad Data Structures"
16698 .IX Xref "SVs_PADSTALE"
16699 .IX Header "Pad Data Structures"
16700 .ie n .IP """CvPADLIST""" 4
16701 .el .IP \f(CWCvPADLIST\fR 4
16702 .IX Xref "CvPADLIST"
16703 .IX Item "CvPADLIST"
16704 NOTE: \f(CW\*(C`CvPADLIST\*(C'\fR is \fBexperimental\fR and may change or be
16705 removed without notice.
16706 .Sp
16707 CV's can have CvPADLIST(cv) set to point to a PADLIST. This is the CV's
16708 scratchpad, which stores lexical variables and opcode temporary and
16709 per-thread values.
16710 .Sp
16711 For these purposes "formats" are a kind-of CV; eval""s are too (except they're
16712 not callable at will and are always thrown away after the eval"" is done
16713 executing). Require'd files are simply evals without any outer lexical
16714 scope.
16715 .Sp
16716 XSUBs do not have a \f(CW\*(C`CvPADLIST\*(C'\fR. \f(CW\*(C`dXSTARG\*(C'\fR fetches values from \f(CW\*(C`PL_curpad\*(C'\fR,
16717 but that is really the callers pad (a slot of which is allocated by
16718 every entersub). Do not get or set \f(CW\*(C`CvPADLIST\*(C'\fR if a CV is an XSUB (as
16719 determined by \f(CWCvISXSUB()\fR), \f(CW\*(C`CvPADLIST\*(C'\fR slot is reused for a different
16720 internal purpose in XSUBs.
16721 .Sp
16722 The PADLIST has a C array where pads are stored.
16723 .Sp
16724 The 0th entry of the PADLIST is a PADNAMELIST
16725 which represents the "names" or rather
16726 the "static type information" for lexicals. The individual elements of a
16727 PADNAMELIST are PADNAMEs. Future
16728 refactorings might stop the PADNAMELIST from being stored in the PADLIST's
16729 array, so don't rely on it. See "PadlistNAMES".
16730 .Sp
16731 The CvDEPTH'th entry of a PADLIST is a PAD (an AV) which is the stack frame
16732 at that depth of recursion into the CV. The 0th slot of a frame AV is an
16733 AV which is \f(CW@_\fR. Other entries are storage for variables and op targets.
16734 .Sp
16735 Iterating over the PADNAMELIST iterates over all possible pad
16736 items. Pad slots for targets (\f(CW\*(C`SVs_PADTMP\*(C'\fR)
16737 and GVs end up having &PL_padname_undef "names", while slots for constants
16738 have \f(CW&PL_padname_const\fR "names" (see \f(CW"pad_alloc"\fR). That
16739 \&\f(CW&PL_padname_undef\fR
16740 and \f(CW&PL_padname_const\fR are used is an implementation detail subject to
16741 change. To test for them, use \f(CW\*(C`!PadnamePV(name)\*(C'\fR and
16742 \&\f(CW\*(C`PadnamePV(name)\ &&\ !PadnameLEN(name)\*(C'\fR, respectively.
16743 .Sp
16744 Only \f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variable slots get valid names.
16745 The rest are op targets/GVs/constants which are statically allocated
16746 or resolved at compile time. These don't have names by which they
16747 can be looked up from Perl code at run time through eval"" the way
16748 \&\f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variables can be. Since they can't be looked up by "name"
16749 but only by their index allocated at compile time (which is usually
16750 in \f(CW\*(C`PL_op\->op_targ\*(C'\fR), wasting a name SV for them doesn't make sense.
16751 .Sp
16752 The pad names in the PADNAMELIST have their PV holding the name of
16753 the variable. The \f(CW\*(C`COP_SEQ_RANGE_LOW\*(C'\fR and \f(CW\*(C`_HIGH\*(C'\fR fields form a range
16754 (low+1..high inclusive) of cop_seq numbers for which the name is
16755 valid. During compilation, these fields may hold the special value
16756 PERL_PADSEQ_INTRO to indicate various stages:
16757 .Sp
16758 .Vb 8
16759 \& COP_SEQ_RANGE_LOW _HIGH
16760 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-
16761 \& PERL_PADSEQ_INTRO 0 variable not yet introduced:
16762 \& { my ($x
16763 \& valid\-seq# PERL_PADSEQ_INTRO variable in scope:
16764 \& { my ($x);
16765 \& valid\-seq# valid\-seq# compilation of scope complete:
16766 \& { my ($x); .... }
16767 .Ve
16768 .Sp
16769 When a lexical var hasn't yet been introduced, it already exists from the
16770 perspective of duplicate declarations, but not for variable lookups, e.g.
16771 .Sp
16772 .Vb 2
16773 \& my ($x, $x); # \*(Aq"my" variable $x masks earlier declaration\*(Aq
16774 \& my $x = $x; # equal to my $x = $::x;
16775 .Ve
16776 .Sp
16777 For typed lexicals \f(CW\*(C`PadnameTYPE\*(C'\fR points at the type stash. For \f(CW\*(C`our\*(C'\fR
16778 lexicals, \f(CW\*(C`PadnameOURSTASH\*(C'\fR points at the stash of the associated global (so
16779 that duplicate \f(CW\*(C`our\*(C'\fR declarations in the same package can be detected).
16780 \&\f(CW\*(C`PadnameGEN\*(C'\fR is sometimes used to store the generation number during
16781 compilation.
16782 .Sp
16783 If \f(CW\*(C`PadnameOUTER\*(C'\fR is set on the pad name, then that slot in the frame AV
16784 is a REFCNT'ed reference to a lexical from "outside". Such entries
16785 are sometimes referred to as 'fake'. In this case, the name does not
16786 use 'low' and 'high' to store a cop_seq range, since it is in scope
16787 throughout. Instead 'high' stores some flags containing info about
16788 the real lexical (is it declared in an anon, and is it capable of being
16789 instantiated multiple times?), and for fake ANONs, 'low' contains the index
16790 within the parent's pad where the lexical's value is stored, to make
16791 cloning quicker.
16792 .Sp
16793 If the 'name' is \f(CW\*(C`&\*(C'\fR the corresponding entry in the PAD
16794 is a CV representing a possible closure.
16795 .Sp
16796 Note that formats are treated as anon subs, and are cloned each time
16797 write is called (if necessary).
16798 .Sp
16799 The flag \f(CW\*(C`SVs_PADSTALE\*(C'\fR is cleared on lexicals each time the \f(CWmy()\fR is executed,
16800 and set on scope exit. This allows the
16801 \&\f(CW"Variable $x is not available"\fR warning
16802 to be generated in evals, such as
16803 .Sp
16804 .Vb 1
16805 \& { my $x = 1; sub f { eval \*(Aq$x\*(Aq} } f();
16806 .Ve
16807 .Sp
16808 For state vars, \f(CW\*(C`SVs_PADSTALE\*(C'\fR is overloaded to mean 'not yet initialised',
16809 but this internal state is stored in a separate pad entry.
16810 .RS 4
16811 .Sp
16812 .Vb 1
16813 \& PADLIST * CvPADLIST(CV *cv)
16814 .Ve
16815 .RE
16816 .RS 4
16817 .RE
16818 .ie n .IP """pad_add_name_pvs""" 4
16819 .el .IP \f(CWpad_add_name_pvs\fR 4
16820 .IX Xref "pad_add_name_pvs"
16821 .IX Item "pad_add_name_pvs"
16822 Exactly like "pad_add_name_pvn", but takes a literal string
16823 instead of a string/length pair.
16824 .RS 4
16825 .Sp
16826 .Vb 2
16827 \& PADOFFSET pad_add_name_pvs("name", U32 flags, HV *typestash,
16828 \& HV *ourstash)
16829 .Ve
16830 .RE
16831 .RS 4
16832 .RE
16833 .ie n .IP """PadARRAY""" 4
16834 .el .IP \f(CWPadARRAY\fR 4
16835 .IX Xref "PadARRAY"
16836 .IX Item "PadARRAY"
16837 NOTE: \f(CW\*(C`PadARRAY\*(C'\fR is \fBexperimental\fR and may change or be
16838 removed without notice.
16839 .Sp
16840 The C array of pad entries.
16841 .RS 4
16842 .Sp
16843 .Vb 1
16844 \& SV ** PadARRAY(PAD * pad)
16845 .Ve
16846 .RE
16847 .RS 4
16848 .RE
16849 .ie n .IP """pad_findmy_pvs""" 4
16850 .el .IP \f(CWpad_findmy_pvs\fR 4
16851 .IX Xref "pad_findmy_pvs"
16852 .IX Item "pad_findmy_pvs"
16853 Exactly like "pad_findmy_pvn", but takes a literal string
16854 instead of a string/length pair.
16855 .RS 4
16856 .Sp
16857 .Vb 1
16858 \& PADOFFSET pad_findmy_pvs("name", U32 flags)
16859 .Ve
16860 .RE
16861 .RS 4
16862 .RE
16863 .ie n .IP """PadlistARRAY""" 4
16864 .el .IP \f(CWPadlistARRAY\fR 4
16865 .IX Xref "PadlistARRAY"
16866 .IX Item "PadlistARRAY"
16867 NOTE: \f(CW\*(C`PadlistARRAY\*(C'\fR is \fBexperimental\fR and may change or be
16868 removed without notice.
16869 .Sp
16870 The C array of a padlist, containing the pads. Only subscript it with
16871 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
16872 .RS 4
16873 .Sp
16874 .Vb 1
16875 \& PAD ** PadlistARRAY(PADLIST * padlist)
16876 .Ve
16877 .RE
16878 .RS 4
16879 .RE
16880 .ie n .IP """PadlistMAX""" 4
16881 .el .IP \f(CWPadlistMAX\fR 4
16882 .IX Xref "PadlistMAX"
16883 .IX Item "PadlistMAX"
16884 NOTE: \f(CW\*(C`PadlistMAX\*(C'\fR is \fBexperimental\fR and may change or be
16885 removed without notice.
16886 .Sp
16887 The index of the last allocated space in the padlist. Note that the last
16888 pad may be in an earlier slot. Any entries following it will be \f(CW\*(C`NULL\*(C'\fR in
16889 that case.
16890 .RS 4
16891 .Sp
16892 .Vb 1
16893 \& SSize_t PadlistMAX(PADLIST * padlist)
16894 .Ve
16895 .RE
16896 .RS 4
16897 .RE
16898 .ie n .IP """PadlistNAMES""" 4
16899 .el .IP \f(CWPadlistNAMES\fR 4
16900 .IX Xref "PadlistNAMES"
16901 .IX Item "PadlistNAMES"
16902 NOTE: \f(CW\*(C`PadlistNAMES\*(C'\fR is \fBexperimental\fR and may change or be
16903 removed without notice.
16904 .Sp
16905 The names associated with pad entries.
16906 .RS 4
16907 .Sp
16908 .Vb 1
16909 \& PADNAMELIST * PadlistNAMES(PADLIST * padlist)
16910 .Ve
16911 .RE
16912 .RS 4
16913 .RE
16914 .ie n .IP """PadlistNAMESARRAY""" 4
16915 .el .IP \f(CWPadlistNAMESARRAY\fR 4
16916 .IX Xref "PadlistNAMESARRAY"
16917 .IX Item "PadlistNAMESARRAY"
16918 NOTE: \f(CW\*(C`PadlistNAMESARRAY\*(C'\fR is \fBexperimental\fR and may change or be
16919 removed without notice.
16920 .Sp
16921 The C array of pad names.
16922 .RS 4
16923 .Sp
16924 .Vb 1
16925 \& PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
16926 .Ve
16927 .RE
16928 .RS 4
16929 .RE
16930 .ie n .IP """PadlistNAMESMAX""" 4
16931 .el .IP \f(CWPadlistNAMESMAX\fR 4
16932 .IX Xref "PadlistNAMESMAX"
16933 .IX Item "PadlistNAMESMAX"
16934 NOTE: \f(CW\*(C`PadlistNAMESMAX\*(C'\fR is \fBexperimental\fR and may change or be
16935 removed without notice.
16936 .Sp
16937 The index of the last pad name.
16938 .RS 4
16939 .Sp
16940 .Vb 1
16941 \& SSize_t PadlistNAMESMAX(PADLIST * padlist)
16942 .Ve
16943 .RE
16944 .RS 4
16945 .RE
16946 .ie n .IP """PadlistREFCNT""" 4
16947 .el .IP \f(CWPadlistREFCNT\fR 4
16948 .IX Xref "PadlistREFCNT"
16949 .IX Item "PadlistREFCNT"
16950 NOTE: \f(CW\*(C`PadlistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
16951 removed without notice.
16952 .Sp
16953 The reference count of the padlist. Currently this is always 1.
16954 .RS 4
16955 .Sp
16956 .Vb 1
16957 \& U32 PadlistREFCNT(PADLIST * padlist)
16958 .Ve
16959 .RE
16960 .RS 4
16961 .RE
16962 .ie n .IP """PadMAX""" 4
16963 .el .IP \f(CWPadMAX\fR 4
16964 .IX Xref "PadMAX"
16965 .IX Item "PadMAX"
16966 NOTE: \f(CW\*(C`PadMAX\*(C'\fR is \fBexperimental\fR and may change or be
16967 removed without notice.
16968 .Sp
16969 The index of the last pad entry.
16970 .RS 4
16971 .Sp
16972 .Vb 1
16973 \& SSize_t PadMAX(PAD * pad)
16974 .Ve
16975 .RE
16976 .RS 4
16977 .RE
16978 .ie n .IP """PadnameLEN""" 4
16979 .el .IP \f(CWPadnameLEN\fR 4
16980 .IX Xref "PadnameLEN"
16981 .IX Item "PadnameLEN"
16982 NOTE: \f(CW\*(C`PadnameLEN\*(C'\fR is \fBexperimental\fR and may change or be
16983 removed without notice.
16984 .Sp
16985 The length of the name.
16986 .RS 4
16987 .Sp
16988 .Vb 1
16989 \& STRLEN PadnameLEN(PADNAME * pn)
16990 .Ve
16991 .RE
16992 .RS 4
16993 .RE
16994 .ie n .IP """PadnamelistARRAY""" 4
16995 .el .IP \f(CWPadnamelistARRAY\fR 4
16996 .IX Xref "PadnamelistARRAY"
16997 .IX Item "PadnamelistARRAY"
16998 NOTE: \f(CW\*(C`PadnamelistARRAY\*(C'\fR is \fBexperimental\fR and may change or be
16999 removed without notice.
17000 .Sp
17001 The C array of pad names.
17002 .RS 4
17003 .Sp
17004 .Vb 1
17005 \& PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
17006 .Ve
17007 .RE
17008 .RS 4
17009 .RE
17010 .ie n .IP """PadnamelistMAX""" 4
17011 .el .IP \f(CWPadnamelistMAX\fR 4
17012 .IX Xref "PadnamelistMAX"
17013 .IX Item "PadnamelistMAX"
17014 NOTE: \f(CW\*(C`PadnamelistMAX\*(C'\fR is \fBexperimental\fR and may change or be
17015 removed without notice.
17016 .Sp
17017 The index of the last pad name.
17018 .RS 4
17019 .Sp
17020 .Vb 1
17021 \& SSize_t PadnamelistMAX(PADNAMELIST * pnl)
17022 .Ve
17023 .RE
17024 .RS 4
17025 .RE
17026 .ie n .IP """PadnamelistREFCNT""" 4
17027 .el .IP \f(CWPadnamelistREFCNT\fR 4
17028 .IX Xref "PadnamelistREFCNT"
17029 .IX Item "PadnamelistREFCNT"
17030 NOTE: \f(CW\*(C`PadnamelistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
17031 removed without notice.
17032 .Sp
17033 The reference count of the pad name list.
17034 .RS 4
17035 .Sp
17036 .Vb 1
17037 \& SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
17038 .Ve
17039 .RE
17040 .RS 4
17041 .RE
17042 .ie n .IP """PadnamelistREFCNT_dec""" 4
17043 .el .IP \f(CWPadnamelistREFCNT_dec\fR 4
17044 .IX Xref "PadnamelistREFCNT_dec"
17045 .IX Item "PadnamelistREFCNT_dec"
17046 NOTE: \f(CW\*(C`PadnamelistREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be
17047 removed without notice.
17048 .Sp
17049 Lowers the reference count of the pad name list.
17050 .RS 4
17051 .Sp
17052 .Vb 1
17053 \& void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
17054 .Ve
17055 .RE
17056 .RS 4
17057 .RE
17058 .ie n .IP """PadnamePV""" 4
17059 .el .IP \f(CWPadnamePV\fR 4
17060 .IX Xref "PadnamePV"
17061 .IX Item "PadnamePV"
17062 NOTE: \f(CW\*(C`PadnamePV\*(C'\fR is \fBexperimental\fR and may change or be
17063 removed without notice.
17064 .Sp
17065 The name stored in the pad name struct. This returns \f(CW\*(C`NULL\*(C'\fR for a target
17066 slot.
17067 .RS 4
17068 .Sp
17069 .Vb 1
17070 \& char * PadnamePV(PADNAME * pn)
17071 .Ve
17072 .RE
17073 .RS 4
17074 .RE
17075 .ie n .IP """PadnameREFCNT""" 4
17076 .el .IP \f(CWPadnameREFCNT\fR 4
17077 .IX Xref "PadnameREFCNT"
17078 .IX Item "PadnameREFCNT"
17079 NOTE: \f(CW\*(C`PadnameREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
17080 removed without notice.
17081 .Sp
17082 The reference count of the pad name.
17083 .RS 4
17084 .Sp
17085 .Vb 1
17086 \& SSize_t PadnameREFCNT(PADNAME * pn)
17087 .Ve
17088 .RE
17089 .RS 4
17090 .RE
17091 .ie n .IP """PadnameREFCNT_dec""" 4
17092 .el .IP \f(CWPadnameREFCNT_dec\fR 4
17093 .IX Xref "PadnameREFCNT_dec"
17094 .IX Item "PadnameREFCNT_dec"
17095 NOTE: \f(CW\*(C`PadnameREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be
17096 removed without notice.
17097 .Sp
17098 Lowers the reference count of the pad name.
17099 .RS 4
17100 .Sp
17101 .Vb 1
17102 \& void PadnameREFCNT_dec(PADNAME * pn)
17103 .Ve
17104 .RE
17105 .RS 4
17106 .RE
17107 .ie n .IP """PadnameREFCNT_inc""" 4
17108 .el .IP \f(CWPadnameREFCNT_inc\fR 4
17109 .IX Xref "PadnameREFCNT_inc"
17110 .IX Item "PadnameREFCNT_inc"
17111 NOTE: \f(CW\*(C`PadnameREFCNT_inc\*(C'\fR is \fBexperimental\fR and may change or be
17112 removed without notice.
17113 .Sp
17114 Increases the reference count of the pad name. Returns the pad name itself.
17115 .RS 4
17116 .Sp
17117 .Vb 1
17118 \& PADNAME * PadnameREFCNT_inc(PADNAME * pn)
17119 .Ve
17120 .RE
17121 .RS 4
17122 .RE
17123 .ie n .IP """PadnameSV""" 4
17124 .el .IP \f(CWPadnameSV\fR 4
17125 .IX Xref "PadnameSV"
17126 .IX Item "PadnameSV"
17127 NOTE: \f(CW\*(C`PadnameSV\*(C'\fR is \fBexperimental\fR and may change or be
17128 removed without notice.
17129 .Sp
17130 Returns the pad name as a mortal SV.
17131 .RS 4
17132 .Sp
17133 .Vb 1
17134 \& SV * PadnameSV(PADNAME * pn)
17135 .Ve
17136 .RE
17137 .RS 4
17138 .RE
17139 .ie n .IP """PadnameUTF8""" 4
17140 .el .IP \f(CWPadnameUTF8\fR 4
17141 .IX Xref "PadnameUTF8"
17142 .IX Item "PadnameUTF8"
17143 NOTE: \f(CW\*(C`PadnameUTF8\*(C'\fR is \fBexperimental\fR and may change or be
17144 removed without notice.
17145 .Sp
17146 Whether PadnamePV is in UTF\-8. Currently, this is always true.
17147 .RS 4
17148 .Sp
17149 .Vb 1
17150 \& bool PadnameUTF8(PADNAME * pn)
17151 .Ve
17152 .RE
17153 .RS 4
17154 .RE
17155 .ie n .IP """pad_new""" 4
17156 .el .IP \f(CWpad_new\fR 4
17157 .IX Xref "pad_new"
17158 .IX Item "pad_new"
17159 Create a new padlist, updating the global variables for the
17160 currently-compiling padlist to point to the new padlist. The following
17161 flags can be OR'ed together:
17162 .Sp
17163 .Vb 3
17164 \& padnew_CLONE this pad is for a cloned CV
17165 \& padnew_SAVE save old globals on the save stack
17166 \& padnew_SAVESUB also save extra stuff for start of sub
17167 .Ve
17168 .RS 4
17169 .Sp
17170 .Vb 1
17171 \& PADLIST * pad_new(int flags)
17172 .Ve
17173 .RE
17174 .RS 4
17175 .RE
17176 .ie n .IP """PL_comppad""" 4
17177 .el .IP \f(CWPL_comppad\fR 4
17178 .IX Xref "PL_comppad"
17179 .IX Item "PL_comppad"
17180 NOTE: \f(CW\*(C`PL_comppad\*(C'\fR is \fBexperimental\fR and may change or be
17181 removed without notice.
17182 .Sp
17183 During compilation, this points to the array containing the values
17184 part of the pad for the currently-compiling code. (At runtime a CV may
17185 have many such value arrays; at compile time just one is constructed.)
17186 At runtime, this points to the array containing the currently-relevant
17187 values for the pad for the currently-executing code.
17188 .ie n .IP """PL_comppad_name""" 4
17189 .el .IP \f(CWPL_comppad_name\fR 4
17190 .IX Xref "PL_comppad_name"
17191 .IX Item "PL_comppad_name"
17192 NOTE: \f(CW\*(C`PL_comppad_name\*(C'\fR is \fBexperimental\fR and may change or be
17193 removed without notice.
17194 .Sp
17195 During compilation, this points to the array containing the names part
17196 of the pad for the currently-compiling code.
17197 .ie n .IP """PL_curpad""" 4
17198 .el .IP \f(CWPL_curpad\fR 4
17199 .IX Xref "PL_curpad"
17200 .IX Item "PL_curpad"
17201 NOTE: \f(CW\*(C`PL_curpad\*(C'\fR is \fBexperimental\fR and may change or be
17202 removed without notice.
17203 .Sp
17204 Points directly to the body of the "PL_comppad" array.
17205 (I.e., this is \f(CWPadARRAY(PL_comppad)\fR.)
17206 .ie n .IP """SVs_PADMY""" 4
17207 .el .IP \f(CWSVs_PADMY\fR 4
17208 .IX Item "SVs_PADMY"
17209 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`SVs_PADMY\*(C'\fR
17210 from a future release of Perl. Do not use it for
17211 new code; remove it from existing code.
17212 .Sp
17213 Described in perlguts.
17214 .ie n .IP """SVs_PADTMP""" 4
17215 .el .IP \f(CWSVs_PADTMP\fR 4
17216 .IX Item "SVs_PADTMP"
17217 Described in perlguts.
17218 .SH "Password and Group access"
17219 .IX Header "Password and Group access"
17220 .ie n .IP """GRPASSWD""" 4
17221 .el .IP \f(CWGRPASSWD\fR 4
17222 .IX Xref "GRPASSWD"
17223 .IX Item "GRPASSWD"
17224 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct group\*(C'\fR
17225 in \fIgrp.h\fR contains \f(CW\*(C`gr_passwd\*(C'\fR.
17226 .ie n .IP """HAS_ENDGRENT""" 4
17227 .el .IP \f(CWHAS_ENDGRENT\fR 4
17228 .IX Xref "HAS_ENDGRENT"
17229 .IX Item "HAS_ENDGRENT"
17230 This symbol, if defined, indicates that the getgrent routine is
17231 available for finalizing sequential access of the group database.
17232 .ie n .IP """HAS_ENDGRENT_R""" 4
17233 .el .IP \f(CWHAS_ENDGRENT_R\fR 4
17234 .IX Xref "HAS_ENDGRENT_R"
17235 .IX Item "HAS_ENDGRENT_R"
17236 This symbol, if defined, indicates that the \f(CW\*(C`endgrent_r\*(C'\fR routine
17237 is available to endgrent re-entrantly.
17238 .ie n .IP """HAS_ENDPWENT""" 4
17239 .el .IP \f(CWHAS_ENDPWENT\fR 4
17240 .IX Xref "HAS_ENDPWENT"
17241 .IX Item "HAS_ENDPWENT"
17242 This symbol, if defined, indicates that the \f(CW\*(C`endpwent\*(C'\fR routine is
17243 available for finalizing sequential access of the passwd database.
17244 .ie n .IP """HAS_ENDPWENT_R""" 4
17245 .el .IP \f(CWHAS_ENDPWENT_R\fR 4
17246 .IX Xref "HAS_ENDPWENT_R"
17247 .IX Item "HAS_ENDPWENT_R"
17248 This symbol, if defined, indicates that the \f(CW\*(C`endpwent_r\*(C'\fR routine
17249 is available to endpwent re-entrantly.
17250 .ie n .IP """HAS_GETGRENT""" 4
17251 .el .IP \f(CWHAS_GETGRENT\fR 4
17252 .IX Xref "HAS_GETGRENT"
17253 .IX Item "HAS_GETGRENT"
17254 This symbol, if defined, indicates that the \f(CW\*(C`getgrent\*(C'\fR routine is
17255 available for sequential access of the group database.
17256 .ie n .IP """HAS_GETGRENT_R""" 4
17257 .el .IP \f(CWHAS_GETGRENT_R\fR 4
17258 .IX Xref "HAS_GETGRENT_R"
17259 .IX Item "HAS_GETGRENT_R"
17260 This symbol, if defined, indicates that the \f(CW\*(C`getgrent_r\*(C'\fR routine
17261 is available to getgrent re-entrantly.
17262 .ie n .IP """HAS_GETPWENT""" 4
17263 .el .IP \f(CWHAS_GETPWENT\fR 4
17264 .IX Xref "HAS_GETPWENT"
17265 .IX Item "HAS_GETPWENT"
17266 This symbol, if defined, indicates that the \f(CW\*(C`getpwent\*(C'\fR routine is
17267 available for sequential access of the passwd database.
17268 If this is not available, the older \f(CWgetpw()\fR function may be available.
17269 .ie n .IP """HAS_GETPWENT_R""" 4
17270 .el .IP \f(CWHAS_GETPWENT_R\fR 4
17271 .IX Xref "HAS_GETPWENT_R"
17272 .IX Item "HAS_GETPWENT_R"
17273 This symbol, if defined, indicates that the \f(CW\*(C`getpwent_r\*(C'\fR routine
17274 is available to getpwent re-entrantly.
17275 .ie n .IP """HAS_SETGRENT""" 4
17276 .el .IP \f(CWHAS_SETGRENT\fR 4
17277 .IX Xref "HAS_SETGRENT"
17278 .IX Item "HAS_SETGRENT"
17279 This symbol, if defined, indicates that the \f(CW\*(C`setgrent\*(C'\fR routine is
17280 available for initializing sequential access of the group database.
17281 .ie n .IP """HAS_SETGRENT_R""" 4
17282 .el .IP \f(CWHAS_SETGRENT_R\fR 4
17283 .IX Xref "HAS_SETGRENT_R"
17284 .IX Item "HAS_SETGRENT_R"
17285 This symbol, if defined, indicates that the \f(CW\*(C`setgrent_r\*(C'\fR routine
17286 is available to setgrent re-entrantly.
17287 .ie n .IP """HAS_SETPWENT""" 4
17288 .el .IP \f(CWHAS_SETPWENT\fR 4
17289 .IX Xref "HAS_SETPWENT"
17290 .IX Item "HAS_SETPWENT"
17291 This symbol, if defined, indicates that the \f(CW\*(C`setpwent\*(C'\fR routine is
17292 available for initializing sequential access of the passwd database.
17293 .ie n .IP """HAS_SETPWENT_R""" 4
17294 .el .IP \f(CWHAS_SETPWENT_R\fR 4
17295 .IX Xref "HAS_SETPWENT_R"
17296 .IX Item "HAS_SETPWENT_R"
17297 This symbol, if defined, indicates that the \f(CW\*(C`setpwent_r\*(C'\fR routine
17298 is available to setpwent re-entrantly.
17299 .ie n .IP """PWAGE""" 4
17300 .el .IP \f(CWPWAGE\fR 4
17301 .IX Xref "PWAGE"
17302 .IX Item "PWAGE"
17303 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17304 contains \f(CW\*(C`pw_age\*(C'\fR.
17305 .ie n .IP """PWCHANGE""" 4
17306 .el .IP \f(CWPWCHANGE\fR 4
17307 .IX Xref "PWCHANGE"
17308 .IX Item "PWCHANGE"
17309 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17310 contains \f(CW\*(C`pw_change\*(C'\fR.
17311 .ie n .IP """PWCLASS""" 4
17312 .el .IP \f(CWPWCLASS\fR 4
17313 .IX Xref "PWCLASS"
17314 .IX Item "PWCLASS"
17315 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17316 contains \f(CW\*(C`pw_class\*(C'\fR.
17317 .ie n .IP """PWCOMMENT""" 4
17318 .el .IP \f(CWPWCOMMENT\fR 4
17319 .IX Xref "PWCOMMENT"
17320 .IX Item "PWCOMMENT"
17321 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17322 contains \f(CW\*(C`pw_comment\*(C'\fR.
17323 .ie n .IP """PWEXPIRE""" 4
17324 .el .IP \f(CWPWEXPIRE\fR 4
17325 .IX Xref "PWEXPIRE"
17326 .IX Item "PWEXPIRE"
17327 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17328 contains \f(CW\*(C`pw_expire\*(C'\fR.
17329 .ie n .IP """PWGECOS""" 4
17330 .el .IP \f(CWPWGECOS\fR 4
17331 .IX Xref "PWGECOS"
17332 .IX Item "PWGECOS"
17333 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17334 contains \f(CW\*(C`pw_gecos\*(C'\fR.
17335 .ie n .IP """PWPASSWD""" 4
17336 .el .IP \f(CWPWPASSWD\fR 4
17337 .IX Xref "PWPASSWD"
17338 .IX Item "PWPASSWD"
17339 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17340 contains \f(CW\*(C`pw_passwd\*(C'\fR.
17341 .ie n .IP """PWQUOTA""" 4
17342 .el .IP \f(CWPWQUOTA\fR 4
17343 .IX Xref "PWQUOTA"
17344 .IX Item "PWQUOTA"
17345 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17346 contains \f(CW\*(C`pw_quota\*(C'\fR.
17347 .SH "Paths to system commands"
17348 .IX Header "Paths to system commands"
17349 .ie n .IP """CSH""" 4
17350 .el .IP \f(CWCSH\fR 4
17351 .IX Xref "CSH"
17352 .IX Item "CSH"
17353 This symbol, if defined, contains the full pathname of csh.
17354 .ie n .IP """LOC_SED""" 4
17355 .el .IP \f(CWLOC_SED\fR 4
17356 .IX Xref "LOC_SED"
17357 .IX Item "LOC_SED"
17358 This symbol holds the complete pathname to the sed program.
17359 .ie n .IP """SH_PATH""" 4
17360 .el .IP \f(CWSH_PATH\fR 4
17361 .IX Xref "SH_PATH"
17362 .IX Item "SH_PATH"
17363 This symbol contains the full pathname to the shell used on this
17364 on this system to execute Bourne shell scripts. Usually, this will be
17365 \&\fI/bin/sh\fR, though it's possible that some systems will have \fI/bin/ksh\fR,
17366 \&\fI/bin/pdksh\fR, \fI/bin/ash\fR, \fI/bin/bash\fR, or even something such as
17367 D:\fI/bin/sh.exe\fR.
17368 .SH "Prototype information"
17369 .IX Header "Prototype information"
17370 .ie n .IP """CRYPT_R_PROTO""" 4
17371 .el .IP \f(CWCRYPT_R_PROTO\fR 4
17372 .IX Xref "CRYPT_R_PROTO"
17373 .IX Item "CRYPT_R_PROTO"
17374 This symbol encodes the prototype of \f(CW\*(C`crypt_r\*(C'\fR.
17375 It is zero if \f(CW\*(C`d_crypt_r\*(C'\fR is undef, and one of the
17376 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_crypt_r\*(C'\fR
17377 is defined.
17378 .ie n .IP """CTERMID_R_PROTO""" 4
17379 .el .IP \f(CWCTERMID_R_PROTO\fR 4
17380 .IX Xref "CTERMID_R_PROTO"
17381 .IX Item "CTERMID_R_PROTO"
17382 This symbol encodes the prototype of \f(CW\*(C`ctermid_r\*(C'\fR.
17383 It is zero if \f(CW\*(C`d_ctermid_r\*(C'\fR is undef, and one of the
17384 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctermid_r\*(C'\fR
17385 is defined.
17386 .ie n .IP """DRAND48_R_PROTO""" 4
17387 .el .IP \f(CWDRAND48_R_PROTO\fR 4
17388 .IX Xref "DRAND48_R_PROTO"
17389 .IX Item "DRAND48_R_PROTO"
17390 This symbol encodes the prototype of \f(CW\*(C`drand48_r\*(C'\fR.
17391 It is zero if \f(CW\*(C`d_drand48_r\*(C'\fR is undef, and one of the
17392 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_drand48_r\*(C'\fR
17393 is defined.
17394 .ie n .IP """ENDGRENT_R_PROTO""" 4
17395 .el .IP \f(CWENDGRENT_R_PROTO\fR 4
17396 .IX Xref "ENDGRENT_R_PROTO"
17397 .IX Item "ENDGRENT_R_PROTO"
17398 This symbol encodes the prototype of \f(CW\*(C`endgrent_r\*(C'\fR.
17399 It is zero if \f(CW\*(C`d_endgrent_r\*(C'\fR is undef, and one of the
17400 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endgrent_r\*(C'\fR
17401 is defined.
17402 .ie n .IP """ENDHOSTENT_R_PROTO""" 4
17403 .el .IP \f(CWENDHOSTENT_R_PROTO\fR 4
17404 .IX Xref "ENDHOSTENT_R_PROTO"
17405 .IX Item "ENDHOSTENT_R_PROTO"
17406 This symbol encodes the prototype of \f(CW\*(C`endhostent_r\*(C'\fR.
17407 It is zero if \f(CW\*(C`d_endhostent_r\*(C'\fR is undef, and one of the
17408 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endhostent_r\*(C'\fR
17409 is defined.
17410 .ie n .IP """ENDNETENT_R_PROTO""" 4
17411 .el .IP \f(CWENDNETENT_R_PROTO\fR 4
17412 .IX Xref "ENDNETENT_R_PROTO"
17413 .IX Item "ENDNETENT_R_PROTO"
17414 This symbol encodes the prototype of \f(CW\*(C`endnetent_r\*(C'\fR.
17415 It is zero if \f(CW\*(C`d_endnetent_r\*(C'\fR is undef, and one of the
17416 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endnetent_r\*(C'\fR
17417 is defined.
17418 .ie n .IP """ENDPROTOENT_R_PROTO""" 4
17419 .el .IP \f(CWENDPROTOENT_R_PROTO\fR 4
17420 .IX Xref "ENDPROTOENT_R_PROTO"
17421 .IX Item "ENDPROTOENT_R_PROTO"
17422 This symbol encodes the prototype of \f(CW\*(C`endprotoent_r\*(C'\fR.
17423 It is zero if \f(CW\*(C`d_endprotoent_r\*(C'\fR is undef, and one of the
17424 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endprotoent_r\*(C'\fR
17425 is defined.
17426 .ie n .IP """ENDPWENT_R_PROTO""" 4
17427 .el .IP \f(CWENDPWENT_R_PROTO\fR 4
17428 .IX Xref "ENDPWENT_R_PROTO"
17429 .IX Item "ENDPWENT_R_PROTO"
17430 This symbol encodes the prototype of \f(CW\*(C`endpwent_r\*(C'\fR.
17431 It is zero if \f(CW\*(C`d_endpwent_r\*(C'\fR is undef, and one of the
17432 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endpwent_r\*(C'\fR
17433 is defined.
17434 .ie n .IP """ENDSERVENT_R_PROTO""" 4
17435 .el .IP \f(CWENDSERVENT_R_PROTO\fR 4
17436 .IX Xref "ENDSERVENT_R_PROTO"
17437 .IX Item "ENDSERVENT_R_PROTO"
17438 This symbol encodes the prototype of \f(CW\*(C`endservent_r\*(C'\fR.
17439 It is zero if \f(CW\*(C`d_endservent_r\*(C'\fR is undef, and one of the
17440 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endservent_r\*(C'\fR
17441 is defined.
17442 .ie n .IP """GDBMNDBM_H_USES_PROTOTYPES""" 4
17443 .el .IP \f(CWGDBMNDBM_H_USES_PROTOTYPES\fR 4
17444 .IX Xref "GDBMNDBM_H_USES_PROTOTYPES"
17445 .IX Item "GDBMNDBM_H_USES_PROTOTYPES"
17446 This symbol, if defined, indicates that \fIgdbm/ndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C
17447 prototypes instead of K&R style function declarations without any
17448 parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
17449 K&R style function declarations will yield errors.
17450 .ie n .IP """GDBM_NDBM_H_USES_PROTOTYPES""" 4
17451 .el .IP \f(CWGDBM_NDBM_H_USES_PROTOTYPES\fR 4
17452 .IX Xref "GDBM_NDBM_H_USES_PROTOTYPES"
17453 .IX Item "GDBM_NDBM_H_USES_PROTOTYPES"
17454 This symbol, if defined, indicates that <gdbm\-\fIndbm.h\fR> uses real \f(CW\*(C`ANSI\*(C'\fR C
17455 prototypes instead of K&R style function declarations without any
17456 parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
17457 K&R style function declarations will yield errors.
17458 .ie n .IP """GETGRENT_R_PROTO""" 4
17459 .el .IP \f(CWGETGRENT_R_PROTO\fR 4
17460 .IX Xref "GETGRENT_R_PROTO"
17461 .IX Item "GETGRENT_R_PROTO"
17462 This symbol encodes the prototype of \f(CW\*(C`getgrent_r\*(C'\fR.
17463 It is zero if \f(CW\*(C`d_getgrent_r\*(C'\fR is undef, and one of the
17464 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrent_r\*(C'\fR
17465 is defined.
17466 .ie n .IP """GETGRGID_R_PROTO""" 4
17467 .el .IP \f(CWGETGRGID_R_PROTO\fR 4
17468 .IX Xref "GETGRGID_R_PROTO"
17469 .IX Item "GETGRGID_R_PROTO"
17470 This symbol encodes the prototype of \f(CW\*(C`getgrgid_r\*(C'\fR.
17471 It is zero if \f(CW\*(C`d_getgrgid_r\*(C'\fR is undef, and one of the
17472 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrgid_r\*(C'\fR
17473 is defined.
17474 .ie n .IP """GETGRNAM_R_PROTO""" 4
17475 .el .IP \f(CWGETGRNAM_R_PROTO\fR 4
17476 .IX Xref "GETGRNAM_R_PROTO"
17477 .IX Item "GETGRNAM_R_PROTO"
17478 This symbol encodes the prototype of \f(CW\*(C`getgrnam_r\*(C'\fR.
17479 It is zero if \f(CW\*(C`d_getgrnam_r\*(C'\fR is undef, and one of the
17480 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrnam_r\*(C'\fR
17481 is defined.
17482 .ie n .IP """GETHOSTBYADDR_R_PROTO""" 4
17483 .el .IP \f(CWGETHOSTBYADDR_R_PROTO\fR 4
17484 .IX Xref "GETHOSTBYADDR_R_PROTO"
17485 .IX Item "GETHOSTBYADDR_R_PROTO"
17486 This symbol encodes the prototype of \f(CW\*(C`gethostbyaddr_r\*(C'\fR.
17487 It is zero if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR is undef, and one of the
17488 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR
17489 is defined.
17490 .ie n .IP """GETHOSTBYNAME_R_PROTO""" 4
17491 .el .IP \f(CWGETHOSTBYNAME_R_PROTO\fR 4
17492 .IX Xref "GETHOSTBYNAME_R_PROTO"
17493 .IX Item "GETHOSTBYNAME_R_PROTO"
17494 This symbol encodes the prototype of \f(CW\*(C`gethostbyname_r\*(C'\fR.
17495 It is zero if \f(CW\*(C`d_gethostbyname_r\*(C'\fR is undef, and one of the
17496 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyname_r\*(C'\fR
17497 is defined.
17498 .ie n .IP """GETHOSTENT_R_PROTO""" 4
17499 .el .IP \f(CWGETHOSTENT_R_PROTO\fR 4
17500 .IX Xref "GETHOSTENT_R_PROTO"
17501 .IX Item "GETHOSTENT_R_PROTO"
17502 This symbol encodes the prototype of \f(CW\*(C`gethostent_r\*(C'\fR.
17503 It is zero if \f(CW\*(C`d_gethostent_r\*(C'\fR is undef, and one of the
17504 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostent_r\*(C'\fR
17505 is defined.
17506 .ie n .IP """GETLOGIN_R_PROTO""" 4
17507 .el .IP \f(CWGETLOGIN_R_PROTO\fR 4
17508 .IX Xref "GETLOGIN_R_PROTO"
17509 .IX Item "GETLOGIN_R_PROTO"
17510 This symbol encodes the prototype of \f(CW\*(C`getlogin_r\*(C'\fR.
17511 It is zero if \f(CW\*(C`d_getlogin_r\*(C'\fR is undef, and one of the
17512 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getlogin_r\*(C'\fR
17513 is defined.
17514 .ie n .IP """GETNETBYADDR_R_PROTO""" 4
17515 .el .IP \f(CWGETNETBYADDR_R_PROTO\fR 4
17516 .IX Xref "GETNETBYADDR_R_PROTO"
17517 .IX Item "GETNETBYADDR_R_PROTO"
17518 This symbol encodes the prototype of \f(CW\*(C`getnetbyaddr_r\*(C'\fR.
17519 It is zero if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR is undef, and one of the
17520 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR
17521 is defined.
17522 .ie n .IP """GETNETBYNAME_R_PROTO""" 4
17523 .el .IP \f(CWGETNETBYNAME_R_PROTO\fR 4
17524 .IX Xref "GETNETBYNAME_R_PROTO"
17525 .IX Item "GETNETBYNAME_R_PROTO"
17526 This symbol encodes the prototype of \f(CW\*(C`getnetbyname_r\*(C'\fR.
17527 It is zero if \f(CW\*(C`d_getnetbyname_r\*(C'\fR is undef, and one of the
17528 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyname_r\*(C'\fR
17529 is defined.
17530 .ie n .IP """GETNETENT_R_PROTO""" 4
17531 .el .IP \f(CWGETNETENT_R_PROTO\fR 4
17532 .IX Xref "GETNETENT_R_PROTO"
17533 .IX Item "GETNETENT_R_PROTO"
17534 This symbol encodes the prototype of \f(CW\*(C`getnetent_r\*(C'\fR.
17535 It is zero if \f(CW\*(C`d_getnetent_r\*(C'\fR is undef, and one of the
17536 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetent_r\*(C'\fR
17537 is defined.
17538 .ie n .IP """GETPROTOBYNAME_R_PROTO""" 4
17539 .el .IP \f(CWGETPROTOBYNAME_R_PROTO\fR 4
17540 .IX Xref "GETPROTOBYNAME_R_PROTO"
17541 .IX Item "GETPROTOBYNAME_R_PROTO"
17542 This symbol encodes the prototype of \f(CW\*(C`getprotobyname_r\*(C'\fR.
17543 It is zero if \f(CW\*(C`d_getprotobyname_r\*(C'\fR is undef, and one of the
17544 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobyname_r\*(C'\fR
17545 is defined.
17546 .ie n .IP """GETPROTOBYNUMBER_R_PROTO""" 4
17547 .el .IP \f(CWGETPROTOBYNUMBER_R_PROTO\fR 4
17548 .IX Xref "GETPROTOBYNUMBER_R_PROTO"
17549 .IX Item "GETPROTOBYNUMBER_R_PROTO"
17550 This symbol encodes the prototype of \f(CW\*(C`getprotobynumber_r\*(C'\fR.
17551 It is zero if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR is undef, and one of the
17552 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR
17553 is defined.
17554 .ie n .IP """GETPROTOENT_R_PROTO""" 4
17555 .el .IP \f(CWGETPROTOENT_R_PROTO\fR 4
17556 .IX Xref "GETPROTOENT_R_PROTO"
17557 .IX Item "GETPROTOENT_R_PROTO"
17558 This symbol encodes the prototype of \f(CW\*(C`getprotoent_r\*(C'\fR.
17559 It is zero if \f(CW\*(C`d_getprotoent_r\*(C'\fR is undef, and one of the
17560 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotoent_r\*(C'\fR
17561 is defined.
17562 .ie n .IP """GETPWENT_R_PROTO""" 4
17563 .el .IP \f(CWGETPWENT_R_PROTO\fR 4
17564 .IX Xref "GETPWENT_R_PROTO"
17565 .IX Item "GETPWENT_R_PROTO"
17566 This symbol encodes the prototype of \f(CW\*(C`getpwent_r\*(C'\fR.
17567 It is zero if \f(CW\*(C`d_getpwent_r\*(C'\fR is undef, and one of the
17568 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwent_r\*(C'\fR
17569 is defined.
17570 .ie n .IP """GETPWNAM_R_PROTO""" 4
17571 .el .IP \f(CWGETPWNAM_R_PROTO\fR 4
17572 .IX Xref "GETPWNAM_R_PROTO"
17573 .IX Item "GETPWNAM_R_PROTO"
17574 This symbol encodes the prototype of \f(CW\*(C`getpwnam_r\*(C'\fR.
17575 It is zero if \f(CW\*(C`d_getpwnam_r\*(C'\fR is undef, and one of the
17576 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwnam_r\*(C'\fR
17577 is defined.
17578 .ie n .IP """GETPWUID_R_PROTO""" 4
17579 .el .IP \f(CWGETPWUID_R_PROTO\fR 4
17580 .IX Xref "GETPWUID_R_PROTO"
17581 .IX Item "GETPWUID_R_PROTO"
17582 This symbol encodes the prototype of \f(CW\*(C`getpwuid_r\*(C'\fR.
17583 It is zero if \f(CW\*(C`d_getpwuid_r\*(C'\fR is undef, and one of the
17584 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwuid_r\*(C'\fR
17585 is defined.
17586 .ie n .IP """GETSERVBYNAME_R_PROTO""" 4
17587 .el .IP \f(CWGETSERVBYNAME_R_PROTO\fR 4
17588 .IX Xref "GETSERVBYNAME_R_PROTO"
17589 .IX Item "GETSERVBYNAME_R_PROTO"
17590 This symbol encodes the prototype of \f(CW\*(C`getservbyname_r\*(C'\fR.
17591 It is zero if \f(CW\*(C`d_getservbyname_r\*(C'\fR is undef, and one of the
17592 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyname_r\*(C'\fR
17593 is defined.
17594 .ie n .IP """GETSERVBYPORT_R_PROTO""" 4
17595 .el .IP \f(CWGETSERVBYPORT_R_PROTO\fR 4
17596 .IX Xref "GETSERVBYPORT_R_PROTO"
17597 .IX Item "GETSERVBYPORT_R_PROTO"
17598 This symbol encodes the prototype of \f(CW\*(C`getservbyport_r\*(C'\fR.
17599 It is zero if \f(CW\*(C`d_getservbyport_r\*(C'\fR is undef, and one of the
17600 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyport_r\*(C'\fR
17601 is defined.
17602 .ie n .IP """GETSERVENT_R_PROTO""" 4
17603 .el .IP \f(CWGETSERVENT_R_PROTO\fR 4
17604 .IX Xref "GETSERVENT_R_PROTO"
17605 .IX Item "GETSERVENT_R_PROTO"
17606 This symbol encodes the prototype of \f(CW\*(C`getservent_r\*(C'\fR.
17607 It is zero if \f(CW\*(C`d_getservent_r\*(C'\fR is undef, and one of the
17608 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservent_r\*(C'\fR
17609 is defined.
17610 .ie n .IP """GETSPNAM_R_PROTO""" 4
17611 .el .IP \f(CWGETSPNAM_R_PROTO\fR 4
17612 .IX Xref "GETSPNAM_R_PROTO"
17613 .IX Item "GETSPNAM_R_PROTO"
17614 This symbol encodes the prototype of \f(CW\*(C`getspnam_r\*(C'\fR.
17615 It is zero if \f(CW\*(C`d_getspnam_r\*(C'\fR is undef, and one of the
17616 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getspnam_r\*(C'\fR
17617 is defined.
17618 .ie n .IP """HAS_DBMINIT_PROTO""" 4
17619 .el .IP \f(CWHAS_DBMINIT_PROTO\fR 4
17620 .IX Xref "HAS_DBMINIT_PROTO"
17621 .IX Item "HAS_DBMINIT_PROTO"
17622 This symbol, if defined, indicates that the system provides
17623 a prototype for the \f(CWdbminit()\fR function. Otherwise, it is up
17624 to the program to supply one. A good guess is
17625 .Sp
17626 .Vb 1
17627 \& extern int dbminit(char *);
17628 .Ve
17629 .ie n .IP """HAS_DRAND48_PROTO""" 4
17630 .el .IP \f(CWHAS_DRAND48_PROTO\fR 4
17631 .IX Xref "HAS_DRAND48_PROTO"
17632 .IX Item "HAS_DRAND48_PROTO"
17633 This symbol, if defined, indicates that the system provides
17634 a prototype for the \f(CWdrand48()\fR function. Otherwise, it is up
17635 to the program to supply one. A good guess is
17636 .Sp
17637 .Vb 1
17638 \& extern double drand48(void);
17639 .Ve
17640 .ie n .IP """HAS_FLOCK_PROTO""" 4
17641 .el .IP \f(CWHAS_FLOCK_PROTO\fR 4
17642 .IX Xref "HAS_FLOCK_PROTO"
17643 .IX Item "HAS_FLOCK_PROTO"
17644 This symbol, if defined, indicates that the system provides
17645 a prototype for the \f(CWflock()\fR function. Otherwise, it is up
17646 to the program to supply one. A good guess is
17647 .Sp
17648 .Vb 1
17649 \& extern int flock(int, int);
17650 .Ve
17651 .ie n .IP """HAS_GETHOST_PROTOS""" 4
17652 .el .IP \f(CWHAS_GETHOST_PROTOS\fR 4
17653 .IX Xref "HAS_GETHOST_PROTOS"
17654 .IX Item "HAS_GETHOST_PROTOS"
17655 This symbol, if defined, indicates that \fInetdb.h\fR includes
17656 prototypes for \f(CWgethostent()\fR, \f(CWgethostbyname()\fR, and
17657 \&\f(CWgethostbyaddr()\fR. Otherwise, it is up to the program to guess
17658 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
17659 .ie n .IP """HAS_GETNET_PROTOS""" 4
17660 .el .IP \f(CWHAS_GETNET_PROTOS\fR 4
17661 .IX Xref "HAS_GETNET_PROTOS"
17662 .IX Item "HAS_GETNET_PROTOS"
17663 This symbol, if defined, indicates that \fInetdb.h\fR includes
17664 prototypes for \f(CWgetnetent()\fR, \f(CWgetnetbyname()\fR, and
17665 \&\f(CWgetnetbyaddr()\fR. Otherwise, it is up to the program to guess
17666 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
17667 .ie n .IP """HAS_GETPROTO_PROTOS""" 4
17668 .el .IP \f(CWHAS_GETPROTO_PROTOS\fR 4
17669 .IX Xref "HAS_GETPROTO_PROTOS"
17670 .IX Item "HAS_GETPROTO_PROTOS"
17671 This symbol, if defined, indicates that \fInetdb.h\fR includes
17672 prototypes for \f(CWgetprotoent()\fR, \f(CWgetprotobyname()\fR, and
17673 \&\f(CWgetprotobyaddr()\fR. Otherwise, it is up to the program to guess
17674 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
17675 .ie n .IP """HAS_GETSERV_PROTOS""" 4
17676 .el .IP \f(CWHAS_GETSERV_PROTOS\fR 4
17677 .IX Xref "HAS_GETSERV_PROTOS"
17678 .IX Item "HAS_GETSERV_PROTOS"
17679 This symbol, if defined, indicates that \fInetdb.h\fR includes
17680 prototypes for \f(CWgetservent()\fR, \f(CWgetservbyname()\fR, and
17681 \&\f(CWgetservbyaddr()\fR. Otherwise, it is up to the program to guess
17682 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
17683 .ie n .IP """HAS_MODFL_PROTO""" 4
17684 .el .IP \f(CWHAS_MODFL_PROTO\fR 4
17685 .IX Xref "HAS_MODFL_PROTO"
17686 .IX Item "HAS_MODFL_PROTO"
17687 This symbol, if defined, indicates that the system provides
17688 a prototype for the \f(CWmodfl()\fR function. Otherwise, it is up
17689 to the program to supply one.
17690 .ie n .IP """HAS_SBRK_PROTO""" 4
17691 .el .IP \f(CWHAS_SBRK_PROTO\fR 4
17692 .IX Xref "HAS_SBRK_PROTO"
17693 .IX Item "HAS_SBRK_PROTO"
17694 This symbol, if defined, indicates that the system provides
17695 a prototype for the \f(CWsbrk()\fR function. Otherwise, it is up
17696 to the program to supply one. Good guesses are
17697 .Sp
17698 .Vb 2
17699 \& extern void* sbrk(int);
17700 \& extern void* sbrk(size_t);
17701 .Ve
17702 .ie n .IP """HAS_SETRESGID_PROTO""" 4
17703 .el .IP \f(CWHAS_SETRESGID_PROTO\fR 4
17704 .IX Xref "HAS_SETRESGID_PROTO"
17705 .IX Item "HAS_SETRESGID_PROTO"
17706 This symbol, if defined, indicates that the system provides
17707 a prototype for the \f(CWsetresgid()\fR function. Otherwise, it is up
17708 to the program to supply one. Good guesses are
17709 .Sp
17710 .Vb 1
17711 \& extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
17712 .Ve
17713 .ie n .IP """HAS_SETRESUID_PROTO""" 4
17714 .el .IP \f(CWHAS_SETRESUID_PROTO\fR 4
17715 .IX Xref "HAS_SETRESUID_PROTO"
17716 .IX Item "HAS_SETRESUID_PROTO"
17717 This symbol, if defined, indicates that the system provides
17718 a prototype for the \f(CWsetresuid()\fR function. Otherwise, it is up
17719 to the program to supply one. Good guesses are
17720 .Sp
17721 .Vb 1
17722 \& extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
17723 .Ve
17724 .ie n .IP """HAS_SHMAT_PROTOTYPE""" 4
17725 .el .IP \f(CWHAS_SHMAT_PROTOTYPE\fR 4
17726 .IX Xref "HAS_SHMAT_PROTOTYPE"
17727 .IX Item "HAS_SHMAT_PROTOTYPE"
17728 This symbol, if defined, indicates that the \fIsys/shm.h\fR includes
17729 a prototype for \f(CWshmat()\fR. Otherwise, it is up to the program to
17730 guess one. \f(CW\*(C`Shmat_t\*(C'\fR \f(CW\*(C`shmat(int, Shmat_t, int)\*(C'\fR is a good guess,
17731 but not always right so it should be emitted by the program only
17732 when \f(CW\*(C`HAS_SHMAT_PROTOTYPE\*(C'\fR is not defined to avoid conflicting defs.
17733 .ie n .IP """HAS_SOCKATMARK_PROTO""" 4
17734 .el .IP \f(CWHAS_SOCKATMARK_PROTO\fR 4
17735 .IX Xref "HAS_SOCKATMARK_PROTO"
17736 .IX Item "HAS_SOCKATMARK_PROTO"
17737 This symbol, if defined, indicates that the system provides
17738 a prototype for the \f(CWsockatmark()\fR function. Otherwise, it is up
17739 to the program to supply one. A good guess is
17740 .Sp
17741 .Vb 1
17742 \& extern int sockatmark(int);
17743 .Ve
17744 .ie n .IP """HAS_SYSCALL_PROTO""" 4
17745 .el .IP \f(CWHAS_SYSCALL_PROTO\fR 4
17746 .IX Xref "HAS_SYSCALL_PROTO"
17747 .IX Item "HAS_SYSCALL_PROTO"
17748 This symbol, if defined, indicates that the system provides
17749 a prototype for the \f(CWsyscall()\fR function. Otherwise, it is up
17750 to the program to supply one. Good guesses are
17751 .Sp
17752 .Vb 2
17753 \& extern int syscall(int, ...);
17754 \& extern int syscall(long, ...);
17755 .Ve
17756 .ie n .IP """HAS_TELLDIR_PROTO""" 4
17757 .el .IP \f(CWHAS_TELLDIR_PROTO\fR 4
17758 .IX Xref "HAS_TELLDIR_PROTO"
17759 .IX Item "HAS_TELLDIR_PROTO"
17760 This symbol, if defined, indicates that the system provides
17761 a prototype for the \f(CWtelldir()\fR function. Otherwise, it is up
17762 to the program to supply one. A good guess is
17763 .Sp
17764 .Vb 1
17765 \& extern long telldir(DIR*);
17766 .Ve
17767 .ie n .IP """NDBM_H_USES_PROTOTYPES""" 4
17768 .el .IP \f(CWNDBM_H_USES_PROTOTYPES\fR 4
17769 .IX Xref "NDBM_H_USES_PROTOTYPES"
17770 .IX Item "NDBM_H_USES_PROTOTYPES"
17771 This symbol, if defined, indicates that \fIndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C
17772 prototypes instead of K&R style function declarations without any
17773 parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
17774 K&R style function declarations will yield errors.
17775 .ie n .IP """RANDOM_R_PROTO""" 4
17776 .el .IP \f(CWRANDOM_R_PROTO\fR 4
17777 .IX Xref "RANDOM_R_PROTO"
17778 .IX Item "RANDOM_R_PROTO"
17779 This symbol encodes the prototype of \f(CW\*(C`random_r\*(C'\fR.
17780 It is zero if \f(CW\*(C`d_random_r\*(C'\fR is undef, and one of the
17781 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_random_r\*(C'\fR
17782 is defined.
17783 .ie n .IP """READDIR_R_PROTO""" 4
17784 .el .IP \f(CWREADDIR_R_PROTO\fR 4
17785 .IX Xref "READDIR_R_PROTO"
17786 .IX Item "READDIR_R_PROTO"
17787 This symbol encodes the prototype of \f(CW\*(C`readdir_r\*(C'\fR.
17788 It is zero if \f(CW\*(C`d_readdir_r\*(C'\fR is undef, and one of the
17789 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir_r\*(C'\fR
17790 is defined.
17791 .ie n .IP """SETGRENT_R_PROTO""" 4
17792 .el .IP \f(CWSETGRENT_R_PROTO\fR 4
17793 .IX Xref "SETGRENT_R_PROTO"
17794 .IX Item "SETGRENT_R_PROTO"
17795 This symbol encodes the prototype of \f(CW\*(C`setgrent_r\*(C'\fR.
17796 It is zero if \f(CW\*(C`d_setgrent_r\*(C'\fR is undef, and one of the
17797 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setgrent_r\*(C'\fR
17798 is defined.
17799 .ie n .IP """SETHOSTENT_R_PROTO""" 4
17800 .el .IP \f(CWSETHOSTENT_R_PROTO\fR 4
17801 .IX Xref "SETHOSTENT_R_PROTO"
17802 .IX Item "SETHOSTENT_R_PROTO"
17803 This symbol encodes the prototype of \f(CW\*(C`sethostent_r\*(C'\fR.
17804 It is zero if \f(CW\*(C`d_sethostent_r\*(C'\fR is undef, and one of the
17805 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_sethostent_r\*(C'\fR
17806 is defined.
17807 .ie n .IP """SETLOCALE_R_PROTO""" 4
17808 .el .IP \f(CWSETLOCALE_R_PROTO\fR 4
17809 .IX Xref "SETLOCALE_R_PROTO"
17810 .IX Item "SETLOCALE_R_PROTO"
17811 This symbol encodes the prototype of \f(CW\*(C`setlocale_r\*(C'\fR.
17812 It is zero if \f(CW\*(C`d_setlocale_r\*(C'\fR is undef, and one of the
17813 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setlocale_r\*(C'\fR
17814 is defined.
17815 .ie n .IP """SETNETENT_R_PROTO""" 4
17816 .el .IP \f(CWSETNETENT_R_PROTO\fR 4
17817 .IX Xref "SETNETENT_R_PROTO"
17818 .IX Item "SETNETENT_R_PROTO"
17819 This symbol encodes the prototype of \f(CW\*(C`setnetent_r\*(C'\fR.
17820 It is zero if \f(CW\*(C`d_setnetent_r\*(C'\fR is undef, and one of the
17821 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setnetent_r\*(C'\fR
17822 is defined.
17823 .ie n .IP """SETPROTOENT_R_PROTO""" 4
17824 .el .IP \f(CWSETPROTOENT_R_PROTO\fR 4
17825 .IX Xref "SETPROTOENT_R_PROTO"
17826 .IX Item "SETPROTOENT_R_PROTO"
17827 This symbol encodes the prototype of \f(CW\*(C`setprotoent_r\*(C'\fR.
17828 It is zero if \f(CW\*(C`d_setprotoent_r\*(C'\fR is undef, and one of the
17829 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setprotoent_r\*(C'\fR
17830 is defined.
17831 .ie n .IP """SETPWENT_R_PROTO""" 4
17832 .el .IP \f(CWSETPWENT_R_PROTO\fR 4
17833 .IX Xref "SETPWENT_R_PROTO"
17834 .IX Item "SETPWENT_R_PROTO"
17835 This symbol encodes the prototype of \f(CW\*(C`setpwent_r\*(C'\fR.
17836 It is zero if \f(CW\*(C`d_setpwent_r\*(C'\fR is undef, and one of the
17837 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setpwent_r\*(C'\fR
17838 is defined.
17839 .ie n .IP """SETSERVENT_R_PROTO""" 4
17840 .el .IP \f(CWSETSERVENT_R_PROTO\fR 4
17841 .IX Xref "SETSERVENT_R_PROTO"
17842 .IX Item "SETSERVENT_R_PROTO"
17843 This symbol encodes the prototype of \f(CW\*(C`setservent_r\*(C'\fR.
17844 It is zero if \f(CW\*(C`d_setservent_r\*(C'\fR is undef, and one of the
17845 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setservent_r\*(C'\fR
17846 is defined.
17847 .ie n .IP """SRANDOM_R_PROTO""" 4
17848 .el .IP \f(CWSRANDOM_R_PROTO\fR 4
17849 .IX Xref "SRANDOM_R_PROTO"
17850 .IX Item "SRANDOM_R_PROTO"
17851 This symbol encodes the prototype of \f(CW\*(C`srandom_r\*(C'\fR.
17852 It is zero if \f(CW\*(C`d_srandom_r\*(C'\fR is undef, and one of the
17853 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srandom_r\*(C'\fR
17854 is defined.
17855 .ie n .IP """SRAND48_R_PROTO""" 4
17856 .el .IP \f(CWSRAND48_R_PROTO\fR 4
17857 .IX Xref "SRAND48_R_PROTO"
17858 .IX Item "SRAND48_R_PROTO"
17859 This symbol encodes the prototype of \f(CW\*(C`srand48_r\*(C'\fR.
17860 It is zero if \f(CW\*(C`d_srand48_r\*(C'\fR is undef, and one of the
17861 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srand48_r\*(C'\fR
17862 is defined.
17863 .ie n .IP """STRERROR_R_PROTO""" 4
17864 .el .IP \f(CWSTRERROR_R_PROTO\fR 4
17865 .IX Xref "STRERROR_R_PROTO"
17866 .IX Item "STRERROR_R_PROTO"
17867 This symbol encodes the prototype of \f(CW\*(C`strerror_r\*(C'\fR.
17868 It is zero if \f(CW\*(C`d_strerror_r\*(C'\fR is undef, and one of the
17869 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_strerror_r\*(C'\fR
17870 is defined.
17871 .ie n .IP """TMPNAM_R_PROTO""" 4
17872 .el .IP \f(CWTMPNAM_R_PROTO\fR 4
17873 .IX Xref "TMPNAM_R_PROTO"
17874 .IX Item "TMPNAM_R_PROTO"
17875 This symbol encodes the prototype of \f(CW\*(C`tmpnam_r\*(C'\fR.
17876 It is zero if \f(CW\*(C`d_tmpnam_r\*(C'\fR is undef, and one of the
17877 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_tmpnam_r\*(C'\fR
17878 is defined.
17879 .ie n .IP """TTYNAME_R_PROTO""" 4
17880 .el .IP \f(CWTTYNAME_R_PROTO\fR 4
17881 .IX Xref "TTYNAME_R_PROTO"
17882 .IX Item "TTYNAME_R_PROTO"
17883 This symbol encodes the prototype of \f(CW\*(C`ttyname_r\*(C'\fR.
17884 It is zero if \f(CW\*(C`d_ttyname_r\*(C'\fR is undef, and one of the
17885 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ttyname_r\*(C'\fR
17886 is defined.
17887 .SH "Reference-counted stack manipulation"
17888 .IX Header "Reference-counted stack manipulation"
17889 Functions for pushing and pulling items on the stack when the
17890 stack is reference counted. They are intended as replacements
17891 for the old PUSHs, POPi, EXTEND etc pp macros within pp
17892 functions.
17893 .ie n .IP """rpp_context""" 4
17894 .el .IP \f(CWrpp_context\fR 4
17895 .IX Xref "rpp_context"
17896 .IX Item "rpp_context"
17897 NOTE: \f(CW\*(C`rpp_context\*(C'\fR is \fBexperimental\fR and may change or be
17898 removed without notice.
17899 .Sp
17900 Impose void, scalar or list context on the stack.
17901 First, pop \f(CW\*(C`extra\*(C'\fR items off the stack, then when \f(CW\*(C`gimme\*(C'\fR is:
17902 \&\f(CW\*(C`G_LIST\*(C'\fR: return as-is.
17903 \&\f(CW\*(C`G_VOID\*(C'\fR: pop everything back to \f(CW\*(C`mark\*(C'\fR
17904 \&\f(CW\*(C`G_SCALAR\*(C'\fR: move the top stack item (or \f(CW&PL_sv_undef\fR if none) to
17905 \&\f(CW\*(C`mark+1\*(C'\fR and free everything above it.
17906 .RS 4
17907 .Sp
17908 .Vb 1
17909 \& void rpp_context(SV **mark, U8 gimme, SSize_t extra)
17910 .Ve
17911 .RE
17912 .RS 4
17913 .RE
17914 .ie n .IP """rpp_extend""" 4
17915 .el .IP \f(CWrpp_extend\fR 4
17916 .IX Xref "rpp_extend"
17917 .IX Item "rpp_extend"
17918 NOTE: \f(CW\*(C`rpp_extend\*(C'\fR is \fBexperimental\fR and may change or be
17919 removed without notice.
17920 .Sp
17921 Ensures that there is space on the stack to push \f(CW\*(C`n\*(C'\fR items, extending it
17922 if necessary.
17923 .RS 4
17924 .Sp
17925 .Vb 1
17926 \& void rpp_extend(SSize_t n)
17927 .Ve
17928 .RE
17929 .RS 4
17930 .RE
17931 .ie n .IP """rpp_invoke_xs""" 4
17932 .el .IP \f(CWrpp_invoke_xs\fR 4
17933 .IX Xref "rpp_invoke_xs"
17934 .IX Item "rpp_invoke_xs"
17935 NOTE: \f(CW\*(C`rpp_invoke_xs\*(C'\fR is \fBexperimental\fR and may change or be
17936 removed without notice.
17937 .Sp
17938 Call the XS function associated with \f(CW\*(C`cv\*(C'\fR. Wraps the call if necessary to
17939 handle XS functions which are not aware of reference-counted stacks.
17940 .RS 4
17941 .Sp
17942 .Vb 1
17943 \& void rpp_invoke_xs(CV *cv)
17944 .Ve
17945 .RE
17946 .RS 4
17947 .RE
17948 .ie n .IP """rpp_is_lone""" 4
17949 .el .IP \f(CWrpp_is_lone\fR 4
17950 .IX Xref "rpp_is_lone"
17951 .IX Item "rpp_is_lone"
17952 NOTE: \f(CW\*(C`rpp_is_lone\*(C'\fR is \fBexperimental\fR and may change or be
17953 removed without notice.
17954 .Sp
17955 Indicates whether the stacked SV \f(CW\*(C`sv\*(C'\fR (assumed to be not yet popped off
17956 the stack) is only kept alive due to a single reference from the argument
17957 stack and/or and the temps stack.
17958 .Sp
17959 This can used for example to decide whether the copying of return values
17960 in rvalue context can be skipped, or whether it shouldn't be assigned to
17961 in lvalue context.
17962 .RS 4
17963 .Sp
17964 .Vb 1
17965 \& bool rpp_is_lone(SV *sv)
17966 .Ve
17967 .RE
17968 .RS 4
17969 .RE
17970 .ie n .IP """rpp_popfree_1_NN""" 4
17971 .el .IP \f(CWrpp_popfree_1_NN\fR 4
17972 .IX Xref "rpp_popfree_1_NN"
17973 .IX Item "rpp_popfree_1_NN"
17974 NOTE: \f(CW\*(C`rpp_popfree_1_NN\*(C'\fR is \fBexperimental\fR and may change or be
17975 removed without notice.
17976 .Sp
17977 A variant of \fBrpp_popfree_1()\fR which assumes that the pointer being popped
17978 off the stack is non-NULL.
17979 .RS 4
17980 .Sp
17981 .Vb 1
17982 \& void rpp_popfree_1_NN()
17983 .Ve
17984 .RE
17985 .RS 4
17986 .RE
17987 .ie n .IP """rpp_popfree_2_NN""" 4
17988 .el .IP \f(CWrpp_popfree_2_NN\fR 4
17989 .IX Xref "rpp_popfree_2_NN"
17990 .IX Item "rpp_popfree_2_NN"
17991 NOTE: \f(CW\*(C`rpp_popfree_2_NN\*(C'\fR is \fBexperimental\fR and may change or be
17992 removed without notice.
17993 .Sp
17994 A variant of \fBrpp_popfree_2()\fR which assumes that the two pointers being
17995 popped off the stack are non-NULL.
17996 .RS 4
17997 .Sp
17998 .Vb 1
17999 \& void rpp_popfree_2_NN()
18000 .Ve
18001 .RE
18002 .RS 4
18003 .RE
18004 .ie n .IP """rpp_popfree_to""" 4
18005 .el .IP \f(CWrpp_popfree_to\fR 4
18006 .IX Xref "rpp_popfree_to"
18007 .IX Item "rpp_popfree_to"
18008 NOTE: \f(CW\*(C`rpp_popfree_to\*(C'\fR is \fBexperimental\fR and may change or be
18009 removed without notice.
18010 .Sp
18011 Pop and free all items on the argument stack above \f(CW\*(C`sp\*(C'\fR. On return,
18012 \&\f(CW\*(C`PL_stack_sp\*(C'\fR will be equal to \f(CW\*(C`sp\*(C'\fR.
18013 .RS 4
18014 .Sp
18015 .Vb 1
18016 \& void rpp_popfree_to(SV **sp)
18017 .Ve
18018 .RE
18019 .RS 4
18020 .RE
18021 .ie n .IP """rpp_popfree_to_NN""" 4
18022 .el .IP \f(CWrpp_popfree_to_NN\fR 4
18023 .IX Xref "rpp_popfree_to_NN"
18024 .IX Item "rpp_popfree_to_NN"
18025 NOTE: \f(CW\*(C`rpp_popfree_to_NN\*(C'\fR is \fBexperimental\fR and may change or be
18026 removed without notice.
18027 .Sp
18028 A variant of \fBrpp_popfree_to()\fR which assumes that all the pointers being
18029 popped off the stack are non-NULL.
18030 .RS 4
18031 .Sp
18032 .Vb 1
18033 \& void rpp_popfree_to_NN(SV **sp)
18034 .Ve
18035 .RE
18036 .RS 4
18037 .RE
18038 .ie n .IP """rpp_popfree_1""" 4
18039 .el .IP \f(CWrpp_popfree_1\fR 4
18040 .IX Xref "rpp_popfree_1"
18041 .IX Item "rpp_popfree_1"
18042 NOTE: \f(CW\*(C`rpp_popfree_1\*(C'\fR is \fBexperimental\fR and may change or be
18043 removed without notice.
18044 .Sp
18045 Pop and free the top item on the argument stack and update \f(CW\*(C`PL_stack_sp\*(C'\fR.
18046 .RS 4
18047 .Sp
18048 .Vb 1
18049 \& void rpp_popfree_1()
18050 .Ve
18051 .RE
18052 .RS 4
18053 .RE
18054 .ie n .IP """rpp_popfree_2""" 4
18055 .el .IP \f(CWrpp_popfree_2\fR 4
18056 .IX Xref "rpp_popfree_2"
18057 .IX Item "rpp_popfree_2"
18058 NOTE: \f(CW\*(C`rpp_popfree_2\*(C'\fR is \fBexperimental\fR and may change or be
18059 removed without notice.
18060 .Sp
18061 Pop and free the top two items on the argument stack and update
18062 \&\f(CW\*(C`PL_stack_sp\*(C'\fR.
18063 .RS 4
18064 .Sp
18065 .Vb 1
18066 \& void rpp_popfree_2()
18067 .Ve
18068 .RE
18069 .RS 4
18070 .RE
18071 .ie n .IP """rpp_pop_1_norc""" 4
18072 .el .IP \f(CWrpp_pop_1_norc\fR 4
18073 .IX Xref "rpp_pop_1_norc"
18074 .IX Item "rpp_pop_1_norc"
18075 NOTE: \f(CW\*(C`rpp_pop_1_norc\*(C'\fR is \fBexperimental\fR and may change or be
18076 removed without notice.
18077 .Sp
18078 Pop and return the top item off the argument stack and update
18079 \&\f(CW\*(C`PL_stack_sp\*(C'\fR. It's similar to \fBrpp_popfree_1()\fR, except that it actually
18080 returns a value, and it \fIdoesn't\fR decrement the SV's reference count.
18081 On non\-\f(CW\*(C`PERL_RC_STACK\*(C'\fR builds it actually increments the SV's reference
18082 count.
18083 .Sp
18084 This is useful in cases where the popped value is immediately embedded
18085 somewhere e.g. via \fBav_store()\fR, allowing you skip decrementing and then
18086 immediately incrementing the reference count again (and risk prematurely
18087 freeing the SV if it had a RC of 1). On non-RC builds, the reference count
18088 bookkeeping still works too, which is why it should be used rather than
18089 a simple \f(CW\*(C`*PL_stack_sp\-\-\*(C'\fR.
18090 .RS 4
18091 .Sp
18092 .Vb 1
18093 \& SV * rpp_pop_1_norc()
18094 .Ve
18095 .RE
18096 .RS 4
18097 .RE
18098 .ie n .IP """rpp_push_1_norc""" 4
18099 .el .IP \f(CWrpp_push_1_norc\fR 4
18100 .IX Xref "rpp_push_1_norc"
18101 .IX Item "rpp_push_1_norc"
18102 NOTE: \f(CW\*(C`rpp_push_1_norc\*(C'\fR is \fBexperimental\fR and may change or be
18103 removed without notice.
18104 .Sp
18105 Push \f(CW\*(C`sv\*(C'\fR onto the stack without incrementing its reference count, and
18106 update \f(CW\*(C`PL_stack_sp\*(C'\fR. On non\-PERL_RC_STACK builds, mortalise too.
18107 .Sp
18108 This is most useful where an SV has just been created and already has a
18109 reference count of 1, but has not yet been anchored anywhere.
18110 .RS 4
18111 .Sp
18112 .Vb 1
18113 \& void rpp_push_1_norc(SV *sv)
18114 .Ve
18115 .RE
18116 .RS 4
18117 .RE
18118 .ie n .IP """rpp_push_1""" 4
18119 .el .IP \f(CWrpp_push_1\fR 4
18120 .IX Item "rpp_push_1"
18121 .PD 0
18122 .ie n .IP """rpp_push_IMM""" 4
18123 .el .IP \f(CWrpp_push_IMM\fR 4
18124 .IX Item "rpp_push_IMM"
18125 .ie n .IP """rpp_push_2""" 4
18126 .el .IP \f(CWrpp_push_2\fR 4
18127 .IX Item "rpp_push_2"
18128 .ie n .IP """rpp_xpush_1""" 4
18129 .el .IP \f(CWrpp_xpush_1\fR 4
18130 .IX Item "rpp_xpush_1"
18131 .ie n .IP """rpp_xpush_IMM""" 4
18132 .el .IP \f(CWrpp_xpush_IMM\fR 4
18133 .IX Item "rpp_xpush_IMM"
18134 .ie n .IP """rpp_xpush_2""" 4
18135 .el .IP \f(CWrpp_xpush_2\fR 4
18136 .IX Xref "rpp_push_1 rpp_push_IMM rpp_push_2 rpp_xpush_1 rpp_xpush_IMM rpp_xpush_2"
18137 .IX Item "rpp_xpush_2"
18138 .PD
18139 NOTE: all these forms are \fBexperimental\fR and may change or be
18140 removed without notice.
18141 .Sp
18142 Push one or two SVs onto the stack, incrementing their reference counts
18143 and updating \f(CW\*(C`PL_stack_sp\*(C'\fR. With the \f(CW\*(C`x\*(C'\fR variants, it extends the stack
18144 first. The \f(CW\*(C`IMM\*(C'\fR variants assume that the single argument is an immortal
18145 such as <&PL_sv_undef> and, for efficiency, will skip incrementing its
18146 reference count.
18147 .RS 4
18148 .Sp
18149 .Vb 6
18150 \& void rpp_push_1 (SV *sv)
18151 \& void rpp_push_IMM (SV *sv)
18152 \& void rpp_push_2 (SV *sv1, SV *sv2)
18153 \& void rpp_xpush_1 (SV *sv)
18154 \& void rpp_xpush_IMM(SV *sv)
18155 \& void rpp_xpush_2 (SV *sv1, SV *sv2)
18156 .Ve
18157 .RE
18158 .RS 4
18159 .RE
18160 .ie n .IP """rpp_replace_at""" 4
18161 .el .IP \f(CWrpp_replace_at\fR 4
18162 .IX Xref "rpp_replace_at"
18163 .IX Item "rpp_replace_at"
18164 NOTE: \f(CW\*(C`rpp_replace_at\*(C'\fR is \fBexperimental\fR and may change or be
18165 removed without notice.
18166 .Sp
18167 Replace the SV at address sp within the stack with \f(CW\*(C`sv\*(C'\fR, while suitably
18168 adjusting reference counts. Equivalent to \f(CW\*(C`*sp = sv\*(C'\fR, except with proper
18169 reference count handling.
18170 .RS 4
18171 .Sp
18172 .Vb 1
18173 \& void rpp_replace_at(SV **sp, SV *sv)
18174 .Ve
18175 .RE
18176 .RS 4
18177 .RE
18178 .ie n .IP """rpp_replace_at_NN""" 4
18179 .el .IP \f(CWrpp_replace_at_NN\fR 4
18180 .IX Xref "rpp_replace_at_NN"
18181 .IX Item "rpp_replace_at_NN"
18182 NOTE: \f(CW\*(C`rpp_replace_at_NN\*(C'\fR is \fBexperimental\fR and may change or be
18183 removed without notice.
18184 .Sp
18185 A variant of \fBrpp_replace_at()\fR which assumes that the SV pointer on the
18186 stack is non-NULL.
18187 .RS 4
18188 .Sp
18189 .Vb 1
18190 \& void rpp_replace_at_NN(SV **sp, SV *sv)
18191 .Ve
18192 .RE
18193 .RS 4
18194 .RE
18195 .ie n .IP """rpp_replace_at_norc""" 4
18196 .el .IP \f(CWrpp_replace_at_norc\fR 4
18197 .IX Xref "rpp_replace_at_norc"
18198 .IX Item "rpp_replace_at_norc"
18199 NOTE: \f(CW\*(C`rpp_replace_at_norc\*(C'\fR is \fBexperimental\fR and may change or be
18200 removed without notice.
18201 .Sp
18202 Replace the SV at address sp within the stack with \f(CW\*(C`sv\*(C'\fR, while suitably
18203 adjusting the reference count of the old SV. Equivalent to \f(CW\*(C`*sp = sv\*(C'\fR,
18204 except with proper reference count handling.
18205 .Sp
18206 \&\f(CW\*(C`sv\*(C'\fR's reference count doesn't get incremented. On non\-\f(CW\*(C`PERL_RC_STACK\*(C'\fR
18207 builds, it gets mortalised too.
18208 .Sp
18209 This is most useful where an SV has just been created and already has a
18210 reference count of 1, but has not yet been anchored anywhere.
18211 .RS 4
18212 .Sp
18213 .Vb 1
18214 \& void rpp_replace_at_norc(SV **sp, SV *sv)
18215 .Ve
18216 .RE
18217 .RS 4
18218 .RE
18219 .ie n .IP """rpp_replace_at_norc_NN""" 4
18220 .el .IP \f(CWrpp_replace_at_norc_NN\fR 4
18221 .IX Xref "rpp_replace_at_norc_NN"
18222 .IX Item "rpp_replace_at_norc_NN"
18223 NOTE: \f(CW\*(C`rpp_replace_at_norc_NN\*(C'\fR is \fBexperimental\fR and may change or be
18224 removed without notice.
18225 .Sp
18226 A variant of \fBrpp_replace_at_norc()\fR which assumes that the SV pointer on the
18227 stack is non-NULL.
18228 .RS 4
18229 .Sp
18230 .Vb 1
18231 \& void rpp_replace_at_norc_NN(SV **sp, SV *sv)
18232 .Ve
18233 .RE
18234 .RS 4
18235 .RE
18236 .ie n .IP """rpp_replace_1_1""" 4
18237 .el .IP \f(CWrpp_replace_1_1\fR 4
18238 .IX Item "rpp_replace_1_1"
18239 .PD 0
18240 .ie n .IP """rpp_replace_1_1_NN""" 4
18241 .el .IP \f(CWrpp_replace_1_1_NN\fR 4
18242 .IX Item "rpp_replace_1_1_NN"
18243 .ie n .IP """rpp_replace_1_IMM_NN""" 4
18244 .el .IP \f(CWrpp_replace_1_IMM_NN\fR 4
18245 .IX Xref "rpp_replace_1_1 rpp_replace_1_1_NN rpp_replace_1_IMM_NN"
18246 .IX Item "rpp_replace_1_IMM_NN"
18247 .PD
18248 NOTE: all these forms are \fBexperimental\fR and may change or be
18249 removed without notice.
18250 .Sp
18251 Replace the current top stack item with \f(CW\*(C`sv\*(C'\fR, while suitably adjusting
18252 reference counts. Equivalent to \fBrpp_popfree_1()\fR; rpp_push_1(sv), but
18253 is more efficient and handles both SVs being the same.
18254 .Sp
18255 The \f(CW\*(C`_NN\*(C'\fR variant assumes that the pointer on the stack to the SV being
18256 freed is non-NULL.
18257 .Sp
18258 The \f(CW\*(C`IMM_NN\*(C'\fR variant is like the \f(CW\*(C`_NN\*(C'\fR variant, but in addition, assumes
18259 that the single argument is an immortal such as <&PL_sv_undef> and, for
18260 efficiency, will skip incrementing its reference count.
18261 .RS 4
18262 .Sp
18263 .Vb 1
18264 \& void rpp_replace_1_1(SV *sv)
18265 .Ve
18266 .RE
18267 .RS 4
18268 .RE
18269 .ie n .IP """rpp_replace_2_1""" 4
18270 .el .IP \f(CWrpp_replace_2_1\fR 4
18271 .IX Item "rpp_replace_2_1"
18272 .PD 0
18273 .ie n .IP """rpp_replace_2_1_NN""" 4
18274 .el .IP \f(CWrpp_replace_2_1_NN\fR 4
18275 .IX Item "rpp_replace_2_1_NN"
18276 .ie n .IP """rpp_replace_2_IMM_NN""" 4
18277 .el .IP \f(CWrpp_replace_2_IMM_NN\fR 4
18278 .IX Xref "rpp_replace_2_1 rpp_replace_2_1_NN rpp_replace_2_IMM_NN"
18279 .IX Item "rpp_replace_2_IMM_NN"
18280 .PD
18281 NOTE: all these forms are \fBexperimental\fR and may change or be
18282 removed without notice.
18283 .Sp
18284 Replace the current top to stacks item with \f(CW\*(C`sv\*(C'\fR, while suitably
18285 adjusting reference counts. Equivalent to \fBrpp_popfree_2()\fR; rpp_push_1(sv),
18286 but is more efficient and handles SVs being the same.
18287 .Sp
18288 The \f(CW\*(C`_NN\*(C'\fR variant assumes that the pointers on the stack to the SVs being
18289 freed are non-NULL.
18290 .Sp
18291 The \f(CW\*(C`IMM_NN\*(C'\fR variant is like the \f(CW\*(C`_NN\*(C'\fR variant, but in addition, assumes
18292 that the single argument is an immortal such as <&PL_sv_undef> and, for
18293 efficiency, will skip incrementing its reference count.
18294 .RS 4
18295 .Sp
18296 .Vb 1
18297 \& void rpp_replace_2_1(SV *sv)
18298 .Ve
18299 .RE
18300 .RS 4
18301 .RE
18302 .ie n .IP """rpp_stack_is_rc""" 4
18303 .el .IP \f(CWrpp_stack_is_rc\fR 4
18304 .IX Xref "rpp_stack_is_rc"
18305 .IX Item "rpp_stack_is_rc"
18306 NOTE: \f(CW\*(C`rpp_stack_is_rc\*(C'\fR is \fBexperimental\fR and may change or be
18307 removed without notice.
18308 .Sp
18309 Returns a boolean value indicating whether the stack is currently
18310 reference-counted. Note that if the stack is split (bottom half RC, top
18311 half non-RC), this function returns false, even if the top half currently
18312 contains zero items.
18313 .RS 4
18314 .Sp
18315 .Vb 1
18316 \& bool rpp_stack_is_rc()
18317 .Ve
18318 .RE
18319 .RS 4
18320 .RE
18321 .ie n .IP """rpp_try_AMAGIC_1""" 4
18322 .el .IP \f(CWrpp_try_AMAGIC_1\fR 4
18323 .IX Item "rpp_try_AMAGIC_1"
18324 .PD 0
18325 .ie n .IP """rpp_try_AMAGIC_2""" 4
18326 .el .IP \f(CWrpp_try_AMAGIC_2\fR 4
18327 .IX Xref "rpp_try_AMAGIC_1 rpp_try_AMAGIC_2"
18328 .IX Item "rpp_try_AMAGIC_2"
18329 .PD
18330 NOTE: both forms are \fBexperimental\fR and may change or be
18331 removed without notice.
18332 .Sp
18333 Check whether either of the one or two SVs at the top of the stack is
18334 magical or a ref, and in either case handle it specially: invoke get
18335 magic, call an overload method, or replace a ref with a temporary numeric
18336 value, as appropriate. If this function returns true, it indicates that
18337 the correct return value is already on the stack. Intended to be used at
18338 the beginning of the PP function for unary or binary ops.
18339 .RS 4
18340 .Sp
18341 .Vb 1
18342 \& bool rpp_try_AMAGIC_1(int method, int flags)
18343 .Ve
18344 .RE
18345 .RS 4
18346 .RE
18347 .ie n .IP """XSPP_wrapped""" 4
18348 .el .IP \f(CWXSPP_wrapped\fR 4
18349 .IX Xref "XSPP_wrapped"
18350 .IX Item "XSPP_wrapped"
18351 NOTE: \f(CW\*(C`XSPP_wrapped\*(C'\fR is \fBexperimental\fR and may change or be
18352 removed without notice.
18353 .Sp
18354 Declare and wrap a non-reference-counted PP-style function.
18355 On traditional perl builds where the stack isn't reference-counted, this
18356 just produces a function declaration like
18357 .Sp
18358 .Vb 1
18359 \& OP * xsppw_name(pTHX)
18360 .Ve
18361 .Sp
18362 Conversely, in ref-counted builds it creates \fBxsppw_name()\fR as a small
18363 wrapper function which calls the real function via a wrapper which
18364 processes the args and return values to ensure that reference counts are
18365 properly handled for code which uses old-style dSP, \fBPUSHs()\fR, \fBPOPs()\fR etc,
18366 which don't adjust the reference counts of the items they manipulate.
18367 .Sp
18368 xsppw_nargs indicates how many arguments the function consumes off the
18369 stack. It can be a constant value or an expression, such as
18370 .Sp
18371 .Vb 1
18372 \& ((PL_op\->op_flags & OPf_STACKED) ? 2 : 1)
18373 .Ve
18374 .Sp
18375 Alternatively if xsppw_nlists is 1, it indicates that the PP function
18376 consumes a list (or \- rarely \- if 2, consumes two lists, like
18377 \&\fBpp_aassign()\fR), as indicated by the top markstack position.
18378 .Sp
18379 This is intended as a temporary fix when converting XS code to run under
18380 PERL_RC_STACK builds. In the longer term, the PP function should be
18381 rewritten to replace \fBPUSHs()\fR etc with \fBrpp_push_1()\fR etc.
18382 .RS 4
18383 .Sp
18384 .Vb 1
18385 \& XSPP_wrapped(xsppw_name, I32 xsppw_nargs, I32 xsppw_nlists)
18386 .Ve
18387 .RE
18388 .RS 4
18389 .RE
18390 .SH "REGEXP Functions"
18391 .IX Xref "RX_OFFS_END RX_OFFS_START RX_OFFS_VALID RXp_OFFS_END RXp_OFFS_START RXp_OFFS_VALID"
18392 .IX Header "REGEXP Functions"
18393 .ie n .IP """pregcomp""" 4
18394 .el .IP \f(CWpregcomp\fR 4
18395 .IX Item "pregcomp"
18396 Described in perlreguts.
18397 .RS 4
18398 .Sp
18399 .Vb 1
18400 \& REGEXP * pregcomp(SV * const pattern, const U32 flags)
18401 .Ve
18402 .RE
18403 .RS 4
18404 .RE
18405 .ie n .IP """pregexec""" 4
18406 .el .IP \f(CWpregexec\fR 4
18407 .IX Item "pregexec"
18408 Described in perlreguts.
18409 .RS 4
18410 .Sp
18411 .Vb 3
18412 \& I32 pregexec(REGEXP * const prog, char *stringarg, char *strend,
18413 \& char *strbeg, SSize_t minend, SV *screamer,
18414 \& U32 nosave)
18415 .Ve
18416 .RE
18417 .RS 4
18418 .RE
18419 .ie n .IP """re_compile""" 4
18420 .el .IP \f(CWre_compile\fR 4
18421 .IX Xref "re_compile"
18422 .IX Item "re_compile"
18423 Compile the regular expression pattern \f(CW\*(C`pattern\*(C'\fR, returning a pointer to the
18424 compiled object for later matching with the internal regex engine.
18425 .Sp
18426 This function is typically used by a custom regexp engine \f(CW\*(C`.comp()\*(C'\fR function
18427 to hand off to the core regexp engine those patterns it doesn't want to handle
18428 itself (typically passing through the same flags it was called with). In
18429 almost all other cases, a regexp should be compiled by calling "\f(CW\*(C`pregcomp\*(C'\fR"
18430 to compile using the currently active regexp engine.
18431 .Sp
18432 If \f(CW\*(C`pattern\*(C'\fR is already a \f(CW\*(C`REGEXP\*(C'\fR, this function does nothing but return a
18433 pointer to the input. Otherwise the PV is extracted and treated like a string
18434 representing a pattern. See perlre.
18435 .Sp
18436 The possible flags for \f(CW\*(C`rx_flags\*(C'\fR are documented in perlreapi. Their names
18437 all begin with \f(CW\*(C`RXf_\*(C'\fR.
18438 .RS 4
18439 .Sp
18440 .Vb 1
18441 \& REGEXP * re_compile(SV * const pattern, U32 orig_rx_flags)
18442 .Ve
18443 .RE
18444 .RS 4
18445 .RE
18446 .ie n .IP """re_dup_guts""" 4
18447 .el .IP \f(CWre_dup_guts\fR 4
18448 .IX Xref "re_dup_guts"
18449 .IX Item "re_dup_guts"
18450 Duplicate a regexp.
18451 .Sp
18452 This routine is expected to clone a given regexp structure. It is only
18453 compiled under USE_ITHREADS.
18454 .Sp
18455 After all of the core data stored in struct regexp is duplicated
18456 the \f(CW\*(C`regexp_engine.dupe\*(C'\fR method is used to copy any private data
18457 stored in the *pprivate pointer. This allows extensions to handle
18458 any duplication they need to do.
18459 .RS 4
18460 .Sp
18461 .Vb 2
18462 \& void re_dup_guts(const REGEXP *sstr, REGEXP *dstr,
18463 \& CLONE_PARAMS *param)
18464 .Ve
18465 .RE
18466 .RS 4
18467 .RE
18468 .ie n .IP """REGEX_LOCALE_CHARSET""" 4
18469 .el .IP \f(CWREGEX_LOCALE_CHARSET\fR 4
18470 .IX Item "REGEX_LOCALE_CHARSET"
18471 Described in perlreapi.
18472 .ie n .IP """REGEXP""" 4
18473 .el .IP \f(CWREGEXP\fR 4
18474 .IX Item "REGEXP"
18475 Described in perlreapi.
18476 .ie n .IP """regexp_engine""" 4
18477 .el .IP \f(CWregexp_engine\fR 4
18478 .IX Xref "regexp_engine"
18479 .IX Item "regexp_engine"
18480 When a regexp is compiled, its \f(CW\*(C`engine\*(C'\fR field is then set to point at
18481 the appropriate structure, so that when it needs to be used Perl can find
18482 the right routines to do so.
18483 .Sp
18484 In order to install a new regexp handler, \f(CW$^H{regcomp}\fR is set
18485 to an integer which (when casted appropriately) resolves to one of these
18486 structures. When compiling, the \f(CW\*(C`comp\*(C'\fR method is executed, and the
18487 resulting \f(CW\*(C`regexp\*(C'\fR structure's engine field is expected to point back at
18488 the same structure.
18489 .Sp
18490 The pTHX_ symbol in the definition is a macro used by Perl under threading
18491 to provide an extra argument to the routine holding a pointer back to
18492 the interpreter that is executing the regexp. So under threading all
18493 routines get an extra argument.
18494 .ie n .IP """regexp_paren_pair""" 4
18495 .el .IP \f(CWregexp_paren_pair\fR 4
18496 .IX Item "regexp_paren_pair"
18497 Described in perlreapi.
18498 .ie n .IP """regmatch_info""" 4
18499 .el .IP \f(CWregmatch_info\fR 4
18500 .IX Xref "regmatch_info"
18501 .IX Item "regmatch_info"
18502 Some basic information about the current match that is created by
18503 Perl_regexec_flags and then passed to \fBregtry()\fR, \fBregmatch()\fR etc.
18504 It is allocated as a local var on the stack, so nothing should be
18505 stored in it that needs preserving or clearing up on \fBcroak()\fR.
18506 For that, see the aux_info and aux_info_eval members of the
18507 regmatch_state union.
18508 .ie n .IP """REXEC_COPY_SKIP_POST""" 4
18509 .el .IP \f(CWREXEC_COPY_SKIP_POST\fR 4
18510 .IX Item "REXEC_COPY_SKIP_POST"
18511 .PD 0
18512 .ie n .IP """REXEC_COPY_SKIP_PRE""" 4
18513 .el .IP \f(CWREXEC_COPY_SKIP_PRE\fR 4
18514 .IX Item "REXEC_COPY_SKIP_PRE"
18515 .ie n .IP """REXEC_COPY_STR""" 4
18516 .el .IP \f(CWREXEC_COPY_STR\fR 4
18517 .IX Item "REXEC_COPY_STR"
18518 .PD
18519 Described in perlreapi.
18520 .ie n .IP """RXapif_ALL""" 4
18521 .el .IP \f(CWRXapif_ALL\fR 4
18522 .IX Item "RXapif_ALL"
18523 .PD 0
18524 .ie n .IP """RXapif_CLEAR""" 4
18525 .el .IP \f(CWRXapif_CLEAR\fR 4
18526 .IX Item "RXapif_CLEAR"
18527 .ie n .IP """RXapif_DELETE""" 4
18528 .el .IP \f(CWRXapif_DELETE\fR 4
18529 .IX Item "RXapif_DELETE"
18530 .ie n .IP """RXapif_EXISTS""" 4
18531 .el .IP \f(CWRXapif_EXISTS\fR 4
18532 .IX Item "RXapif_EXISTS"
18533 .ie n .IP """RXapif_FETCH""" 4
18534 .el .IP \f(CWRXapif_FETCH\fR 4
18535 .IX Item "RXapif_FETCH"
18536 .ie n .IP """RXapif_FIRSTKEY""" 4
18537 .el .IP \f(CWRXapif_FIRSTKEY\fR 4
18538 .IX Item "RXapif_FIRSTKEY"
18539 .ie n .IP """RXapif_NEXTKEY""" 4
18540 .el .IP \f(CWRXapif_NEXTKEY\fR 4
18541 .IX Item "RXapif_NEXTKEY"
18542 .ie n .IP """RXapif_ONE""" 4
18543 .el .IP \f(CWRXapif_ONE\fR 4
18544 .IX Item "RXapif_ONE"
18545 .ie n .IP """RXapif_REGNAME""" 4
18546 .el .IP \f(CWRXapif_REGNAME\fR 4
18547 .IX Item "RXapif_REGNAME"
18548 .ie n .IP """RXapif_REGNAMES""" 4
18549 .el .IP \f(CWRXapif_REGNAMES\fR 4
18550 .IX Item "RXapif_REGNAMES"
18551 .ie n .IP """RXapif_REGNAMES_COUNT""" 4
18552 .el .IP \f(CWRXapif_REGNAMES_COUNT\fR 4
18553 .IX Item "RXapif_REGNAMES_COUNT"
18554 .ie n .IP """RXapif_SCALAR""" 4
18555 .el .IP \f(CWRXapif_SCALAR\fR 4
18556 .IX Item "RXapif_SCALAR"
18557 .ie n .IP """RXapif_STORE""" 4
18558 .el .IP \f(CWRXapif_STORE\fR 4
18559 .IX Item "RXapif_STORE"
18560 .PD
18561 Described in perlreapi.
18562 .ie n .IP """RX_BUFF_IDX_CARET_FULLMATCH""" 4
18563 .el .IP \f(CWRX_BUFF_IDX_CARET_FULLMATCH\fR 4
18564 .IX Item "RX_BUFF_IDX_CARET_FULLMATCH"
18565 .PD 0
18566 .ie n .IP """RX_BUFF_IDX_CARET_POSTMATCH""" 4
18567 .el .IP \f(CWRX_BUFF_IDX_CARET_POSTMATCH\fR 4
18568 .IX Item "RX_BUFF_IDX_CARET_POSTMATCH"
18569 .ie n .IP """RX_BUFF_IDX_CARET_PREMATCH""" 4
18570 .el .IP \f(CWRX_BUFF_IDX_CARET_PREMATCH\fR 4
18571 .IX Item "RX_BUFF_IDX_CARET_PREMATCH"
18572 .ie n .IP """RX_BUFF_IDX_FULLMATCH""" 4
18573 .el .IP \f(CWRX_BUFF_IDX_FULLMATCH\fR 4
18574 .IX Item "RX_BUFF_IDX_FULLMATCH"
18575 .ie n .IP """RX_BUFF_IDX_POSTMATCH""" 4
18576 .el .IP \f(CWRX_BUFF_IDX_POSTMATCH\fR 4
18577 .IX Item "RX_BUFF_IDX_POSTMATCH"
18578 .ie n .IP """RX_BUFF_IDX_PREMATCH""" 4
18579 .el .IP \f(CWRX_BUFF_IDX_PREMATCH\fR 4
18580 .IX Item "RX_BUFF_IDX_PREMATCH"
18581 .PD
18582 Described in perlreapi.
18583 .ie n .IP """RXf_NO_INPLACE_SUBST""" 4
18584 .el .IP \f(CWRXf_NO_INPLACE_SUBST\fR 4
18585 .IX Item "RXf_NO_INPLACE_SUBST"
18586 .PD 0
18587 .ie n .IP """RXf_NULL""" 4
18588 .el .IP \f(CWRXf_NULL\fR 4
18589 .IX Item "RXf_NULL"
18590 .ie n .IP """RXf_SKIPWHITE""" 4
18591 .el .IP \f(CWRXf_SKIPWHITE\fR 4
18592 .IX Item "RXf_SKIPWHITE"
18593 .ie n .IP """RXf_SPLIT""" 4
18594 .el .IP \f(CWRXf_SPLIT\fR 4
18595 .IX Item "RXf_SPLIT"
18596 .ie n .IP """RXf_START_ONLY""" 4
18597 .el .IP \f(CWRXf_START_ONLY\fR 4
18598 .IX Item "RXf_START_ONLY"
18599 .ie n .IP """RXf_WHITE""" 4
18600 .el .IP \f(CWRXf_WHITE\fR 4
18601 .IX Item "RXf_WHITE"
18602 .PD
18603 Described in perlreapi.
18604 .ie n .IP """RXf_PMf_EXTENDED""" 4
18605 .el .IP \f(CWRXf_PMf_EXTENDED\fR 4
18606 .IX Item "RXf_PMf_EXTENDED"
18607 .PD 0
18608 .ie n .IP """RXf_PMf_FOLD""" 4
18609 .el .IP \f(CWRXf_PMf_FOLD\fR 4
18610 .IX Item "RXf_PMf_FOLD"
18611 .ie n .IP """RXf_PMf_KEEPCOPY""" 4
18612 .el .IP \f(CWRXf_PMf_KEEPCOPY\fR 4
18613 .IX Item "RXf_PMf_KEEPCOPY"
18614 .ie n .IP """RXf_PMf_MULTILINE""" 4
18615 .el .IP \f(CWRXf_PMf_MULTILINE\fR 4
18616 .IX Item "RXf_PMf_MULTILINE"
18617 .ie n .IP """RXf_PMf_SINGLELINE""" 4
18618 .el .IP \f(CWRXf_PMf_SINGLELINE\fR 4
18619 .IX Item "RXf_PMf_SINGLELINE"
18620 .PD
18621 Described in perlreapi.
18622 .ie n .IP """RX_MATCH_COPIED""" 4
18623 .el .IP \f(CWRX_MATCH_COPIED\fR 4
18624 .IX Item "RX_MATCH_COPIED"
18625 Described in perlreapi.
18626 .RS 4
18627 .Sp
18628 .Vb 1
18629 \& RX_MATCH_COPIED(const REGEXP * rx_sv)
18630 .Ve
18631 .RE
18632 .RS 4
18633 .RE
18634 .ie n .IP """struct regexp""" 4
18635 .el .IP "\f(CWstruct regexp\fR" 4
18636 .IX Item "struct regexp"
18637 Described in perlreapi.
18638 .ie n .IP """SvRX""" 4
18639 .el .IP \f(CWSvRX\fR 4
18640 .IX Xref "SvRX"
18641 .IX Item "SvRX"
18642 Convenience macro to get the REGEXP from a SV. This is approximately
18643 equivalent to the following snippet:
18644 .Sp
18645 .Vb 6
18646 \& if (SvMAGICAL(sv))
18647 \& mg_get(sv);
18648 \& if (SvROK(sv))
18649 \& sv = MUTABLE_SV(SvRV(sv));
18650 \& if (SvTYPE(sv) == SVt_REGEXP)
18651 \& return (REGEXP*) sv;
18652 .Ve
18653 .Sp
18654 \&\f(CW\*(C`NULL\*(C'\fR will be returned if a REGEXP* is not found.
18655 .RS 4
18656 .Sp
18657 .Vb 1
18658 \& REGEXP * SvRX(SV *sv)
18659 .Ve
18660 .RE
18661 .RS 4
18662 .RE
18663 .ie n .IP """SvRXOK""" 4
18664 .el .IP \f(CWSvRXOK\fR 4
18665 .IX Xref "SvRXOK"
18666 .IX Item "SvRXOK"
18667 Returns a boolean indicating whether the SV (or the one it references)
18668 is a REGEXP.
18669 .Sp
18670 If you want to do something with the REGEXP* later use SvRX instead
18671 and check for NULL.
18672 .RS 4
18673 .Sp
18674 .Vb 1
18675 \& bool SvRXOK(SV* sv)
18676 .Ve
18677 .RE
18678 .RS 4
18679 .RE
18680 .ie n .IP """SV_SAVED_COPY""" 4
18681 .el .IP \f(CWSV_SAVED_COPY\fR 4
18682 .IX Item "SV_SAVED_COPY"
18683 Described in perlreapi.
18684 .SH "Reports and Formats"
18685 .IX Header "Reports and Formats"
18686 These are used in the simple report generation feature of Perl.
18687 See perlform.
18688 .ie n .IP """IoBOTTOM_GV""" 4
18689 .el .IP \f(CWIoBOTTOM_GV\fR 4
18690 .IX Item "IoBOTTOM_GV"
18691 Described in perlguts.
18692 .RS 4
18693 .Sp
18694 .Vb 1
18695 \& GV * IoBOTTOM_GV(IO *io)
18696 .Ve
18697 .RE
18698 .RS 4
18699 .RE
18700 .ie n .IP """IoBOTTOM_NAME""" 4
18701 .el .IP \f(CWIoBOTTOM_NAME\fR 4
18702 .IX Item "IoBOTTOM_NAME"
18703 Described in perlguts.
18704 .RS 4
18705 .Sp
18706 .Vb 1
18707 \& char * IoBOTTOM_NAME(IO *io)
18708 .Ve
18709 .RE
18710 .RS 4
18711 .RE
18712 .ie n .IP """IoFMT_GV""" 4
18713 .el .IP \f(CWIoFMT_GV\fR 4
18714 .IX Item "IoFMT_GV"
18715 Described in perlguts.
18716 .RS 4
18717 .Sp
18718 .Vb 1
18719 \& GV * IoFMT_GV(IO *io)
18720 .Ve
18721 .RE
18722 .RS 4
18723 .RE
18724 .ie n .IP """IoFMT_NAME""" 4
18725 .el .IP \f(CWIoFMT_NAME\fR 4
18726 .IX Item "IoFMT_NAME"
18727 Described in perlguts.
18728 .RS 4
18729 .Sp
18730 .Vb 1
18731 \& char * IoFMT_NAME(IO *io)
18732 .Ve
18733 .RE
18734 .RS 4
18735 .RE
18736 .ie n .IP """IoLINES""" 4
18737 .el .IP \f(CWIoLINES\fR 4
18738 .IX Item "IoLINES"
18739 Described in perlguts.
18740 .RS 4
18741 .Sp
18742 .Vb 1
18743 \& IV IoLINES(IO *io)
18744 .Ve
18745 .RE
18746 .RS 4
18747 .RE
18748 .ie n .IP """IoLINES_LEFT""" 4
18749 .el .IP \f(CWIoLINES_LEFT\fR 4
18750 .IX Item "IoLINES_LEFT"
18751 Described in perlguts.
18752 .RS 4
18753 .Sp
18754 .Vb 1
18755 \& IV IoLINES_LEFT(IO *io)
18756 .Ve
18757 .RE
18758 .RS 4
18759 .RE
18760 .ie n .IP """IoPAGE""" 4
18761 .el .IP \f(CWIoPAGE\fR 4
18762 .IX Item "IoPAGE"
18763 Described in perlguts.
18764 .RS 4
18765 .Sp
18766 .Vb 1
18767 \& IV IoPAGE(IO *io)
18768 .Ve
18769 .RE
18770 .RS 4
18771 .RE
18772 .ie n .IP """IoPAGE_LEN""" 4
18773 .el .IP \f(CWIoPAGE_LEN\fR 4
18774 .IX Item "IoPAGE_LEN"
18775 Described in perlguts.
18776 .RS 4
18777 .Sp
18778 .Vb 1
18779 \& IV IoPAGE_LEN(IO *io)
18780 .Ve
18781 .RE
18782 .RS 4
18783 .RE
18784 .ie n .IP """IoTOP_GV""" 4
18785 .el .IP \f(CWIoTOP_GV\fR 4
18786 .IX Item "IoTOP_GV"
18787 Described in perlguts.
18788 .RS 4
18789 .Sp
18790 .Vb 1
18791 \& GV * IoTOP_GV(IO *io)
18792 .Ve
18793 .RE
18794 .RS 4
18795 .RE
18796 .ie n .IP """IoTOP_NAME""" 4
18797 .el .IP \f(CWIoTOP_NAME\fR 4
18798 .IX Item "IoTOP_NAME"
18799 Described in perlguts.
18800 .RS 4
18801 .Sp
18802 .Vb 1
18803 \& char * IoTOP_NAME(IO *io)
18804 .Ve
18805 .RE
18806 .RS 4
18807 .RE
18808 .SH Signals
18809 .IX Header "Signals"
18810 .ie n .IP """HAS_SIGINFO_SI_ADDR""" 4
18811 .el .IP \f(CWHAS_SIGINFO_SI_ADDR\fR 4
18812 .IX Xref "HAS_SIGINFO_SI_ADDR"
18813 .IX Item "HAS_SIGINFO_SI_ADDR"
18814 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
18815 \&\f(CW\*(C`si_addr\*(C'\fR member
18816 .ie n .IP """HAS_SIGINFO_SI_BAND""" 4
18817 .el .IP \f(CWHAS_SIGINFO_SI_BAND\fR 4
18818 .IX Xref "HAS_SIGINFO_SI_BAND"
18819 .IX Item "HAS_SIGINFO_SI_BAND"
18820 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
18821 \&\f(CW\*(C`si_band\*(C'\fR member
18822 .ie n .IP """HAS_SIGINFO_SI_ERRNO""" 4
18823 .el .IP \f(CWHAS_SIGINFO_SI_ERRNO\fR 4
18824 .IX Xref "HAS_SIGINFO_SI_ERRNO"
18825 .IX Item "HAS_SIGINFO_SI_ERRNO"
18826 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
18827 \&\f(CW\*(C`si_errno\*(C'\fR member
18828 .ie n .IP """HAS_SIGINFO_SI_PID""" 4
18829 .el .IP \f(CWHAS_SIGINFO_SI_PID\fR 4
18830 .IX Xref "HAS_SIGINFO_SI_PID"
18831 .IX Item "HAS_SIGINFO_SI_PID"
18832 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
18833 \&\f(CW\*(C`si_pid\*(C'\fR member
18834 .ie n .IP """HAS_SIGINFO_SI_STATUS""" 4
18835 .el .IP \f(CWHAS_SIGINFO_SI_STATUS\fR 4
18836 .IX Xref "HAS_SIGINFO_SI_STATUS"
18837 .IX Item "HAS_SIGINFO_SI_STATUS"
18838 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
18839 \&\f(CW\*(C`si_status\*(C'\fR member
18840 .ie n .IP """HAS_SIGINFO_SI_UID""" 4
18841 .el .IP \f(CWHAS_SIGINFO_SI_UID\fR 4
18842 .IX Xref "HAS_SIGINFO_SI_UID"
18843 .IX Item "HAS_SIGINFO_SI_UID"
18844 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
18845 \&\f(CW\*(C`si_uid\*(C'\fR member
18846 .ie n .IP """HAS_SIGINFO_SI_VALUE""" 4
18847 .el .IP \f(CWHAS_SIGINFO_SI_VALUE\fR 4
18848 .IX Xref "HAS_SIGINFO_SI_VALUE"
18849 .IX Item "HAS_SIGINFO_SI_VALUE"
18850 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
18851 \&\f(CW\*(C`si_value\*(C'\fR member
18852 .ie n .IP """PERL_SIGNALS_UNSAFE_FLAG""" 4
18853 .el .IP \f(CWPERL_SIGNALS_UNSAFE_FLAG\fR 4
18854 .IX Xref "PERL_SIGNALS_UNSAFE_FLAG"
18855 .IX Item "PERL_SIGNALS_UNSAFE_FLAG"
18856 If this bit in \f(CW\*(C`PL_signals\*(C'\fR is set, the system is uing the pre-Perl 5.8
18857 unsafe signals. See "PERL_SIGNALS" in perlrun and "Deferred Signals
18858 (Safe Signals)" in perlipc.
18859 .RS 4
18860 .Sp
18861 .Vb 1
18862 \& U32 PERL_SIGNALS_UNSAFE_FLAG
18863 .Ve
18864 .RE
18865 .RS 4
18866 .RE
18867 .ie n .IP """rsignal""" 4
18868 .el .IP \f(CWrsignal\fR 4
18869 .IX Xref "rsignal"
18870 .IX Item "rsignal"
18871 A wrapper for the C library functions \fBsigaction\fR\|(2) or \fBsignal\fR\|(2).
18872 Use this instead of those libc functions, as the Perl version gives the
18873 safest available implementation, and knows things that interact with the
18874 rest of the perl interpreter.
18875 .RS 4
18876 .Sp
18877 .Vb 1
18878 \& Sighandler_t rsignal(int i, Sighandler_t t)
18879 .Ve
18880 .RE
18881 .RS 4
18882 .RE
18883 .ie n .IP """rsignal_state""" 4
18884 .el .IP \f(CWrsignal_state\fR 4
18885 .IX Xref "rsignal_state"
18886 .IX Item "rsignal_state"
18887 Returns a the current signal handler for signal \f(CW\*(C`signo\*(C'\fR.
18888 See "\f(CW\*(C`rsignal\*(C'\fR".
18889 .RS 4
18890 .Sp
18891 .Vb 1
18892 \& Sighandler_t rsignal_state(int i)
18893 .Ve
18894 .RE
18895 .RS 4
18896 .RE
18897 .ie n .IP """Sigjmp_buf""" 4
18898 .el .IP \f(CWSigjmp_buf\fR 4
18899 .IX Xref "Sigjmp_buf"
18900 .IX Item "Sigjmp_buf"
18901 This is the buffer type to be used with Sigsetjmp and Siglongjmp.
18902 .ie n .IP """Siglongjmp""" 4
18903 .el .IP \f(CWSiglongjmp\fR 4
18904 .IX Xref "Siglongjmp"
18905 .IX Item "Siglongjmp"
18906 This macro is used in the same way as \f(CWsiglongjmp()\fR, but will invoke
18907 traditional \f(CWlongjmp()\fR if siglongjmp isn't available.
18908 See \f(CW"HAS_SIGSETJMP"\fR.
18909 .RS 4
18910 .Sp
18911 .Vb 1
18912 \& void Siglongjmp(jmp_buf env, int val)
18913 .Ve
18914 .RE
18915 .RS 4
18916 .RE
18917 .ie n .IP """SIG_NAME""" 4
18918 .el .IP \f(CWSIG_NAME\fR 4
18919 .IX Xref "SIG_NAME"
18920 .IX Item "SIG_NAME"
18921 This symbol contains a list of signal names in order of
18922 signal number. This is intended
18923 to be used as a static array initialization, like this:
18924 .Sp
18925 .Vb 1
18926 \& char *sig_name[] = { SIG_NAME };
18927 .Ve
18928 .Sp
18929 The signals in the list are separated with commas, and each signal
18930 is surrounded by double quotes. There is no leading \f(CW\*(C`SIG\*(C'\fR in the signal
18931 name, i.e. \f(CW\*(C`SIGQUIT\*(C'\fR is known as "\f(CW\*(C`QUIT\*(C'\fR".
18932 Gaps in the signal numbers (up to \f(CW\*(C`NSIG\*(C'\fR) are filled in with \f(CW\*(C`NUMnn\*(C'\fR,
18933 etc., where nn is the actual signal number (e.g. \f(CW\*(C`NUM37\*(C'\fR).
18934 The signal number for \f(CW\*(C`sig_name[i]\*(C'\fR is stored in \f(CW\*(C`sig_num[i]\*(C'\fR.
18935 The last element is 0 to terminate the list with a \f(CW\*(C`NULL\*(C'\fR. This
18936 corresponds to the 0 at the end of the \f(CW\*(C`sig_name_init\*(C'\fR list.
18937 Note that this variable is initialized from the \f(CW\*(C`sig_name_init\*(C'\fR,
18938 not from \f(CW\*(C`sig_name\*(C'\fR (which is unused).
18939 .ie n .IP """SIG_NUM""" 4
18940 .el .IP \f(CWSIG_NUM\fR 4
18941 .IX Xref "SIG_NUM"
18942 .IX Item "SIG_NUM"
18943 This symbol contains a list of signal numbers, in the same order as the
18944 \&\f(CW\*(C`SIG_NAME\*(C'\fR list. It is suitable for static array initialization, as in:
18945 .Sp
18946 .Vb 1
18947 \& int sig_num[] = { SIG_NUM };
18948 .Ve
18949 .Sp
18950 The signals in the list are separated with commas, and the indices
18951 within that list and the \f(CW\*(C`SIG_NAME\*(C'\fR list match, so it's easy to compute
18952 the signal name from a number or vice versa at the price of a small
18953 dynamic linear lookup.
18954 Duplicates are allowed, but are moved to the end of the list.
18955 The signal number corresponding to \f(CW\*(C`sig_name[i]\*(C'\fR is \f(CW\*(C`sig_number[i]\*(C'\fR.
18956 if (i < \f(CW\*(C`NSIG\*(C'\fR) then \f(CW\*(C`sig_number[i]\*(C'\fR == i.
18957 The last element is 0, corresponding to the 0 at the end of
18958 the \f(CW\*(C`sig_name_init\*(C'\fR list.
18959 Note that this variable is initialized from the \f(CW\*(C`sig_num_init\*(C'\fR,
18960 not from \f(CW\*(C`sig_num\*(C'\fR (which is unused).
18961 .ie n .IP """Sigsetjmp""" 4
18962 .el .IP \f(CWSigsetjmp\fR 4
18963 .IX Xref "Sigsetjmp"
18964 .IX Item "Sigsetjmp"
18965 This macro is used in the same way as \f(CWsigsetjmp()\fR, but will invoke
18966 traditional \f(CWsetjmp()\fR if sigsetjmp isn't available.
18967 See \f(CW"HAS_SIGSETJMP"\fR.
18968 .RS 4
18969 .Sp
18970 .Vb 1
18971 \& int Sigsetjmp(jmp_buf env, int savesigs)
18972 .Ve
18973 .RE
18974 .RS 4
18975 .RE
18976 .ie n .IP """SIG_SIZE""" 4
18977 .el .IP \f(CWSIG_SIZE\fR 4
18978 .IX Xref "SIG_SIZE"
18979 .IX Item "SIG_SIZE"
18980 This variable contains the number of elements of the \f(CW\*(C`SIG_NAME\*(C'\fR
18981 and \f(CW\*(C`SIG_NUM\*(C'\fR arrays, excluding the final \f(CW\*(C`NULL\*(C'\fR entry.
18982 .ie n .IP """whichsig""" 4
18983 .el .IP \f(CWwhichsig\fR 4
18984 .IX Item "whichsig"
18985 .PD 0
18986 .ie n .IP """whichsig_pv""" 4
18987 .el .IP \f(CWwhichsig_pv\fR 4
18988 .IX Item "whichsig_pv"
18989 .ie n .IP """whichsig_pvn""" 4
18990 .el .IP \f(CWwhichsig_pvn\fR 4
18991 .IX Item "whichsig_pvn"
18992 .ie n .IP """whichsig_sv""" 4
18993 .el .IP \f(CWwhichsig_sv\fR 4
18994 .IX Xref "whichsig whichsig_pv whichsig_pvn whichsig_sv"
18995 .IX Item "whichsig_sv"
18996 .PD
18997 These all convert a signal name into its corresponding signal number;
18998 returning \-1 if no corresponding number was found.
18999 .Sp
19000 They differ only in the source of the signal name:
19001 .Sp
19002 \&\f(CW\*(C`whichsig_pv\*(C'\fR takes the name from the \f(CW\*(C`NUL\*(C'\fR\-terminated string starting at
19003 \&\f(CW\*(C`sig\*(C'\fR.
19004 .Sp
19005 \&\f(CW\*(C`whichsig\*(C'\fR is merely a different spelling, a synonym, of \f(CW\*(C`whichsig_pv\*(C'\fR.
19006 .Sp
19007 \&\f(CW\*(C`whichsig_pvn\*(C'\fR takes the name from the string starting at \f(CW\*(C`sig\*(C'\fR, with length
19008 \&\f(CW\*(C`len\*(C'\fR bytes.
19009 .Sp
19010 \&\f(CW\*(C`whichsig_sv\*(C'\fR takes the name from the PV stored in the SV \f(CW\*(C`sigsv\*(C'\fR.
19011 .RS 4
19012 .Sp
19013 .Vb 4
19014 \& I32 whichsig (const char *sig)
19015 \& I32 whichsig_pv (const char *sig)
19016 \& I32 whichsig_pvn(const char *sig, STRLEN len)
19017 \& I32 whichsig_sv (SV *sigsv)
19018 .Ve
19019 .RE
19020 .RS 4
19021 .RE
19022 .SH "Site configuration"
19023 .IX Header "Site configuration"
19024 These variables give details as to where various libraries,
19025 installation destinations, \fIetc.\fR, go, as well as what various
19026 installation options were selected
19027 .ie n .IP """ARCHLIB""" 4
19028 .el .IP \f(CWARCHLIB\fR 4
19029 .IX Xref "ARCHLIB"
19030 .IX Item "ARCHLIB"
19031 This variable, if defined, holds the name of the directory in
19032 which the user wants to put architecture-dependent public
19033 library files for perl5. It is most often a local directory
19034 such as \fI/usr/local/lib\fR. Programs using this variable must be
19035 prepared to deal with filename expansion. If \f(CW\*(C`ARCHLIB\*(C'\fR is the
19036 same as \f(CW\*(C`PRIVLIB\*(C'\fR, it is not defined, since presumably the
19037 program already searches \f(CW\*(C`PRIVLIB\*(C'\fR.
19038 .ie n .IP """ARCHLIB_EXP""" 4
19039 .el .IP \f(CWARCHLIB_EXP\fR 4
19040 .IX Xref "ARCHLIB_EXP"
19041 .IX Item "ARCHLIB_EXP"
19042 This symbol contains the ~name expanded version of \f(CW\*(C`ARCHLIB\*(C'\fR, to be used
19043 in programs that are not prepared to deal with ~ expansion at run-time.
19044 .ie n .IP """ARCHNAME""" 4
19045 .el .IP \f(CWARCHNAME\fR 4
19046 .IX Xref "ARCHNAME"
19047 .IX Item "ARCHNAME"
19048 This symbol holds a string representing the architecture name.
19049 It may be used to construct an architecture-dependant pathname
19050 where library files may be held under a private library, for
19051 instance.
19052 .ie n .IP """BIN""" 4
19053 .el .IP \f(CWBIN\fR 4
19054 .IX Xref "BIN"
19055 .IX Item "BIN"
19056 This symbol holds the path of the bin directory where the package will
19057 be installed. Program must be prepared to deal with ~name substitution.
19058 .ie n .IP """BIN_EXP""" 4
19059 .el .IP \f(CWBIN_EXP\fR 4
19060 .IX Xref "BIN_EXP"
19061 .IX Item "BIN_EXP"
19062 This symbol is the filename expanded version of the \f(CW\*(C`BIN\*(C'\fR symbol, for
19063 programs that do not want to deal with that at run-time.
19064 .ie n .IP """INSTALL_USR_BIN_PERL""" 4
19065 .el .IP \f(CWINSTALL_USR_BIN_PERL\fR 4
19066 .IX Xref "INSTALL_USR_BIN_PERL"
19067 .IX Item "INSTALL_USR_BIN_PERL"
19068 This symbol, if defined, indicates that Perl is to be installed
19069 also as \fI/usr/bin/perl\fR.
19070 .ie n .IP """MULTIARCH""" 4
19071 .el .IP \f(CWMULTIARCH\fR 4
19072 .IX Xref "MULTIARCH"
19073 .IX Item "MULTIARCH"
19074 This symbol, if defined, signifies that the build
19075 process will produce some binary files that are going to be
19076 used in a cross-platform environment. This is the case for
19077 example with the NeXT "fat" binaries that contain executables
19078 for several \f(CW\*(C`CPUs\*(C'\fR.
19079 .ie n .IP """PERL_INC_VERSION_LIST""" 4
19080 .el .IP \f(CWPERL_INC_VERSION_LIST\fR 4
19081 .IX Xref "PERL_INC_VERSION_LIST"
19082 .IX Item "PERL_INC_VERSION_LIST"
19083 This variable specifies the list of subdirectories in over
19084 which \fIperl.c\fR:\f(CWincpush()\fR and \fIlib/lib.pm\fR will automatically
19085 search when adding directories to @\f(CW\*(C`INC\*(C'\fR, in a format suitable
19086 for a C initialization string. See the \f(CW\*(C`inc_version_list\*(C'\fR entry
19087 in Porting/Glossary for more details.
19088 .ie n .IP """PERL_OTHERLIBDIRS""" 4
19089 .el .IP \f(CWPERL_OTHERLIBDIRS\fR 4
19090 .IX Xref "PERL_OTHERLIBDIRS"
19091 .IX Item "PERL_OTHERLIBDIRS"
19092 This variable contains a colon-separated set of paths for the perl
19093 binary to search for additional library files or modules.
19094 These directories will be tacked to the end of @\f(CW\*(C`INC\*(C'\fR.
19095 Perl will automatically search below each path for version\-
19096 and architecture-specific directories. See \f(CW"PERL_INC_VERSION_LIST"\fR
19097 for more details.
19098 .ie n .IP """PERL_RELOCATABLE_INC""" 4
19099 .el .IP \f(CWPERL_RELOCATABLE_INC\fR 4
19100 .IX Xref "PERL_RELOCATABLE_INC"
19101 .IX Item "PERL_RELOCATABLE_INC"
19102 This symbol, if defined, indicates that we'd like to relocate entries
19103 in @\f(CW\*(C`INC\*(C'\fR at run time based on the location of the perl binary.
19104 .ie n .IP """PERL_TARGETARCH""" 4
19105 .el .IP \f(CWPERL_TARGETARCH\fR 4
19106 .IX Xref "PERL_TARGETARCH"
19107 .IX Item "PERL_TARGETARCH"
19108 This symbol, if defined, indicates the target architecture
19109 Perl has been cross-compiled to. Undefined if not a cross-compile.
19110 .ie n .IP """PERL_USE_DEVEL""" 4
19111 .el .IP \f(CWPERL_USE_DEVEL\fR 4
19112 .IX Xref "PERL_USE_DEVEL"
19113 .IX Item "PERL_USE_DEVEL"
19114 This symbol, if defined, indicates that Perl was configured with
19115 \&\f(CW\*(C`\-Dusedevel\*(C'\fR, to enable development features. This should not be
19116 done for production builds.
19117 .ie n .IP """PERL_VENDORARCH""" 4
19118 .el .IP \f(CWPERL_VENDORARCH\fR 4
19119 .IX Xref "PERL_VENDORARCH"
19120 .IX Item "PERL_VENDORARCH"
19121 If defined, this symbol contains the name of a private library.
19122 The library is private in the sense that it needn't be in anyone's
19123 execution path, but it should be accessible by the world.
19124 It may have a ~ on the front.
19125 The standard distribution will put nothing in this directory.
19126 Vendors who distribute perl may wish to place their own
19127 architecture-dependent modules and extensions in this directory with
19128 .Sp
19129 .Vb 1
19130 \& MakeMaker Makefile.PL INSTALLDIRS=vendor
19131 .Ve
19132 .Sp
19133 or equivalent. See \f(CW\*(C`INSTALL\*(C'\fR for details.
19134 .ie n .IP """PERL_VENDORARCH_EXP""" 4
19135 .el .IP \f(CWPERL_VENDORARCH_EXP\fR 4
19136 .IX Xref "PERL_VENDORARCH_EXP"
19137 .IX Item "PERL_VENDORARCH_EXP"
19138 This symbol contains the ~name expanded version of \f(CW\*(C`PERL_VENDORARCH\*(C'\fR, to be used
19139 in programs that are not prepared to deal with ~ expansion at run-time.
19140 .ie n .IP """PERL_VENDORLIB_EXP""" 4
19141 .el .IP \f(CWPERL_VENDORLIB_EXP\fR 4
19142 .IX Xref "PERL_VENDORLIB_EXP"
19143 .IX Item "PERL_VENDORLIB_EXP"
19144 This symbol contains the ~name expanded version of \f(CW\*(C`VENDORLIB\*(C'\fR, to be used
19145 in programs that are not prepared to deal with ~ expansion at run-time.
19146 .ie n .IP """PERL_VENDORLIB_STEM""" 4
19147 .el .IP \f(CWPERL_VENDORLIB_STEM\fR 4
19148 .IX Xref "PERL_VENDORLIB_STEM"
19149 .IX Item "PERL_VENDORLIB_STEM"
19150 This define is \f(CW\*(C`PERL_VENDORLIB_EXP\*(C'\fR with any trailing version-specific component
19151 removed. The elements in \f(CW\*(C`inc_version_list\*(C'\fR (\f(CW\*(C`inc_version_list\*(C'\fR.U (part of metaconfig)) can
19152 be tacked onto this variable to generate a list of directories to search.
19153 .ie n .IP """PRIVLIB""" 4
19154 .el .IP \f(CWPRIVLIB\fR 4
19155 .IX Xref "PRIVLIB"
19156 .IX Item "PRIVLIB"
19157 This symbol contains the name of the private library for this package.
19158 The library is private in the sense that it needn't be in anyone's
19159 execution path, but it should be accessible by the world. The program
19160 should be prepared to do ~ expansion.
19161 .ie n .IP """PRIVLIB_EXP""" 4
19162 .el .IP \f(CWPRIVLIB_EXP\fR 4
19163 .IX Xref "PRIVLIB_EXP"
19164 .IX Item "PRIVLIB_EXP"
19165 This symbol contains the ~name expanded version of \f(CW\*(C`PRIVLIB\*(C'\fR, to be used
19166 in programs that are not prepared to deal with ~ expansion at run-time.
19167 .ie n .IP """SITEARCH""" 4
19168 .el .IP \f(CWSITEARCH\fR 4
19169 .IX Xref "SITEARCH"
19170 .IX Item "SITEARCH"
19171 This symbol contains the name of the private library for this package.
19172 The library is private in the sense that it needn't be in anyone's
19173 execution path, but it should be accessible by the world. The program
19174 should be prepared to do ~ expansion.
19175 The standard distribution will put nothing in this directory.
19176 After perl has been installed, users may install their own local
19177 architecture-dependent modules in this directory with
19178 .Sp
19179 .Vb 1
19180 \& MakeMaker Makefile.PL
19181 .Ve
19182 .Sp
19183 or equivalent. See \f(CW\*(C`INSTALL\*(C'\fR for details.
19184 .ie n .IP """SITEARCH_EXP""" 4
19185 .el .IP \f(CWSITEARCH_EXP\fR 4
19186 .IX Xref "SITEARCH_EXP"
19187 .IX Item "SITEARCH_EXP"
19188 This symbol contains the ~name expanded version of \f(CW\*(C`SITEARCH\*(C'\fR, to be used
19189 in programs that are not prepared to deal with ~ expansion at run-time.
19190 .ie n .IP """SITELIB""" 4
19191 .el .IP \f(CWSITELIB\fR 4
19192 .IX Xref "SITELIB"
19193 .IX Item "SITELIB"
19194 This symbol contains the name of the private library for this package.
19195 The library is private in the sense that it needn't be in anyone's
19196 execution path, but it should be accessible by the world. The program
19197 should be prepared to do ~ expansion.
19198 The standard distribution will put nothing in this directory.
19199 After perl has been installed, users may install their own local
19200 architecture-independent modules in this directory with
19201 .Sp
19202 .Vb 1
19203 \& MakeMaker Makefile.PL
19204 .Ve
19205 .Sp
19206 or equivalent. See \f(CW\*(C`INSTALL\*(C'\fR for details.
19207 .ie n .IP """SITELIB_EXP""" 4
19208 .el .IP \f(CWSITELIB_EXP\fR 4
19209 .IX Xref "SITELIB_EXP"
19210 .IX Item "SITELIB_EXP"
19211 This symbol contains the ~name expanded version of \f(CW\*(C`SITELIB\*(C'\fR, to be used
19212 in programs that are not prepared to deal with ~ expansion at run-time.
19213 .ie n .IP """SITELIB_STEM""" 4
19214 .el .IP \f(CWSITELIB_STEM\fR 4
19215 .IX Xref "SITELIB_STEM"
19216 .IX Item "SITELIB_STEM"
19217 This define is \f(CW\*(C`SITELIB_EXP\*(C'\fR with any trailing version-specific component
19218 removed. The elements in \f(CW\*(C`inc_version_list\*(C'\fR (\f(CW\*(C`inc_version_list\*(C'\fR.U (part of metaconfig)) can
19219 be tacked onto this variable to generate a list of directories to search.
19220 .ie n .IP """STARTPERL""" 4
19221 .el .IP \f(CWSTARTPERL\fR 4
19222 .IX Xref "STARTPERL"
19223 .IX Item "STARTPERL"
19224 This variable contains the string to put in front of a perl
19225 script to make sure (one hopes) that it runs with perl and not
19226 some shell.
19227 .ie n .IP """USE_64_BIT_ALL""" 4
19228 .el .IP \f(CWUSE_64_BIT_ALL\fR 4
19229 .IX Xref "USE_64_BIT_ALL"
19230 .IX Item "USE_64_BIT_ALL"
19231 This symbol, if defined, indicates that 64\-bit integers should
19232 be used when available. If not defined, the native integers
19233 will be used (be they 32 or 64 bits). The maximal possible
19234 64\-bitness is employed: LP64 or \f(CW\*(C`ILP64\*(C'\fR, meaning that you will
19235 be able to use more than 2 gigabytes of memory. This mode is
19236 even more binary incompatible than \f(CW\*(C`USE_64_BIT_INT\*(C'\fR. You may not
19237 be able to run the resulting executable in a 32\-bit \f(CW\*(C`CPU\*(C'\fR at all or
19238 you may need at least to reboot your OS to 64\-bit mode.
19239 .ie n .IP """USE_64_BIT_INT""" 4
19240 .el .IP \f(CWUSE_64_BIT_INT\fR 4
19241 .IX Xref "USE_64_BIT_INT"
19242 .IX Item "USE_64_BIT_INT"
19243 This symbol, if defined, indicates that 64\-bit integers should
19244 be used when available. If not defined, the native integers
19245 will be employed (be they 32 or 64 bits). The minimal possible
19246 64\-bitness is used, just enough to get 64\-bit integers into Perl.
19247 This may mean using for example "long longs", while your memory
19248 may still be limited to 2 gigabytes.
19249 .ie n .IP """USE_BSD_GETPGRP""" 4
19250 .el .IP \f(CWUSE_BSD_GETPGRP\fR 4
19251 .IX Xref "USE_BSD_GETPGRP"
19252 .IX Item "USE_BSD_GETPGRP"
19253 This symbol, if defined, indicates that getpgrp needs one
19254 arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none.
19255 .ie n .IP """USE_BSD_SETPGRP""" 4
19256 .el .IP \f(CWUSE_BSD_SETPGRP\fR 4
19257 .IX Xref "USE_BSD_SETPGRP"
19258 .IX Item "USE_BSD_SETPGRP"
19259 This symbol, if defined, indicates that setpgrp needs two
19260 arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none. See also \f(CW"HAS_SETPGID"\fR
19261 for a \f(CW\*(C`POSIX\*(C'\fR interface.
19262 .ie n .IP """USE_C_BACKTRACE""" 4
19263 .el .IP \f(CWUSE_C_BACKTRACE\fR 4
19264 .IX Xref "USE_C_BACKTRACE"
19265 .IX Item "USE_C_BACKTRACE"
19266 This symbol, if defined, indicates that Perl should
19267 be built with support for backtrace.
19268 .ie n .IP """USE_CPLUSPLUS""" 4
19269 .el .IP \f(CWUSE_CPLUSPLUS\fR 4
19270 .IX Xref "USE_CPLUSPLUS"
19271 .IX Item "USE_CPLUSPLUS"
19272 This symbol, if defined, indicates that a C++ compiler was
19273 used to compiled Perl and will be used to compile extensions.
19274 .ie n .IP """USE_CROSS_COMPILE""" 4
19275 .el .IP \f(CWUSE_CROSS_COMPILE\fR 4
19276 .IX Xref "USE_CROSS_COMPILE"
19277 .IX Item "USE_CROSS_COMPILE"
19278 This symbol, if defined, indicates that Perl is being cross-compiled.
19279 .ie n .IP """USE_DTRACE""" 4
19280 .el .IP \f(CWUSE_DTRACE\fR 4
19281 .IX Xref "USE_DTRACE"
19282 .IX Item "USE_DTRACE"
19283 This symbol, if defined, indicates that Perl should
19284 be built with support for DTrace.
19285 .ie n .IP """USE_DYNAMIC_LOADING""" 4
19286 .el .IP \f(CWUSE_DYNAMIC_LOADING\fR 4
19287 .IX Xref "USE_DYNAMIC_LOADING"
19288 .IX Item "USE_DYNAMIC_LOADING"
19289 This symbol, if defined, indicates that dynamic loading of
19290 some sort is available.
19291 .ie n .IP """USE_FAST_STDIO""" 4
19292 .el .IP \f(CWUSE_FAST_STDIO\fR 4
19293 .IX Xref "USE_FAST_STDIO"
19294 .IX Item "USE_FAST_STDIO"
19295 This symbol, if defined, indicates that Perl should
19296 be built to use 'fast stdio'.
19297 Defaults to define in Perls 5.8 and earlier, to undef later.
19298 .ie n .IP """USE_ITHREADS""" 4
19299 .el .IP \f(CWUSE_ITHREADS\fR 4
19300 .IX Xref "USE_ITHREADS"
19301 .IX Item "USE_ITHREADS"
19302 This symbol, if defined, indicates that Perl should be built to
19303 use the interpreter-based threading implementation.
19304 .ie n .IP """USE_KERN_PROC_PATHNAME""" 4
19305 .el .IP \f(CWUSE_KERN_PROC_PATHNAME\fR 4
19306 .IX Xref "USE_KERN_PROC_PATHNAME"
19307 .IX Item "USE_KERN_PROC_PATHNAME"
19308 This symbol, if defined, indicates that we can use sysctl with
19309 \&\f(CW\*(C`KERN_PROC_PATHNAME\*(C'\fR to get a full path for the executable, and hence
19310 convert $^X to an absolute path.
19311 .ie n .IP """USE_LARGE_FILES""" 4
19312 .el .IP \f(CWUSE_LARGE_FILES\fR 4
19313 .IX Xref "USE_LARGE_FILES"
19314 .IX Item "USE_LARGE_FILES"
19315 This symbol, if defined, indicates that large file support
19316 should be used when available.
19317 .ie n .IP """USE_LONG_DOUBLE""" 4
19318 .el .IP \f(CWUSE_LONG_DOUBLE\fR 4
19319 .IX Xref "USE_LONG_DOUBLE"
19320 .IX Item "USE_LONG_DOUBLE"
19321 This symbol, if defined, indicates that long doubles should
19322 be used when available.
19323 .ie n .IP """USE_MORE_BITS""" 4
19324 .el .IP \f(CWUSE_MORE_BITS\fR 4
19325 .IX Xref "USE_MORE_BITS"
19326 .IX Item "USE_MORE_BITS"
19327 This symbol, if defined, indicates that 64\-bit interfaces and
19328 long doubles should be used when available.
19329 .ie n .IP """USE_NSGETEXECUTABLEPATH""" 4
19330 .el .IP \f(CWUSE_NSGETEXECUTABLEPATH\fR 4
19331 .IX Xref "USE_NSGETEXECUTABLEPATH"
19332 .IX Item "USE_NSGETEXECUTABLEPATH"
19333 This symbol, if defined, indicates that we can use \f(CW\*(C`_NSGetExecutablePath\*(C'\fR
19334 and realpath to get a full path for the executable, and hence convert
19335 $^X to an absolute path.
19336 .ie n .IP """USE_PERLIO""" 4
19337 .el .IP \f(CWUSE_PERLIO\fR 4
19338 .IX Xref "USE_PERLIO"
19339 .IX Item "USE_PERLIO"
19340 This symbol, if defined, indicates that the PerlIO abstraction should
19341 be used throughout. If not defined, stdio should be
19342 used in a fully backward compatible manner.
19343 .ie n .IP """USE_QUADMATH""" 4
19344 .el .IP \f(CWUSE_QUADMATH\fR 4
19345 .IX Xref "USE_QUADMATH"
19346 .IX Item "USE_QUADMATH"
19347 This symbol, if defined, indicates that the quadmath library should
19348 be used when available.
19349 .ie n .IP """USE_REENTRANT_API""" 4
19350 .el .IP \f(CWUSE_REENTRANT_API\fR 4
19351 .IX Xref "USE_REENTRANT_API"
19352 .IX Item "USE_REENTRANT_API"
19353 This symbol, if defined, indicates that Perl should
19354 try to use the various \f(CW\*(C`_r\*(C'\fR versions of library functions.
19355 This is extremely experimental.
19356 .ie n .IP """USE_SEMCTL_SEMID_DS""" 4
19357 .el .IP \f(CWUSE_SEMCTL_SEMID_DS\fR 4
19358 .IX Xref "USE_SEMCTL_SEMID_DS"
19359 .IX Item "USE_SEMCTL_SEMID_DS"
19360 This symbol, if defined, indicates that \f(CW\*(C`struct semid_ds\*(C'\fR * is
19361 used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR.
19362 .ie n .IP """USE_SEMCTL_SEMUN""" 4
19363 .el .IP \f(CWUSE_SEMCTL_SEMUN\fR 4
19364 .IX Xref "USE_SEMCTL_SEMUN"
19365 .IX Item "USE_SEMCTL_SEMUN"
19366 This symbol, if defined, indicates that \f(CW\*(C`union semun\*(C'\fR is
19367 used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR.
19368 .ie n .IP """USE_SITECUSTOMIZE""" 4
19369 .el .IP \f(CWUSE_SITECUSTOMIZE\fR 4
19370 .IX Xref "USE_SITECUSTOMIZE"
19371 .IX Item "USE_SITECUSTOMIZE"
19372 This symbol, if defined, indicates that sitecustomize should
19373 be used.
19374 .ie n .IP """USE_SOCKS""" 4
19375 .el .IP \f(CWUSE_SOCKS\fR 4
19376 .IX Xref "USE_SOCKS"
19377 .IX Item "USE_SOCKS"
19378 This symbol, if defined, indicates that Perl should
19379 be built to use socks.
19380 .ie n .IP """USE_STAT_BLOCKS""" 4
19381 .el .IP \f(CWUSE_STAT_BLOCKS\fR 4
19382 .IX Xref "USE_STAT_BLOCKS"
19383 .IX Item "USE_STAT_BLOCKS"
19384 This symbol is defined if this system has a stat structure declaring
19385 \&\f(CW\*(C`st_blksize\*(C'\fR and \f(CW\*(C`st_blocks\*(C'\fR.
19386 .ie n .IP """USE_STDIO_BASE""" 4
19387 .el .IP \f(CWUSE_STDIO_BASE\fR 4
19388 .IX Xref "USE_STDIO_BASE"
19389 .IX Item "USE_STDIO_BASE"
19390 This symbol is defined if the \f(CW\*(C`_base\*(C'\fR field (or similar) of the
19391 stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer for
19392 a file handle. If this is defined, then the \f(CWFILE_base(fp)\fR macro
19393 will also be defined and should be used to access this field.
19394 Also, the \f(CWFILE_bufsiz(fp)\fR macro will be defined and should be used
19395 to determine the number of bytes in the buffer. \f(CW\*(C`USE_STDIO_BASE\*(C'\fR
19396 will never be defined unless \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is.
19397 .ie n .IP """USE_STDIO_PTR""" 4
19398 .el .IP \f(CWUSE_STDIO_PTR\fR 4
19399 .IX Xref "USE_STDIO_PTR"
19400 .IX Item "USE_STDIO_PTR"
19401 This symbol is defined if the \f(CW\*(C`_ptr\*(C'\fR and \f(CW\*(C`_cnt\*(C'\fR fields (or similar)
19402 of the stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer
19403 for a file handle. If this is defined, then the \f(CWFILE_ptr(fp)\fR
19404 and \f(CWFILE_cnt(fp)\fR macros will also be defined and should be used
19405 to access these fields.
19406 .ie n .IP """USE_STRICT_BY_DEFAULT""" 4
19407 .el .IP \f(CWUSE_STRICT_BY_DEFAULT\fR 4
19408 .IX Xref "USE_STRICT_BY_DEFAULT"
19409 .IX Item "USE_STRICT_BY_DEFAULT"
19410 This symbol, if defined, enables additional defaults.
19411 At this time it only enables implicit strict by default.
19412 .ie n .IP """USE_THREADS""" 4
19413 .el .IP \f(CWUSE_THREADS\fR 4
19414 .IX Xref "USE_THREADS"
19415 .IX Item "USE_THREADS"
19416 This symbol, if defined, indicates that Perl should
19417 be built to use threads. At present, it is a synonym for
19418 and \f(CW\*(C`USE_ITHREADS\*(C'\fR, but eventually the source ought to be
19419 changed to use this to mean \f(CW\*(C`_any_\*(C'\fR threading implementation.
19420 .SH "Sockets configuration values"
19421 .IX Header "Sockets configuration values"
19422 .ie n .IP """HAS_SOCKADDR_IN6""" 4
19423 .el .IP \f(CWHAS_SOCKADDR_IN6\fR 4
19424 .IX Xref "HAS_SOCKADDR_IN6"
19425 .IX Item "HAS_SOCKADDR_IN6"
19426 This symbol, if defined, indicates the availability of
19427 \&\f(CW\*(C`struct sockaddr_in6\*(C'\fR;
19428 .ie n .IP """HAS_SOCKADDR_SA_LEN""" 4
19429 .el .IP \f(CWHAS_SOCKADDR_SA_LEN\fR 4
19430 .IX Xref "HAS_SOCKADDR_SA_LEN"
19431 .IX Item "HAS_SOCKADDR_SA_LEN"
19432 This symbol, if defined, indicates that the \f(CW\*(C`struct sockaddr\*(C'\fR
19433 structure has a member called \f(CW\*(C`sa_len\*(C'\fR, indicating the length of
19434 the structure.
19435 .ie n .IP """HAS_SOCKADDR_STORAGE""" 4
19436 .el .IP \f(CWHAS_SOCKADDR_STORAGE\fR 4
19437 .IX Xref "HAS_SOCKADDR_STORAGE"
19438 .IX Item "HAS_SOCKADDR_STORAGE"
19439 This symbol, if defined, indicates the availability of
19440 \&\f(CW\*(C`struct sockaddr_storage\*(C'\fR;
19441 .ie n .IP """HAS_SOCKATMARK""" 4
19442 .el .IP \f(CWHAS_SOCKATMARK\fR 4
19443 .IX Xref "HAS_SOCKATMARK"
19444 .IX Item "HAS_SOCKATMARK"
19445 This symbol, if defined, indicates that the \f(CW\*(C`sockatmark\*(C'\fR routine is
19446 available to test whether a socket is at the out-of-band mark.
19447 .ie n .IP """HAS_SOCKET""" 4
19448 .el .IP \f(CWHAS_SOCKET\fR 4
19449 .IX Xref "HAS_SOCKET"
19450 .IX Item "HAS_SOCKET"
19451 This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CW\*(C`socket\*(C'\fR interface is
19452 supported.
19453 .ie n .IP """HAS_SOCKETPAIR""" 4
19454 .el .IP \f(CWHAS_SOCKETPAIR\fR 4
19455 .IX Xref "HAS_SOCKETPAIR"
19456 .IX Item "HAS_SOCKETPAIR"
19457 This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CWsocketpair()\fR call is
19458 supported.
19459 .ie n .IP """HAS_SOCKS5_INIT""" 4
19460 .el .IP \f(CWHAS_SOCKS5_INIT\fR 4
19461 .IX Xref "HAS_SOCKS5_INIT"
19462 .IX Item "HAS_SOCKS5_INIT"
19463 This symbol, if defined, indicates that the \f(CW\*(C`socks5_init\*(C'\fR routine is
19464 available to initialize \f(CW\*(C`SOCKS\*(C'\fR 5.
19465 .ie n .IP """I_SOCKS""" 4
19466 .el .IP \f(CWI_SOCKS\fR 4
19467 .IX Xref "I_SOCKS"
19468 .IX Item "I_SOCKS"
19469 This symbol, if defined, indicates that \fIsocks.h\fR exists and
19470 should be included.
19471 .RS 4
19472 .Sp
19473 .Vb 3
19474 \& #ifdef I_SOCKS
19475 \& #include <socks.h>
19476 \& #endif
19477 .Ve
19478 .RE
19479 .RS 4
19480 .RE
19481 .ie n .IP """I_SYS_SOCKIO""" 4
19482 .el .IP \f(CWI_SYS_SOCKIO\fR 4
19483 .IX Xref "I_SYS_SOCKIO"
19484 .IX Item "I_SYS_SOCKIO"
19485 This symbol, if defined, indicates the \fIsys/sockio.h\fR should be included
19486 to get socket ioctl options, like \f(CW\*(C`SIOCATMARK\*(C'\fR.
19487 .RS 4
19488 .Sp
19489 .Vb 3
19490 \& #ifdef I_SYS_SOCKIO
19491 \& #include <sys_sockio.h>
19492 \& #endif
19493 .Ve
19494 .RE
19495 .RS 4
19496 .RE
19497 .SH "Source Filters"
19498 .IX Header "Source Filters"
19499 .ie n .IP """apply_builtin_cv_attributes""" 4
19500 .el .IP \f(CWapply_builtin_cv_attributes\fR 4
19501 .IX Xref "apply_builtin_cv_attributes"
19502 .IX Item "apply_builtin_cv_attributes"
19503 Given an OP_LIST containing attribute definitions, filter it for known builtin
19504 attributes to apply to the cv, returning a possibly-smaller list containing
19505 just the remaining ones.
19506 .RS 4
19507 .Sp
19508 .Vb 1
19509 \& OP * apply_builtin_cv_attributes(CV *cv, OP *attrlist)
19510 .Ve
19511 .RE
19512 .RS 4
19513 .RE
19514 .ie n .IP """filter_add""" 4
19515 .el .IP \f(CWfilter_add\fR 4
19516 .IX Item "filter_add"
19517 Described in perlfilter.
19518 .RS 4
19519 .Sp
19520 .Vb 1
19521 \& SV * filter_add(filter_t funcp, SV *datasv)
19522 .Ve
19523 .RE
19524 .RS 4
19525 .RE
19526 .ie n .IP """filter_del""" 4
19527 .el .IP \f(CWfilter_del\fR 4
19528 .IX Xref "filter_del"
19529 .IX Item "filter_del"
19530 Delete most recently added instance of the filter function argument
19531 .RS 4
19532 .Sp
19533 .Vb 1
19534 \& void filter_del(filter_t funcp)
19535 .Ve
19536 .RE
19537 .RS 4
19538 .RE
19539 .ie n .IP """filter_read""" 4
19540 .el .IP \f(CWfilter_read\fR 4
19541 .IX Item "filter_read"
19542 Described in perlfilter.
19543 .RS 4
19544 .Sp
19545 .Vb 1
19546 \& I32 filter_read(int idx, SV *buf_sv, int maxlen)
19547 .Ve
19548 .RE
19549 .RS 4
19550 .RE
19551 .ie n .IP """scan_vstring""" 4
19552 .el .IP \f(CWscan_vstring\fR 4
19553 .IX Xref "scan_vstring"
19554 .IX Item "scan_vstring"
19555 Returns a pointer to the next character after the parsed
19556 vstring, as well as updating the passed in sv.
19557 .Sp
19558 Function must be called like
19559 .Sp
19560 .Vb 2
19561 \& sv = sv_2mortal(newSV(5));
19562 \& s = scan_vstring(s,e,sv);
19563 .Ve
19564 .Sp
19565 where s and e are the start and end of the string.
19566 The sv should already be large enough to store the vstring
19567 passed in, for performance reasons.
19568 .Sp
19569 This function may croak if fatal warnings are enabled in the
19570 calling scope, hence the sv_2mortal in the example (to prevent
19571 a leak). Make sure to do SvREFCNT_inc afterwards if you use
19572 sv_2mortal.
19573 .RS 4
19574 .Sp
19575 .Vb 1
19576 \& char * scan_vstring(const char *s, const char * const e, SV *sv)
19577 .Ve
19578 .RE
19579 .RS 4
19580 .RE
19581 .ie n .IP """start_subparse""" 4
19582 .el .IP \f(CWstart_subparse\fR 4
19583 .IX Xref "start_subparse"
19584 .IX Item "start_subparse"
19585 Set things up for parsing a subroutine.
19586 .Sp
19587 If \f(CW\*(C`is_format\*(C'\fR is non-zero, the input is to be considered a format sub
19588 (a specialised sub used to implement perl's \f(CW\*(C`format\*(C'\fR feature); else a
19589 normal \f(CW\*(C`sub\*(C'\fR.
19590 .Sp
19591 \&\f(CW\*(C`flags\*(C'\fR are added to the flags for \f(CW\*(C`PL_compcv\*(C'\fR. \f(CW\*(C`flags\*(C'\fR may include the
19592 \&\f(CW\*(C`CVf_IsMETHOD\*(C'\fR bit, which causes the new subroutine to be a method.
19593 .Sp
19594 This returns the value of \f(CW\*(C`PL_savestack_ix\*(C'\fR that was in effect upon entry to
19595 the function;
19596 .RS 4
19597 .Sp
19598 .Vb 1
19599 \& I32 start_subparse(I32 is_format, U32 flags)
19600 .Ve
19601 .RE
19602 .RS 4
19603 .RE
19604 .SH "Stack Manipulation Macros"
19605 .IX Header "Stack Manipulation Macros"
19606 .ie n .IP """dMARK""" 4
19607 .el .IP \f(CWdMARK\fR 4
19608 .IX Xref "dMARK"
19609 .IX Item "dMARK"
19610 Declare a stack marker variable, \f(CW\*(C`mark\*(C'\fR, for the XSUB. See \f(CW"MARK"\fR and
19611 \&\f(CW"dORIGMARK"\fR.
19612 .RS 4
19613 .Sp
19614 .Vb 1
19615 \& dMARK;
19616 .Ve
19617 .RE
19618 .RS 4
19619 .RE
19620 .ie n .IP """dORIGMARK""" 4
19621 .el .IP \f(CWdORIGMARK\fR 4
19622 .IX Xref "dORIGMARK"
19623 .IX Item "dORIGMARK"
19624 Saves the original stack mark for the XSUB. See \f(CW"ORIGMARK"\fR.
19625 .RS 4
19626 .Sp
19627 .Vb 1
19628 \& dORIGMARK;
19629 .Ve
19630 .RE
19631 .RS 4
19632 .RE
19633 .ie n .IP """dSP""" 4
19634 .el .IP \f(CWdSP\fR 4
19635 .IX Xref "dSP"
19636 .IX Item "dSP"
19637 Declares a local copy of perl's stack pointer for the XSUB, available via
19638 the \f(CW\*(C`SP\*(C'\fR macro. See \f(CW"SP"\fR.
19639 .RS 4
19640 .Sp
19641 .Vb 1
19642 \& dSP;
19643 .Ve
19644 .RE
19645 .RS 4
19646 .RE
19647 .ie n .IP """dTARGET""" 4
19648 .el .IP \f(CWdTARGET\fR 4
19649 .IX Xref "dTARGET"
19650 .IX Item "dTARGET"
19651 Declare that this function uses \f(CW\*(C`TARG\*(C'\fR, and initializes it
19652 .RS 4
19653 .Sp
19654 .Vb 1
19655 \& dTARGET;
19656 .Ve
19657 .RE
19658 .RS 4
19659 .RE
19660 .ie n .IP """EXTEND""" 4
19661 .el .IP \f(CWEXTEND\fR 4
19662 .IX Xref "EXTEND"
19663 .IX Item "EXTEND"
19664 Used to extend the argument stack for an XSUB's return values. Once
19665 used, guarantees that there is room for at least \f(CW\*(C`nitems\*(C'\fR to be pushed
19666 onto the stack.
19667 .RS 4
19668 .Sp
19669 .Vb 1
19670 \& void EXTEND(SP, SSize_t nitems)
19671 .Ve
19672 .RE
19673 .RS 4
19674 .RE
19675 .ie n .IP """MARK""" 4
19676 .el .IP \f(CWMARK\fR 4
19677 .IX Xref "MARK"
19678 .IX Item "MARK"
19679 Stack marker variable for the XSUB. See \f(CW"dMARK"\fR.
19680 .ie n .IP """mPUSHi""" 4
19681 .el .IP \f(CWmPUSHi\fR 4
19682 .IX Xref "mPUSHi"
19683 .IX Item "mPUSHi"
19684 Push an integer onto the stack. The stack must have room for this element.
19685 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHi"\fR, \f(CW"mXPUSHi"\fR and \f(CW"XPUSHi"\fR.
19686 .RS 4
19687 .Sp
19688 .Vb 1
19689 \& void mPUSHi(IV iv)
19690 .Ve
19691 .RE
19692 .RS 4
19693 .RE
19694 .ie n .IP """mPUSHn""" 4
19695 .el .IP \f(CWmPUSHn\fR 4
19696 .IX Xref "mPUSHn"
19697 .IX Item "mPUSHn"
19698 Push a double onto the stack. The stack must have room for this element.
19699 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHn"\fR, \f(CW"mXPUSHn"\fR and \f(CW"XPUSHn"\fR.
19700 .RS 4
19701 .Sp
19702 .Vb 1
19703 \& void mPUSHn(NV nv)
19704 .Ve
19705 .RE
19706 .RS 4
19707 .RE
19708 .ie n .IP """mPUSHp""" 4
19709 .el .IP \f(CWmPUSHp\fR 4
19710 .IX Xref "mPUSHp"
19711 .IX Item "mPUSHp"
19712 Push a string onto the stack. The stack must have room for this element.
19713 The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Does not use \f(CW\*(C`TARG\*(C'\fR.
19714 See also \f(CW"PUSHp"\fR, \f(CW"mXPUSHp"\fR and \f(CW"XPUSHp"\fR.
19715 .RS 4
19716 .Sp
19717 .Vb 1
19718 \& void mPUSHp(char* str, STRLEN len)
19719 .Ve
19720 .RE
19721 .RS 4
19722 .RE
19723 .ie n .IP """mPUSHpvs""" 4
19724 .el .IP \f(CWmPUSHpvs\fR 4
19725 .IX Xref "mPUSHpvs"
19726 .IX Item "mPUSHpvs"
19727 A variation on \f(CW\*(C`mPUSHp\*(C'\fR that takes a literal string and calculates its size
19728 directly.
19729 .RS 4
19730 .Sp
19731 .Vb 1
19732 \& void mPUSHpvs("literal string")
19733 .Ve
19734 .RE
19735 .RS 4
19736 .RE
19737 .ie n .IP """mPUSHs""" 4
19738 .el .IP \f(CWmPUSHs\fR 4
19739 .IX Xref "mPUSHs"
19740 .IX Item "mPUSHs"
19741 Push an SV onto the stack and mortalizes the SV. The stack must have room
19742 for this element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHs"\fR and
19743 \&\f(CW"mXPUSHs"\fR.
19744 .RS 4
19745 .Sp
19746 .Vb 1
19747 \& void mPUSHs(SV* sv)
19748 .Ve
19749 .RE
19750 .RS 4
19751 .RE
19752 .ie n .IP """mPUSHu""" 4
19753 .el .IP \f(CWmPUSHu\fR 4
19754 .IX Xref "mPUSHu"
19755 .IX Item "mPUSHu"
19756 Push an unsigned integer onto the stack. The stack must have room for this
19757 element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHu"\fR, \f(CW"mXPUSHu"\fR and
19758 \&\f(CW"XPUSHu"\fR.
19759 .RS 4
19760 .Sp
19761 .Vb 1
19762 \& void mPUSHu(UV uv)
19763 .Ve
19764 .RE
19765 .RS 4
19766 .RE
19767 .ie n .IP """mXPUSHi""" 4
19768 .el .IP \f(CWmXPUSHi\fR 4
19769 .IX Xref "mXPUSHi"
19770 .IX Item "mXPUSHi"
19771 Push an integer onto the stack, extending the stack if necessary.
19772 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHi"\fR, \f(CW"mPUSHi"\fR and \f(CW"PUSHi"\fR.
19773 .RS 4
19774 .Sp
19775 .Vb 1
19776 \& void mXPUSHi(IV iv)
19777 .Ve
19778 .RE
19779 .RS 4
19780 .RE
19781 .ie n .IP """mXPUSHn""" 4
19782 .el .IP \f(CWmXPUSHn\fR 4
19783 .IX Xref "mXPUSHn"
19784 .IX Item "mXPUSHn"
19785 Push a double onto the stack, extending the stack if necessary.
19786 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHn"\fR, \f(CW"mPUSHn"\fR and \f(CW"PUSHn"\fR.
19787 .RS 4
19788 .Sp
19789 .Vb 1
19790 \& void mXPUSHn(NV nv)
19791 .Ve
19792 .RE
19793 .RS 4
19794 .RE
19795 .ie n .IP """mXPUSHp""" 4
19796 .el .IP \f(CWmXPUSHp\fR 4
19797 .IX Xref "mXPUSHp"
19798 .IX Item "mXPUSHp"
19799 Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR
19800 indicates the length of the string. Does not use \f(CW\*(C`TARG\*(C'\fR. See also
19801 \&\f(CW"XPUSHp"\fR, \f(CW\*(C`mPUSHp\*(C'\fR and \f(CW\*(C`PUSHp\*(C'\fR.
19802 .RS 4
19803 .Sp
19804 .Vb 1
19805 \& void mXPUSHp(char* str, STRLEN len)
19806 .Ve
19807 .RE
19808 .RS 4
19809 .RE
19810 .ie n .IP """mXPUSHpvs""" 4
19811 .el .IP \f(CWmXPUSHpvs\fR 4
19812 .IX Xref "mXPUSHpvs"
19813 .IX Item "mXPUSHpvs"
19814 A variation on \f(CW\*(C`mXPUSHp\*(C'\fR that takes a literal string and calculates its size
19815 directly.
19816 .RS 4
19817 .Sp
19818 .Vb 1
19819 \& void mXPUSHpvs("literal string")
19820 .Ve
19821 .RE
19822 .RS 4
19823 .RE
19824 .ie n .IP """mXPUSHs""" 4
19825 .el .IP \f(CWmXPUSHs\fR 4
19826 .IX Xref "mXPUSHs"
19827 .IX Item "mXPUSHs"
19828 Push an SV onto the stack, extending the stack if necessary and mortalizes
19829 the SV. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHs"\fR and \f(CW"mPUSHs"\fR.
19830 .RS 4
19831 .Sp
19832 .Vb 1
19833 \& void mXPUSHs(SV* sv)
19834 .Ve
19835 .RE
19836 .RS 4
19837 .RE
19838 .ie n .IP """mXPUSHu""" 4
19839 .el .IP \f(CWmXPUSHu\fR 4
19840 .IX Xref "mXPUSHu"
19841 .IX Item "mXPUSHu"
19842 Push an unsigned integer onto the stack, extending the stack if necessary.
19843 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHu"\fR, \f(CW"mPUSHu"\fR and \f(CW"PUSHu"\fR.
19844 .RS 4
19845 .Sp
19846 .Vb 1
19847 \& void mXPUSHu(UV uv)
19848 .Ve
19849 .RE
19850 .RS 4
19851 .RE
19852 .ie n .IP """newXSproto""" 4
19853 .el .IP \f(CWnewXSproto\fR 4
19854 .IX Xref "newXSproto"
19855 .IX Item "newXSproto"
19856 Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. Adds Perl prototypes to
19857 the subs.
19858 .ie n .IP """ORIGMARK""" 4
19859 .el .IP \f(CWORIGMARK\fR 4
19860 .IX Xref "ORIGMARK"
19861 .IX Item "ORIGMARK"
19862 The original stack mark for the XSUB. See \f(CW"dORIGMARK"\fR.
19863 .ie n .IP """PL_markstack""" 4
19864 .el .IP \f(CWPL_markstack\fR 4
19865 .IX Item "PL_markstack"
19866 Described in perlguts.
19867 .ie n .IP """PL_markstack_ptr""" 4
19868 .el .IP \f(CWPL_markstack_ptr\fR 4
19869 .IX Item "PL_markstack_ptr"
19870 Described in perlguts.
19871 .ie n .IP """PL_savestack""" 4
19872 .el .IP \f(CWPL_savestack\fR 4
19873 .IX Item "PL_savestack"
19874 Described in perlguts.
19875 .ie n .IP """PL_savestack_ix""" 4
19876 .el .IP \f(CWPL_savestack_ix\fR 4
19877 .IX Item "PL_savestack_ix"
19878 Described in perlguts.
19879 .ie n .IP """PL_scopestack""" 4
19880 .el .IP \f(CWPL_scopestack\fR 4
19881 .IX Item "PL_scopestack"
19882 Described in perlguts.
19883 .ie n .IP """PL_scopestack_ix""" 4
19884 .el .IP \f(CWPL_scopestack_ix\fR 4
19885 .IX Item "PL_scopestack_ix"
19886 Described in perlguts.
19887 .ie n .IP """PL_scopestack_name""" 4
19888 .el .IP \f(CWPL_scopestack_name\fR 4
19889 .IX Item "PL_scopestack_name"
19890 Described in perlguts.
19891 .ie n .IP """PL_stack_base""" 4
19892 .el .IP \f(CWPL_stack_base\fR 4
19893 .IX Item "PL_stack_base"
19894 Described in perlguts.
19895 .ie n .IP """PL_stack_sp""" 4
19896 .el .IP \f(CWPL_stack_sp\fR 4
19897 .IX Item "PL_stack_sp"
19898 Described in perlguts.
19899 .ie n .IP """PL_tmps_floor""" 4
19900 .el .IP \f(CWPL_tmps_floor\fR 4
19901 .IX Item "PL_tmps_floor"
19902 Described in perlguts.
19903 .ie n .IP """PL_tmps_ix""" 4
19904 .el .IP \f(CWPL_tmps_ix\fR 4
19905 .IX Item "PL_tmps_ix"
19906 Described in perlguts.
19907 .ie n .IP """PL_tmps_stack""" 4
19908 .el .IP \f(CWPL_tmps_stack\fR 4
19909 .IX Item "PL_tmps_stack"
19910 Described in perlguts.
19911 .ie n .IP """POPi""" 4
19912 .el .IP \f(CWPOPi\fR 4
19913 .IX Xref "POPi"
19914 .IX Item "POPi"
19915 Pops an integer off the stack.
19916 .RS 4
19917 .Sp
19918 .Vb 1
19919 \& IV POPi
19920 .Ve
19921 .RE
19922 .RS 4
19923 .RE
19924 .ie n .IP """POPl""" 4
19925 .el .IP \f(CWPOPl\fR 4
19926 .IX Xref "POPl"
19927 .IX Item "POPl"
19928 Pops a long off the stack.
19929 .RS 4
19930 .Sp
19931 .Vb 1
19932 \& long POPl
19933 .Ve
19934 .RE
19935 .RS 4
19936 .RE
19937 .ie n .IP """POPn""" 4
19938 .el .IP \f(CWPOPn\fR 4
19939 .IX Xref "POPn"
19940 .IX Item "POPn"
19941 Pops a double off the stack.
19942 .RS 4
19943 .Sp
19944 .Vb 1
19945 \& NV POPn
19946 .Ve
19947 .RE
19948 .RS 4
19949 .RE
19950 .ie n .IP """POPp""" 4
19951 .el .IP \f(CWPOPp\fR 4
19952 .IX Xref "POPp"
19953 .IX Item "POPp"
19954 Pops a string off the stack.
19955 .RS 4
19956 .Sp
19957 .Vb 1
19958 \& char* POPp
19959 .Ve
19960 .RE
19961 .RS 4
19962 .RE
19963 .ie n .IP """POPpbytex""" 4
19964 .el .IP \f(CWPOPpbytex\fR 4
19965 .IX Xref "POPpbytex"
19966 .IX Item "POPpbytex"
19967 Pops a string off the stack which must consist of bytes i.e. characters < 256.
19968 .RS 4
19969 .Sp
19970 .Vb 1
19971 \& char* POPpbytex
19972 .Ve
19973 .RE
19974 .RS 4
19975 .RE
19976 .ie n .IP """POPpx""" 4
19977 .el .IP \f(CWPOPpx\fR 4
19978 .IX Xref "POPpx"
19979 .IX Item "POPpx"
19980 Pops a string off the stack. Identical to POPp. There are two names for
19981 historical reasons.
19982 .RS 4
19983 .Sp
19984 .Vb 1
19985 \& char* POPpx
19986 .Ve
19987 .RE
19988 .RS 4
19989 .RE
19990 .ie n .IP """POPs""" 4
19991 .el .IP \f(CWPOPs\fR 4
19992 .IX Xref "POPs"
19993 .IX Item "POPs"
19994 Pops an SV off the stack.
19995 .RS 4
19996 .Sp
19997 .Vb 1
19998 \& SV* POPs
19999 .Ve
20000 .RE
20001 .RS 4
20002 .RE
20003 .ie n .IP """POPu""" 4
20004 .el .IP \f(CWPOPu\fR 4
20005 .IX Xref "POPu"
20006 .IX Item "POPu"
20007 Pops an unsigned integer off the stack.
20008 .RS 4
20009 .Sp
20010 .Vb 1
20011 \& UV POPu
20012 .Ve
20013 .RE
20014 .RS 4
20015 .RE
20016 .ie n .IP """POPul""" 4
20017 .el .IP \f(CWPOPul\fR 4
20018 .IX Xref "POPul"
20019 .IX Item "POPul"
20020 Pops an unsigned long off the stack.
20021 .RS 4
20022 .Sp
20023 .Vb 1
20024 \& long POPul
20025 .Ve
20026 .RE
20027 .RS 4
20028 .RE
20029 .ie n .IP """PUSHi""" 4
20030 .el .IP \f(CWPUSHi\fR 4
20031 .IX Xref "PUSHi"
20032 .IX Item "PUSHi"
20033 Push an integer onto the stack. The stack must have room for this element.
20034 Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
20035 called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
20036 return lists from XSUB's \- see \f(CW"mPUSHi"\fR instead. See also \f(CW"XPUSHi"\fR
20037 and \f(CW"mXPUSHi"\fR.
20038 .RS 4
20039 .Sp
20040 .Vb 1
20041 \& void PUSHi(IV iv)
20042 .Ve
20043 .RE
20044 .RS 4
20045 .RE
20046 .ie n .IP """PUSHMARK""" 4
20047 .el .IP \f(CWPUSHMARK\fR 4
20048 .IX Xref "PUSHMARK"
20049 .IX Item "PUSHMARK"
20050 Opening bracket for arguments on a callback. See \f(CW"PUTBACK"\fR and
20051 perlcall.
20052 .RS 4
20053 .Sp
20054 .Vb 1
20055 \& void PUSHMARK(SP)
20056 .Ve
20057 .RE
20058 .RS 4
20059 .RE
20060 .ie n .IP """PUSHmortal""" 4
20061 .el .IP \f(CWPUSHmortal\fR 4
20062 .IX Xref "PUSHmortal"
20063 .IX Item "PUSHmortal"
20064 Push a new mortal SV onto the stack. The stack must have room for this
20065 element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHs"\fR, \f(CW"XPUSHmortal"\fR and
20066 \&\f(CW"XPUSHs"\fR.
20067 .RS 4
20068 .Sp
20069 .Vb 1
20070 \& void PUSHmortal
20071 .Ve
20072 .RE
20073 .RS 4
20074 .RE
20075 .ie n .IP """PUSHn""" 4
20076 .el .IP \f(CWPUSHn\fR 4
20077 .IX Xref "PUSHn"
20078 .IX Item "PUSHn"
20079 Push a double onto the stack. The stack must have room for this element.
20080 Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
20081 called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
20082 return lists from XSUB's \- see \f(CW"mPUSHn"\fR instead. See also \f(CW"XPUSHn"\fR
20083 and \f(CW"mXPUSHn"\fR.
20084 .RS 4
20085 .Sp
20086 .Vb 1
20087 \& void PUSHn(NV nv)
20088 .Ve
20089 .RE
20090 .RS 4
20091 .RE
20092 .ie n .IP """PUSHp""" 4
20093 .el .IP \f(CWPUSHp\fR 4
20094 .IX Xref "PUSHp"
20095 .IX Item "PUSHp"
20096 Push a string onto the stack. The stack must have room for this element.
20097 The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Handles 'set' magic. Uses
20098 \&\f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it. Do not
20099 call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB's \- see
20100 \&\f(CW"mPUSHp"\fR instead. See also \f(CW"XPUSHp"\fR and \f(CW"mXPUSHp"\fR.
20101 .RS 4
20102 .Sp
20103 .Vb 1
20104 \& void PUSHp(char* str, STRLEN len)
20105 .Ve
20106 .RE
20107 .RS 4
20108 .RE
20109 .ie n .IP """PUSHpvs""" 4
20110 .el .IP \f(CWPUSHpvs\fR 4
20111 .IX Xref "PUSHpvs"
20112 .IX Item "PUSHpvs"
20113 A variation on \f(CW\*(C`PUSHp\*(C'\fR that takes a literal string and calculates its size
20114 directly.
20115 .RS 4
20116 .Sp
20117 .Vb 1
20118 \& void PUSHpvs("literal string")
20119 .Ve
20120 .RE
20121 .RS 4
20122 .RE
20123 .ie n .IP """PUSHs""" 4
20124 .el .IP \f(CWPUSHs\fR 4
20125 .IX Xref "PUSHs"
20126 .IX Item "PUSHs"
20127 Push an SV onto the stack. The stack must have room for this element.
20128 Does not handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also
20129 \&\f(CW"PUSHmortal"\fR, \f(CW"XPUSHs"\fR, and \f(CW"XPUSHmortal"\fR.
20130 .RS 4
20131 .Sp
20132 .Vb 1
20133 \& void PUSHs(SV* sv)
20134 .Ve
20135 .RE
20136 .RS 4
20137 .RE
20138 .ie n .IP """PUSHu""" 4
20139 .el .IP \f(CWPUSHu\fR 4
20140 .IX Xref "PUSHu"
20141 .IX Item "PUSHu"
20142 Push an unsigned integer onto the stack. The stack must have room for this
20143 element. Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR
20144 should be called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented
20145 macros to return lists from XSUB's \- see \f(CW"mPUSHu"\fR instead. See also
20146 \&\f(CW"XPUSHu"\fR and \f(CW"mXPUSHu"\fR.
20147 .RS 4
20148 .Sp
20149 .Vb 1
20150 \& void PUSHu(UV uv)
20151 .Ve
20152 .RE
20153 .RS 4
20154 .RE
20155 .ie n .IP """PUTBACK""" 4
20156 .el .IP \f(CWPUTBACK\fR 4
20157 .IX Xref "PUTBACK"
20158 .IX Item "PUTBACK"
20159 Closing bracket for XSUB arguments. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR.
20160 See \f(CW"PUSHMARK"\fR and perlcall for other uses.
20161 .RS 4
20162 .Sp
20163 .Vb 1
20164 \& PUTBACK;
20165 .Ve
20166 .RE
20167 .RS 4
20168 .RE
20169 .ie n .IP """SAVEt_INT""" 4
20170 .el .IP \f(CWSAVEt_INT\fR 4
20171 .IX Item "SAVEt_INT"
20172 Described in perlguts.
20173 .ie n .IP """SP""" 4
20174 .el .IP \f(CWSP\fR 4
20175 .IX Xref "SP"
20176 .IX Item "SP"
20177 Stack pointer. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. See \f(CW"dSP"\fR and
20178 \&\f(CW\*(C`SPAGAIN\*(C'\fR.
20179 .ie n .IP """SPAGAIN""" 4
20180 .el .IP \f(CWSPAGAIN\fR 4
20181 .IX Xref "SPAGAIN"
20182 .IX Item "SPAGAIN"
20183 Refetch the stack pointer. Used after a callback. See perlcall.
20184 .RS 4
20185 .Sp
20186 .Vb 1
20187 \& SPAGAIN;
20188 .Ve
20189 .RE
20190 .RS 4
20191 .RE
20192 .ie n .IP """SSNEW""" 4
20193 .el .IP \f(CWSSNEW\fR 4
20194 .IX Item "SSNEW"
20195 .PD 0
20196 .ie n .IP """SSNEWa""" 4
20197 .el .IP \f(CWSSNEWa\fR 4
20198 .IX Item "SSNEWa"
20199 .ie n .IP """SSNEWat""" 4
20200 .el .IP \f(CWSSNEWat\fR 4
20201 .IX Item "SSNEWat"
20202 .ie n .IP """SSNEWt""" 4
20203 .el .IP \f(CWSSNEWt\fR 4
20204 .IX Xref "SSNEW SSNEWa SSNEWat SSNEWt"
20205 .IX Item "SSNEWt"
20206 .PD
20207 These each temporarily allocate data on the savestack, returning an SSize_t
20208 index into the savestack, because a pointer would get broken if the savestack
20209 is moved on reallocation. Use "\f(CW\*(C`SSPTR\*(C'\fR" to convert the returned index into
20210 a pointer.
20211 .Sp
20212 The forms differ in that plain \f(CW\*(C`SSNEW\*(C'\fR allocates \f(CW\*(C`size\*(C'\fR bytes;
20213 \&\f(CW\*(C`SSNEWt\*(C'\fR and \f(CW\*(C`SSNEWat\*(C'\fR allocate \f(CW\*(C`size\*(C'\fR objects, each of which is type
20214 \&\f(CW\*(C`type\*(C'\fR;
20215 and <SSNEWa> and \f(CW\*(C`SSNEWat\*(C'\fR make sure to align the new data to an \f(CW\*(C`align\*(C'\fR
20216 boundary. The most useful value for the alignment is likely to be
20217 "\f(CW\*(C`MEM_ALIGNBYTES\*(C'\fR". The alignment will be preserved through savestack
20218 reallocation \fBonly\fR if realloc returns data aligned to a size divisible by
20219 "align"!
20220 .RS 4
20221 .Sp
20222 .Vb 4
20223 \& SSize_t SSNEW (Size_t size)
20224 \& SSize_t SSNEWa (Size_t size, Size_t align)
20225 \& SSize_t SSNEWat(Size_t size, type, Size_t align)
20226 \& SSize_t SSNEWt (Size_t size, type)
20227 .Ve
20228 .RE
20229 .RS 4
20230 .RE
20231 .ie n .IP """SSPTR""" 4
20232 .el .IP \f(CWSSPTR\fR 4
20233 .IX Item "SSPTR"
20234 .PD 0
20235 .ie n .IP """SSPTRt""" 4
20236 .el .IP \f(CWSSPTRt\fR 4
20237 .IX Xref "SSPTR SSPTRt"
20238 .IX Item "SSPTRt"
20239 .PD
20240 These convert the \f(CW\*(C`index\*(C'\fR returned by L/<\f(CW\*(C`SSNEW\*(C'\fR> and kin into actual pointers.
20241 .Sp
20242 The difference is that \f(CW\*(C`SSPTR\*(C'\fR casts the result to \f(CW\*(C`type\*(C'\fR, and \f(CW\*(C`SSPTRt\*(C'\fR
20243 casts it to a pointer of that \f(CW\*(C`type\*(C'\fR.
20244 .RS 4
20245 .Sp
20246 .Vb 2
20247 \& type SSPTR (SSize_t index, type)
20248 \& type * SSPTRt(SSize_t index, type)
20249 .Ve
20250 .RE
20251 .RS 4
20252 .RE
20253 .ie n .IP """TARG""" 4
20254 .el .IP \f(CWTARG\fR 4
20255 .IX Xref "TARG"
20256 .IX Item "TARG"
20257 \&\f(CW\*(C`TARG\*(C'\fR is short for "target". It is an entry in the pad that an OPs
20258 \&\f(CW\*(C`op_targ\*(C'\fR refers to. It is scratchpad space, often used as a return
20259 value for the OP, but some use it for other purposes.
20260 .RS 4
20261 .Sp
20262 .Vb 1
20263 \& TARG;
20264 .Ve
20265 .RE
20266 .RS 4
20267 .RE
20268 .ie n .IP """TOPs""" 4
20269 .el .IP \f(CWTOPs\fR 4
20270 .IX Item "TOPs"
20271 Described in perlguts.
20272 .ie n .IP """XPUSHi""" 4
20273 .el .IP \f(CWXPUSHi\fR 4
20274 .IX Xref "XPUSHi"
20275 .IX Item "XPUSHi"
20276 Push an integer onto the stack, extending the stack if necessary. Handles
20277 \&'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to
20278 declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists
20279 from XSUB's \- see \f(CW"mXPUSHi"\fR instead. See also \f(CW"PUSHi"\fR and
20280 \&\f(CW"mPUSHi"\fR.
20281 .RS 4
20282 .Sp
20283 .Vb 1
20284 \& void XPUSHi(IV iv)
20285 .Ve
20286 .RE
20287 .RS 4
20288 .RE
20289 .ie n .IP """XPUSHmortal""" 4
20290 .el .IP \f(CWXPUSHmortal\fR 4
20291 .IX Xref "XPUSHmortal"
20292 .IX Item "XPUSHmortal"
20293 Push a new mortal SV onto the stack, extending the stack if necessary.
20294 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHs"\fR, \f(CW"PUSHmortal"\fR and
20295 \&\f(CW"PUSHs"\fR.
20296 .RS 4
20297 .Sp
20298 .Vb 1
20299 \& void XPUSHmortal
20300 .Ve
20301 .RE
20302 .RS 4
20303 .RE
20304 .ie n .IP """XPUSHn""" 4
20305 .el .IP \f(CWXPUSHn\fR 4
20306 .IX Xref "XPUSHn"
20307 .IX Item "XPUSHn"
20308 Push a double onto the stack, extending the stack if necessary. Handles
20309 \&'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to
20310 declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists
20311 from XSUB's \- see \f(CW"mXPUSHn"\fR instead. See also \f(CW"PUSHn"\fR and
20312 \&\f(CW"mPUSHn"\fR.
20313 .RS 4
20314 .Sp
20315 .Vb 1
20316 \& void XPUSHn(NV nv)
20317 .Ve
20318 .RE
20319 .RS 4
20320 .RE
20321 .ie n .IP """XPUSHp""" 4
20322 .el .IP \f(CWXPUSHp\fR 4
20323 .IX Xref "XPUSHp"
20324 .IX Item "XPUSHp"
20325 Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR
20326 indicates the length of the string. Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so
20327 \&\f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it. Do not call
20328 multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB's \- see
20329 \&\f(CW"mXPUSHp"\fR instead. See also \f(CW"PUSHp"\fR and \f(CW"mPUSHp"\fR.
20330 .RS 4
20331 .Sp
20332 .Vb 1
20333 \& void XPUSHp(char* str, STRLEN len)
20334 .Ve
20335 .RE
20336 .RS 4
20337 .RE
20338 .ie n .IP """XPUSHpvs""" 4
20339 .el .IP \f(CWXPUSHpvs\fR 4
20340 .IX Xref "XPUSHpvs"
20341 .IX Item "XPUSHpvs"
20342 A variation on \f(CW\*(C`XPUSHp\*(C'\fR that takes a literal string and calculates its size
20343 directly.
20344 .RS 4
20345 .Sp
20346 .Vb 1
20347 \& void XPUSHpvs("literal string")
20348 .Ve
20349 .RE
20350 .RS 4
20351 .RE
20352 .ie n .IP """XPUSHs""" 4
20353 .el .IP \f(CWXPUSHs\fR 4
20354 .IX Xref "XPUSHs"
20355 .IX Item "XPUSHs"
20356 Push an SV onto the stack, extending the stack if necessary. Does not
20357 handle 'set' magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHmortal"\fR,
20358 \&\f(CW\*(C`PUSHs\*(C'\fR and \f(CW\*(C`PUSHmortal\*(C'\fR.
20359 .RS 4
20360 .Sp
20361 .Vb 1
20362 \& void XPUSHs(SV* sv)
20363 .Ve
20364 .RE
20365 .RS 4
20366 .RE
20367 .ie n .IP """XPUSHu""" 4
20368 .el .IP \f(CWXPUSHu\fR 4
20369 .IX Xref "XPUSHu"
20370 .IX Item "XPUSHu"
20371 Push an unsigned integer onto the stack, extending the stack if necessary.
20372 Handles 'set' magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
20373 called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
20374 return lists from XSUB's \- see \f(CW"mXPUSHu"\fR instead. See also \f(CW"PUSHu"\fR and
20375 \&\f(CW"mPUSHu"\fR.
20376 .RS 4
20377 .Sp
20378 .Vb 1
20379 \& void XPUSHu(UV uv)
20380 .Ve
20381 .RE
20382 .RS 4
20383 .RE
20384 .ie n .IP """XS_APIVERSION_BOOTCHECK""" 4
20385 .el .IP \f(CWXS_APIVERSION_BOOTCHECK\fR 4
20386 .IX Xref "XS_APIVERSION_BOOTCHECK"
20387 .IX Item "XS_APIVERSION_BOOTCHECK"
20388 Macro to verify that the perl api version an XS module has been compiled against
20389 matches the api version of the perl interpreter it's being loaded into.
20390 .RS 4
20391 .Sp
20392 .Vb 1
20393 \& XS_APIVERSION_BOOTCHECK;
20394 .Ve
20395 .RE
20396 .RS 4
20397 .RE
20398 .ie n .IP """XSRETURN""" 4
20399 .el .IP \f(CWXSRETURN\fR 4
20400 .IX Xref "XSRETURN"
20401 .IX Item "XSRETURN"
20402 Return from XSUB, indicating number of items on the stack. This is usually
20403 handled by \f(CW\*(C`xsubpp\*(C'\fR.
20404 .RS 4
20405 .Sp
20406 .Vb 1
20407 \& void XSRETURN(int nitems)
20408 .Ve
20409 .RE
20410 .RS 4
20411 .RE
20412 .ie n .IP """XSRETURN_EMPTY""" 4
20413 .el .IP \f(CWXSRETURN_EMPTY\fR 4
20414 .IX Xref "XSRETURN_EMPTY"
20415 .IX Item "XSRETURN_EMPTY"
20416 Return an empty list from an XSUB immediately.
20417 .RS 4
20418 .Sp
20419 .Vb 1
20420 \& XSRETURN_EMPTY;
20421 .Ve
20422 .RE
20423 .RS 4
20424 .RE
20425 .ie n .IP """XSRETURN_IV""" 4
20426 .el .IP \f(CWXSRETURN_IV\fR 4
20427 .IX Xref "XSRETURN_IV"
20428 .IX Item "XSRETURN_IV"
20429 Return an integer from an XSUB immediately. Uses \f(CW\*(C`XST_mIV\*(C'\fR.
20430 .RS 4
20431 .Sp
20432 .Vb 1
20433 \& void XSRETURN_IV(IV iv)
20434 .Ve
20435 .RE
20436 .RS 4
20437 .RE
20438 .ie n .IP """XSRETURN_NO""" 4
20439 .el .IP \f(CWXSRETURN_NO\fR 4
20440 .IX Xref "XSRETURN_NO"
20441 .IX Item "XSRETURN_NO"
20442 Return \f(CW&PL_sv_no\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mNO\*(C'\fR.
20443 .RS 4
20444 .Sp
20445 .Vb 1
20446 \& XSRETURN_NO;
20447 .Ve
20448 .RE
20449 .RS 4
20450 .RE
20451 .ie n .IP """XSRETURN_NV""" 4
20452 .el .IP \f(CWXSRETURN_NV\fR 4
20453 .IX Xref "XSRETURN_NV"
20454 .IX Item "XSRETURN_NV"
20455 Return a double from an XSUB immediately. Uses \f(CW\*(C`XST_mNV\*(C'\fR.
20456 .RS 4
20457 .Sp
20458 .Vb 1
20459 \& void XSRETURN_NV(NV nv)
20460 .Ve
20461 .RE
20462 .RS 4
20463 .RE
20464 .ie n .IP """XSRETURN_PV""" 4
20465 .el .IP \f(CWXSRETURN_PV\fR 4
20466 .IX Xref "XSRETURN_PV"
20467 .IX Item "XSRETURN_PV"
20468 Return a copy of a string from an XSUB immediately. Uses \f(CW\*(C`XST_mPV\*(C'\fR.
20469 .RS 4
20470 .Sp
20471 .Vb 1
20472 \& void XSRETURN_PV(char* str)
20473 .Ve
20474 .RE
20475 .RS 4
20476 .RE
20477 .ie n .IP """XSRETURN_UNDEF""" 4
20478 .el .IP \f(CWXSRETURN_UNDEF\fR 4
20479 .IX Xref "XSRETURN_UNDEF"
20480 .IX Item "XSRETURN_UNDEF"
20481 Return \f(CW&PL_sv_undef\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mUNDEF\*(C'\fR.
20482 .RS 4
20483 .Sp
20484 .Vb 1
20485 \& XSRETURN_UNDEF;
20486 .Ve
20487 .RE
20488 .RS 4
20489 .RE
20490 .ie n .IP """XSRETURN_UV""" 4
20491 .el .IP \f(CWXSRETURN_UV\fR 4
20492 .IX Xref "XSRETURN_UV"
20493 .IX Item "XSRETURN_UV"
20494 Return an integer from an XSUB immediately. Uses \f(CW\*(C`XST_mUV\*(C'\fR.
20495 .RS 4
20496 .Sp
20497 .Vb 1
20498 \& void XSRETURN_UV(IV uv)
20499 .Ve
20500 .RE
20501 .RS 4
20502 .RE
20503 .ie n .IP """XSRETURN_YES""" 4
20504 .el .IP \f(CWXSRETURN_YES\fR 4
20505 .IX Xref "XSRETURN_YES"
20506 .IX Item "XSRETURN_YES"
20507 Return \f(CW&PL_sv_yes\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mYES\*(C'\fR.
20508 .RS 4
20509 .Sp
20510 .Vb 1
20511 \& XSRETURN_YES;
20512 .Ve
20513 .RE
20514 .RS 4
20515 .RE
20516 .ie n .IP """XST_mIV""" 4
20517 .el .IP \f(CWXST_mIV\fR 4
20518 .IX Xref "XST_mIV"
20519 .IX Item "XST_mIV"
20520 Place an integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The
20521 value is stored in a new mortal SV.
20522 .RS 4
20523 .Sp
20524 .Vb 1
20525 \& void XST_mIV(int pos, IV iv)
20526 .Ve
20527 .RE
20528 .RS 4
20529 .RE
20530 .ie n .IP """XST_mNO""" 4
20531 .el .IP \f(CWXST_mNO\fR 4
20532 .IX Xref "XST_mNO"
20533 .IX Item "XST_mNO"
20534 Place \f(CW&PL_sv_no\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
20535 stack.
20536 .RS 4
20537 .Sp
20538 .Vb 1
20539 \& void XST_mNO(int pos)
20540 .Ve
20541 .RE
20542 .RS 4
20543 .RE
20544 .ie n .IP """XST_mNV""" 4
20545 .el .IP \f(CWXST_mNV\fR 4
20546 .IX Xref "XST_mNV"
20547 .IX Item "XST_mNV"
20548 Place a double into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The value
20549 is stored in a new mortal SV.
20550 .RS 4
20551 .Sp
20552 .Vb 1
20553 \& void XST_mNV(int pos, NV nv)
20554 .Ve
20555 .RE
20556 .RS 4
20557 .RE
20558 .ie n .IP """XST_mPV""" 4
20559 .el .IP \f(CWXST_mPV\fR 4
20560 .IX Xref "XST_mPV"
20561 .IX Item "XST_mPV"
20562 Place a copy of a string into the specified position \f(CW\*(C`pos\*(C'\fR on the stack.
20563 The value is stored in a new mortal SV.
20564 .RS 4
20565 .Sp
20566 .Vb 1
20567 \& void XST_mPV(int pos, char* str)
20568 .Ve
20569 .RE
20570 .RS 4
20571 .RE
20572 .ie n .IP """XST_mUNDEF""" 4
20573 .el .IP \f(CWXST_mUNDEF\fR 4
20574 .IX Xref "XST_mUNDEF"
20575 .IX Item "XST_mUNDEF"
20576 Place \f(CW&PL_sv_undef\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
20577 stack.
20578 .RS 4
20579 .Sp
20580 .Vb 1
20581 \& void XST_mUNDEF(int pos)
20582 .Ve
20583 .RE
20584 .RS 4
20585 .RE
20586 .ie n .IP """XST_mUV""" 4
20587 .el .IP \f(CWXST_mUV\fR 4
20588 .IX Xref "XST_mUV"
20589 .IX Item "XST_mUV"
20590 Place an unsigned integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The
20591 value is stored in a new mortal SV.
20592 .RS 4
20593 .Sp
20594 .Vb 1
20595 \& void XST_mUV(int pos, UV uv)
20596 .Ve
20597 .RE
20598 .RS 4
20599 .RE
20600 .ie n .IP """XST_mYES""" 4
20601 .el .IP \f(CWXST_mYES\fR 4
20602 .IX Xref "XST_mYES"
20603 .IX Item "XST_mYES"
20604 Place \f(CW&PL_sv_yes\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
20605 stack.
20606 .RS 4
20607 .Sp
20608 .Vb 1
20609 \& void XST_mYES(int pos)
20610 .Ve
20611 .RE
20612 .RS 4
20613 .RE
20614 .ie n .IP """XS_VERSION""" 4
20615 .el .IP \f(CWXS_VERSION\fR 4
20616 .IX Xref "XS_VERSION"
20617 .IX Item "XS_VERSION"
20618 The version identifier for an XS module. This is usually
20619 handled automatically by \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. See
20620 \&\f(CW"XS_VERSION_BOOTCHECK"\fR.
20621 .ie n .IP """XS_VERSION_BOOTCHECK""" 4
20622 .el .IP \f(CWXS_VERSION_BOOTCHECK\fR 4
20623 .IX Xref "XS_VERSION_BOOTCHECK"
20624 .IX Item "XS_VERSION_BOOTCHECK"
20625 Macro to verify that a PM module's \f(CW$VERSION\fR variable matches the XS
20626 module's \f(CW\*(C`XS_VERSION\*(C'\fR variable. This is usually handled automatically by
20627 \&\f(CW\*(C`xsubpp\*(C'\fR. See "The VERSIONCHECK: Keyword" in perlxs.
20628 .RS 4
20629 .Sp
20630 .Vb 1
20631 \& XS_VERSION_BOOTCHECK;
20632 .Ve
20633 .RE
20634 .RS 4
20635 .RE
20636 .SH "String Handling"
20637 .IX Header "String Handling"
20638 See also \f(CW"Unicode Support"\fR.
20639 .ie n .IP """CAT2""" 4
20640 .el .IP \f(CWCAT2\fR 4
20641 .IX Xref "CAT2"
20642 .IX Item "CAT2"
20643 This macro concatenates 2 tokens together.
20644 .RS 4
20645 .Sp
20646 .Vb 1
20647 \& token CAT2(token x, token y)
20648 .Ve
20649 .RE
20650 .RS 4
20651 .RE
20652 .ie n .IP """Copy""" 4
20653 .el .IP \f(CWCopy\fR 4
20654 .IX Item "Copy"
20655 .PD 0
20656 .ie n .IP """CopyD""" 4
20657 .el .IP \f(CWCopyD\fR 4
20658 .IX Xref "Copy CopyD"
20659 .IX Item "CopyD"
20660 .PD
20661 The XSUB-writer's interface to the C \f(CW\*(C`memcpy\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the
20662 source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and
20663 \&\f(CW\*(C`type\*(C'\fR is the type. May fail on overlapping copies. See also \f(CW"Move"\fR.
20664 .Sp
20665 \&\f(CW\*(C`CopyD\*(C'\fR is like \f(CW\*(C`Copy\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful
20666 for encouraging compilers to tail-call
20667 optimise.
20668 .RS 4
20669 .Sp
20670 .Vb 2
20671 \& void Copy (void* src, void* dest, int nitems, type)
20672 \& void * CopyD(void* src, void* dest, int nitems, type)
20673 .Ve
20674 .RE
20675 .RS 4
20676 .RE
20677 .ie n .IP """delimcpy""" 4
20678 .el .IP \f(CWdelimcpy\fR 4
20679 .IX Xref "delimcpy"
20680 .IX Item "delimcpy"
20681 Copy a source buffer to a destination buffer, stopping at (but not including)
20682 the first occurrence in the source of an unescaped (defined below) delimiter
20683 byte, \f(CW\*(C`delim\*(C'\fR. The source is the bytes between \f(CW\*(C`from\*(C'\fR\ and\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1. Similarly, the dest is \f(CW\*(C`to\*(C'\fR up to \f(CW\*(C`to_end\*(C'\fR.
20684 .Sp
20685 The number of bytes copied is written to \f(CW*retlen\fR.
20686 .Sp
20687 Returns the position of the first uncopied \f(CW\*(C`delim\*(C'\fR in the \f(CW\*(C`from\*(C'\fR buffer, but
20688 if there is no such occurrence before \f(CW\*(C`from_end\*(C'\fR, then \f(CW\*(C`from_end\*(C'\fR is returned,
20689 and the entire buffer \f(CW\*(C`from\*(C'\fR\ ..\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1 is copied.
20690 .Sp
20691 If there is room in the destination available after the copy, an extra
20692 terminating safety \f(CW\*(C`NUL\*(C'\fR byte is appended (not included in the returned
20693 length).
20694 .Sp
20695 The error case is if the destination buffer is not large enough to accommodate
20696 everything that should be copied. In this situation, a value larger than
20697 \&\f(CW\*(C`to_end\*(C'\fR\ \-\ \f(CW\*(C`to\*(C'\fR is written to \f(CW*retlen\fR, and as much of the source as
20698 fits will be written to the destination. Not having room for the safety \f(CW\*(C`NUL\*(C'\fR
20699 is not considered an error.
20700 .Sp
20701 In the following examples, let \f(CW\*(C`x\*(C'\fR be the delimiter, and \f(CW0\fR represent a \f(CW\*(C`NUL\*(C'\fR
20702 byte (\fBNOT\fR the digit \f(CW0\fR). Then we would have
20703 .Sp
20704 .Vb 2
20705 \& Source Destination
20706 \& abcxdef abc0
20707 .Ve
20708 .Sp
20709 provided the destination buffer is at least 4 bytes long.
20710 .Sp
20711 An escaped delimiter is one which is immediately preceded by a single
20712 backslash. Escaped delimiters are copied, and the copy continues past the
20713 delimiter; the backslash is not copied:
20714 .Sp
20715 .Vb 2
20716 \& Source Destination
20717 \& abc\exdef abcxdef0
20718 .Ve
20719 .Sp
20720 (provided the destination buffer is at least 8 bytes long).
20721 .Sp
20722 It's actually somewhat more complicated than that. A sequence of any odd number
20723 of backslashes escapes the following delimiter, and the copy continues with
20724 exactly one of the backslashes stripped.
20725 .Sp
20726 .Vb 4
20727 \& Source Destination
20728 \& abc\exdef abcxdef0
20729 \& abc\e\e\exdef abc\e\exdef0
20730 \& abc\e\e\e\e\exdef abc\e\e\e\exdef0
20731 .Ve
20732 .Sp
20733 (as always, if the destination is large enough)
20734 .Sp
20735 An even number of preceding backslashes does not escape the delimiter, so that
20736 the copy stops just before it, and includes all the backslashes (no stripping;
20737 zero is considered even):
20738 .Sp
20739 .Vb 4
20740 \& Source Destination
20741 \& abcxdef abc0
20742 \& abc\e\exdef abc\e\e0
20743 \& abc\e\e\e\exdef abc\e\e\e\e0
20744 .Ve
20745 .RS 4
20746 .Sp
20747 .Vb 3
20748 \& char * delimcpy(char *to, const char *to_end, const char *from,
20749 \& const char *from_end, const int delim,
20750 \& I32 *retlen)
20751 .Ve
20752 .RE
20753 .RS 4
20754 .RE
20755 .ie n .IP """do_join""" 4
20756 .el .IP \f(CWdo_join\fR 4
20757 .IX Xref "do_join"
20758 .IX Item "do_join"
20759 This performs a Perl \f(CW\*(C`join\*(C'\fR, placing the joined output
20760 into \f(CW\*(C`sv\*(C'\fR.
20761 .Sp
20762 The elements to join are in SVs, stored in a C array of pointers to SVs, from
20763 \&\f(CW**mark\fR to \f(CW\*(C`**sp\ \-\ 1\*(C'\fR. Hence \f(CW*mark\fR is a reference to the first SV.
20764 Each SV will be coerced into a PV if not one already.
20765 .Sp
20766 \&\f(CW\*(C`delim\*(C'\fR contains the string (or coerced into a string) that is to separate
20767 each of the joined elements.
20768 .Sp
20769 If any component is in UTF\-8, the result will be as well, and all non\-UTF\-8
20770 components will be converted to UTF\-8 as necessary.
20771 .Sp
20772 Magic and tainting are handled.
20773 .RS 4
20774 .Sp
20775 .Vb 1
20776 \& void do_join(SV *sv, SV *delim, SV **mark, SV **sp)
20777 .Ve
20778 .RE
20779 .RS 4
20780 .RE
20781 .ie n .IP """do_sprintf""" 4
20782 .el .IP \f(CWdo_sprintf\fR 4
20783 .IX Xref "do_sprintf"
20784 .IX Item "do_sprintf"
20785 This performs a Perl \f(CW\*(C`sprintf\*(C'\fR placing the string output
20786 into \f(CW\*(C`sv\*(C'\fR.
20787 .Sp
20788 The elements to format are in SVs, stored in a C array of pointers to SVs of
20789 length \f(CW\*(C`len\*(C'\fR> and beginning at \f(CW**sarg\fR. The element referenced by \f(CW*sarg\fR
20790 is the format.
20791 .Sp
20792 Magic and tainting are handled.
20793 .RS 4
20794 .Sp
20795 .Vb 1
20796 \& void do_sprintf(SV *sv, SSize_t len, SV **sarg)
20797 .Ve
20798 .RE
20799 .RS 4
20800 .RE
20801 .ie n .IP """fbm_compile""" 4
20802 .el .IP \f(CWfbm_compile\fR 4
20803 .IX Xref "fbm_compile"
20804 .IX Item "fbm_compile"
20805 Analyzes the string in order to make fast searches on it using \f(CWfbm_instr()\fR
20806 \&\-\- the Boyer-Moore algorithm.
20807 .RS 4
20808 .Sp
20809 .Vb 1
20810 \& void fbm_compile(SV *sv, U32 flags)
20811 .Ve
20812 .RE
20813 .RS 4
20814 .RE
20815 .ie n .IP """fbm_instr""" 4
20816 .el .IP \f(CWfbm_instr\fR 4
20817 .IX Xref "fbm_instr"
20818 .IX Item "fbm_instr"
20819 Returns the location of the SV in the string delimited by \f(CW\*(C`big\*(C'\fR and
20820 \&\f(CW\*(C`bigend\*(C'\fR (\f(CW\*(C`bigend\*(C'\fR) is the char following the last char).
20821 It returns \f(CW\*(C`NULL\*(C'\fR if the string can't be found. The \f(CW\*(C`sv\*(C'\fR
20822 does not have to be \f(CW\*(C`fbm_compiled\*(C'\fR, but the search will not be as fast
20823 then.
20824 .RS 4
20825 .Sp
20826 .Vb 2
20827 \& char * fbm_instr(unsigned char *big, unsigned char *bigend,
20828 \& SV *littlestr, U32 flags)
20829 .Ve
20830 .RE
20831 .RS 4
20832 .RE
20833 .ie n .IP """foldEQ""" 4
20834 .el .IP \f(CWfoldEQ\fR 4
20835 .IX Xref "foldEQ"
20836 .IX Item "foldEQ"
20837 Returns true if the leading \f(CW\*(C`len\*(C'\fR bytes of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR are the
20838 same
20839 case-insensitively; false otherwise. Uppercase and lowercase ASCII range bytes
20840 match themselves and their opposite case counterparts. Non-cased and non-ASCII
20841 range bytes match only themselves.
20842 .RS 4
20843 .Sp
20844 .Vb 1
20845 \& I32 foldEQ(const char *a, const char *b, I32 len)
20846 .Ve
20847 .RE
20848 .RS 4
20849 .RE
20850 .ie n .IP """ibcmp""" 4
20851 .el .IP \f(CWibcmp\fR 4
20852 .IX Xref "ibcmp"
20853 .IX Item "ibcmp"
20854 This is a synonym for \f(CW\*(C`(!\ foldEQ())\*(C'\fR
20855 .RS 4
20856 .Sp
20857 .Vb 1
20858 \& I32 ibcmp(const char *a, const char *b, I32 len)
20859 .Ve
20860 .RE
20861 .RS 4
20862 .RE
20863 .ie n .IP """ibcmp_locale""" 4
20864 .el .IP \f(CWibcmp_locale\fR 4
20865 .IX Xref "ibcmp_locale"
20866 .IX Item "ibcmp_locale"
20867 This is a synonym for \f(CW\*(C`(!\ foldEQ_locale())\*(C'\fR
20868 .RS 4
20869 .Sp
20870 .Vb 1
20871 \& I32 ibcmp_locale(const char *a, const char *b, I32 len)
20872 .Ve
20873 .RE
20874 .RS 4
20875 .RE
20876 .ie n .IP """ibcmp_utf8""" 4
20877 .el .IP \f(CWibcmp_utf8\fR 4
20878 .IX Xref "ibcmp_utf8"
20879 .IX Item "ibcmp_utf8"
20880 This is a synonym for \f(CW\*(C`(!\ foldEQ_utf8())\*(C'\fR
20881 .RS 4
20882 .Sp
20883 .Vb 2
20884 \& I32 ibcmp_utf8(const char *s1, char **pe1, UV l1, bool u1,
20885 \& const char *s2, char **pe2, UV l2, bool u2)
20886 .Ve
20887 .RE
20888 .RS 4
20889 .RE
20890 .ie n .IP """instr""" 4
20891 .el .IP \f(CWinstr\fR 4
20892 .IX Xref "instr"
20893 .IX Item "instr"
20894 Same as \fBstrstr\fR\|(3), which finds and returns a pointer to the first occurrence
20895 of the NUL-terminated substring \f(CW\*(C`little\*(C'\fR in the NUL-terminated string \f(CW\*(C`big\*(C'\fR,
20896 returning NULL if not found. The terminating NUL bytes are not compared.
20897 .RS 4
20898 .Sp
20899 .Vb 1
20900 \& char * instr(const char *big, const char *little)
20901 .Ve
20902 .RE
20903 .RS 4
20904 .RE
20905 .ie n .IP """memCHRs""" 4
20906 .el .IP \f(CWmemCHRs\fR 4
20907 .IX Xref "memCHRs"
20908 .IX Item "memCHRs"
20909 Returns the position of the first occurrence of the byte \f(CW\*(C`c\*(C'\fR in the literal
20910 string \f(CW"list"\fR, or NULL if \f(CW\*(C`c\*(C'\fR doesn't appear in \f(CW"list"\fR. All bytes are
20911 treated as unsigned char. Thus this macro can be used to determine if \f(CW\*(C`c\*(C'\fR is
20912 in a set of particular characters. Unlike \fBstrchr\fR\|(3), it works even if \f(CW\*(C`c\*(C'\fR
20913 is \f(CW\*(C`NUL\*(C'\fR (and the set doesn't include \f(CW\*(C`NUL\*(C'\fR).
20914 .RS 4
20915 .Sp
20916 .Vb 1
20917 \& bool memCHRs("list", char c)
20918 .Ve
20919 .RE
20920 .RS 4
20921 .RE
20922 .ie n .IP """memEQ""" 4
20923 .el .IP \f(CWmemEQ\fR 4
20924 .IX Xref "memEQ"
20925 .IX Item "memEQ"
20926 Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they
20927 are equal. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare.
20928 Returns true or false. It is undefined behavior if either of the buffers
20929 doesn't contain at least \f(CW\*(C`len\*(C'\fR bytes.
20930 .RS 4
20931 .Sp
20932 .Vb 1
20933 \& bool memEQ(char* s1, char* s2, STRLEN len)
20934 .Ve
20935 .RE
20936 .RS 4
20937 .RE
20938 .ie n .IP """memEQs""" 4
20939 .el .IP \f(CWmemEQs\fR 4
20940 .IX Xref "memEQs"
20941 .IX Item "memEQs"
20942 Like "memEQ", but the second string is a literal enclosed in double quotes,
20943 \&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR.
20944 Returns true or false.
20945 .RS 4
20946 .Sp
20947 .Vb 1
20948 \& bool memEQs(char* s1, STRLEN l1, "s2")
20949 .Ve
20950 .RE
20951 .RS 4
20952 .RE
20953 .ie n .IP """memNE""" 4
20954 .el .IP \f(CWmemNE\fR 4
20955 .IX Xref "memNE"
20956 .IX Item "memNE"
20957 Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they
20958 are not equal. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare.
20959 Returns true or false. It is undefined behavior if either of the buffers
20960 doesn't contain at least \f(CW\*(C`len\*(C'\fR bytes.
20961 .RS 4
20962 .Sp
20963 .Vb 1
20964 \& bool memNE(char* s1, char* s2, STRLEN len)
20965 .Ve
20966 .RE
20967 .RS 4
20968 .RE
20969 .ie n .IP """memNEs""" 4
20970 .el .IP \f(CWmemNEs\fR 4
20971 .IX Xref "memNEs"
20972 .IX Item "memNEs"
20973 Like "memNE", but the second string is a literal enclosed in double quotes,
20974 \&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR.
20975 Returns true or false.
20976 .RS 4
20977 .Sp
20978 .Vb 1
20979 \& bool memNEs(char* s1, STRLEN l1, "s2")
20980 .Ve
20981 .RE
20982 .RS 4
20983 .RE
20984 .ie n .IP """Move""" 4
20985 .el .IP \f(CWMove\fR 4
20986 .IX Item "Move"
20987 .PD 0
20988 .ie n .IP """MoveD""" 4
20989 .el .IP \f(CWMoveD\fR 4
20990 .IX Xref "Move MoveD"
20991 .IX Item "MoveD"
20992 .PD
20993 The XSUB-writer's interface to the C \f(CW\*(C`memmove\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the
20994 source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and
20995 \&\f(CW\*(C`type\*(C'\fR is the type. Can do overlapping moves. See also \f(CW"Copy"\fR.
20996 .Sp
20997 \&\f(CW\*(C`MoveD\*(C'\fR is like \f(CW\*(C`Move\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful
20998 for encouraging compilers to tail-call
20999 optimise.
21000 .RS 4
21001 .Sp
21002 .Vb 2
21003 \& void Move (void* src, void* dest, int nitems, type)
21004 \& void * MoveD(void* src, void* dest, int nitems, type)
21005 .Ve
21006 .RE
21007 .RS 4
21008 .RE
21009 .ie n .IP """my_snprintf""" 4
21010 .el .IP \f(CWmy_snprintf\fR 4
21011 .IX Xref "my_snprintf"
21012 .IX Item "my_snprintf"
21013 The C library \f(CW\*(C`snprintf\*(C'\fR functionality, if available and
21014 standards-compliant (uses \f(CW\*(C`vsnprintf\*(C'\fR, actually). However, if the
21015 \&\f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately use the unsafe
21016 \&\f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an overrun check,
21017 but that may be too late). Consider using \f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or
21018 getting \f(CW\*(C`vsnprintf\*(C'\fR.
21019 .RS 4
21020 .Sp
21021 .Vb 2
21022 \& int my_snprintf(char *buffer, const Size_t len,
21023 \& const char *format, ...)
21024 .Ve
21025 .RE
21026 .RS 4
21027 .RE
21028 .ie n .IP """my_sprintf""" 4
21029 .el .IP \f(CWmy_sprintf\fR 4
21030 .IX Xref "my_sprintf"
21031 .IX Item "my_sprintf"
21032 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`my_sprintf\*(C'\fR
21033 from a future release of Perl. Do not use it for
21034 new code; remove it from existing code.
21035 .Sp
21036 Do NOT use this due to the possibility of overflowing \f(CW\*(C`buffer\*(C'\fR. Instead use
21037 \&\fBmy_snprintf()\fR
21038 .RS 4
21039 .Sp
21040 .Vb 1
21041 \& int my_sprintf(NN char *buffer, NN const char *pat, ...)
21042 .Ve
21043 .RE
21044 .RS 4
21045 .RE
21046 .ie n .IP """my_strnlen""" 4
21047 .el .IP \f(CWmy_strnlen\fR 4
21048 .IX Xref "my_strnlen"
21049 .IX Item "my_strnlen"
21050 The C library \f(CW\*(C`strnlen\*(C'\fR if available, or a Perl implementation of it.
21051 .Sp
21052 \&\f(CWmy_strnlen()\fR computes the length of the string, up to \f(CW\*(C`maxlen\*(C'\fR
21053 bytes. It will never attempt to address more than \f(CW\*(C`maxlen\*(C'\fR
21054 bytes, making it suitable for use with strings that are not
21055 guaranteed to be NUL-terminated.
21056 .RS 4
21057 .Sp
21058 .Vb 1
21059 \& Size_t my_strnlen(const char *str, Size_t maxlen)
21060 .Ve
21061 .RE
21062 .RS 4
21063 .RE
21064 .ie n .IP """my_vsnprintf""" 4
21065 .el .IP \f(CWmy_vsnprintf\fR 4
21066 .IX Xref "my_vsnprintf"
21067 .IX Item "my_vsnprintf"
21068 The C library \f(CW\*(C`vsnprintf\*(C'\fR if available and standards-compliant.
21069 However, if the \f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately
21070 use the unsafe \f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an
21071 overrun check, but that may be too late). Consider using
21072 \&\f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or getting \f(CW\*(C`vsnprintf\*(C'\fR.
21073 .RS 4
21074 .Sp
21075 .Vb 2
21076 \& int my_vsnprintf(char *buffer, const Size_t len,
21077 \& const char *format, va_list ap)
21078 .Ve
21079 .RE
21080 .RS 4
21081 .RE
21082 .ie n .IP """NewCopy""" 4
21083 .el .IP \f(CWNewCopy\fR 4
21084 .IX Xref "NewCopy"
21085 .IX Item "NewCopy"
21086 Combines \fBNewx()\fR and \fBCopy()\fR into a single macro. Dest will be allocated
21087 using \fBNewx()\fR and then src will be copied into it.
21088 .RS 4
21089 .Sp
21090 .Vb 1
21091 \& void NewCopy(void* src, void* dest, int nitems, type)
21092 .Ve
21093 .RE
21094 .RS 4
21095 .RE
21096 .ie n .IP """ninstr""" 4
21097 .el .IP \f(CWninstr\fR 4
21098 .IX Xref "ninstr"
21099 .IX Item "ninstr"
21100 Find the first (leftmost) occurrence of a sequence of bytes within another
21101 sequence. This is the Perl version of \f(CWstrstr()\fR, extended to handle
21102 arbitrary sequences, potentially containing embedded \f(CW\*(C`NUL\*(C'\fR characters (\f(CW\*(C`NUL\*(C'\fR
21103 is what the initial \f(CW\*(C`n\*(C'\fR in the function name stands for; some systems have an
21104 equivalent, \f(CWmemmem()\fR, but with a somewhat different API).
21105 .Sp
21106 Another way of thinking about this function is finding a needle in a haystack.
21107 \&\f(CW\*(C`big\*(C'\fR points to the first byte in the haystack. \f(CW\*(C`big_end\*(C'\fR points to one byte
21108 beyond the final byte in the haystack. \f(CW\*(C`little\*(C'\fR points to the first byte in
21109 the needle. \f(CW\*(C`little_end\*(C'\fR points to one byte beyond the final byte in the
21110 needle. All the parameters must be non\-\f(CW\*(C`NULL\*(C'\fR.
21111 .Sp
21112 The function returns \f(CW\*(C`NULL\*(C'\fR if there is no occurrence of \f(CW\*(C`little\*(C'\fR within
21113 \&\f(CW\*(C`big\*(C'\fR. If \f(CW\*(C`little\*(C'\fR is the empty string, \f(CW\*(C`big\*(C'\fR is returned.
21114 .Sp
21115 Because this function operates at the byte level, and because of the inherent
21116 characteristics of UTF\-8 (or UTF-EBCDIC), it will work properly if both the
21117 needle and the haystack are strings with the same UTF\-8ness, but not if the
21118 UTF\-8ness differs.
21119 .RS 4
21120 .Sp
21121 .Vb 2
21122 \& char * ninstr(const char *big, const char *bigend,
21123 \& const char *little, const char *lend)
21124 .Ve
21125 .RE
21126 .RS 4
21127 .RE
21128 .ie n .IP """Nullch""" 4
21129 .el .IP \f(CWNullch\fR 4
21130 .IX Xref "Nullch"
21131 .IX Item "Nullch"
21132 Null character pointer. (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is
21133 defined.)
21134 .ie n .IP """PL_na""" 4
21135 .el .IP \f(CWPL_na\fR 4
21136 .IX Xref "PL_na"
21137 .IX Item "PL_na"
21138 A scratch pad variable in which to store a \f(CW\*(C`STRLEN\*(C'\fR value. If would have been
21139 better named something like \f(CW\*(C`PL_temp_strlen\*(C'\fR.
21140 .Sp
21141 It is is typically used with \f(CW\*(C`SvPV\*(C'\fR when one is actually planning to discard
21142 the returned length, (hence the length is "Not Applicable", which is how this
21143 variable got its name).
21144 .Sp
21145 \&\fBBUT BEWARE\fR, if this is used in a situation where something that is using it
21146 is in a call stack with something else that is using it, this variable would
21147 get zapped, leading to hard-to-diagnose errors.
21148 .Sp
21149 It is usually more efficient to either declare a local variable and use that
21150 instead, or to use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro.
21151 .RS 4
21152 .Sp
21153 .Vb 1
21154 \& STRLEN PL_na
21155 .Ve
21156 .RE
21157 .RS 4
21158 .RE
21159 .ie n .IP """rninstr""" 4
21160 .el .IP \f(CWrninstr\fR 4
21161 .IX Xref "rninstr"
21162 .IX Item "rninstr"
21163 Like \f(CW"ninstr"\fR, but instead finds the final (rightmost) occurrence of a
21164 sequence of bytes within another sequence, returning \f(CW\*(C`NULL\*(C'\fR if there is no
21165 such occurrence.
21166 .RS 4
21167 .Sp
21168 .Vb 2
21169 \& char * rninstr(const char *big, const char *bigend,
21170 \& const char *little, const char *lend)
21171 .Ve
21172 .RE
21173 .RS 4
21174 .RE
21175 .ie n .IP """savepv""" 4
21176 .el .IP \f(CWsavepv\fR 4
21177 .IX Xref "savepv"
21178 .IX Item "savepv"
21179 Perl's version of \f(CWstrdup()\fR. Returns a pointer to a newly allocated
21180 string which is a duplicate of \f(CW\*(C`pv\*(C'\fR. The size of the string is
21181 determined by \f(CWstrlen()\fR, which means it may not contain embedded \f(CW\*(C`NUL\*(C'\fR
21182 characters and must have a trailing \f(CW\*(C`NUL\*(C'\fR. To prevent memory leaks, the
21183 memory allocated for the new string needs to be freed when no longer needed.
21184 This can be done with the \f(CW"Safefree"\fR function, or
21185 \&\f(CW\*(C`SAVEFREEPV\*(C'\fR.
21186 .Sp
21187 On some platforms, Windows for example, all allocated memory owned by a thread
21188 is deallocated when that thread ends. So if you need that not to happen, you
21189 need to use the shared memory functions, such as \f(CW"savesharedpv"\fR.
21190 .RS 4
21191 .Sp
21192 .Vb 1
21193 \& char * savepv(const char *pv)
21194 .Ve
21195 .RE
21196 .RS 4
21197 .RE
21198 .ie n .IP """savepvn""" 4
21199 .el .IP \f(CWsavepvn\fR 4
21200 .IX Xref "savepvn"
21201 .IX Item "savepvn"
21202 Perl's version of what \f(CWstrndup()\fR would be if it existed. Returns a
21203 pointer to a newly allocated string which is a duplicate of the first
21204 \&\f(CW\*(C`len\*(C'\fR bytes from \f(CW\*(C`pv\*(C'\fR, plus a trailing
21205 \&\f(CW\*(C`NUL\*(C'\fR byte. The memory allocated for
21206 the new string can be freed with the \f(CWSafefree()\fR function.
21207 .Sp
21208 On some platforms, Windows for example, all allocated memory owned by a thread
21209 is deallocated when that thread ends. So if you need that not to happen, you
21210 need to use the shared memory functions, such as \f(CW"savesharedpvn"\fR.
21211 .RS 4
21212 .Sp
21213 .Vb 1
21214 \& char * savepvn(const char *pv, Size_t len)
21215 .Ve
21216 .RE
21217 .RS 4
21218 .RE
21219 .ie n .IP """savepvs""" 4
21220 .el .IP \f(CWsavepvs\fR 4
21221 .IX Xref "savepvs"
21222 .IX Item "savepvs"
21223 Like \f(CW\*(C`savepvn\*(C'\fR, but takes a literal string instead of a
21224 string/length pair.
21225 .RS 4
21226 .Sp
21227 .Vb 1
21228 \& char* savepvs("literal string")
21229 .Ve
21230 .RE
21231 .RS 4
21232 .RE
21233 .ie n .IP """savesharedpv""" 4
21234 .el .IP \f(CWsavesharedpv\fR 4
21235 .IX Xref "savesharedpv"
21236 .IX Item "savesharedpv"
21237 A version of \f(CWsavepv()\fR which allocates the duplicate string in memory
21238 which is shared between threads.
21239 .RS 4
21240 .Sp
21241 .Vb 1
21242 \& char * savesharedpv(const char *pv)
21243 .Ve
21244 .RE
21245 .RS 4
21246 .RE
21247 .ie n .IP """savesharedpvn""" 4
21248 .el .IP \f(CWsavesharedpvn\fR 4
21249 .IX Xref "savesharedpvn"
21250 .IX Item "savesharedpvn"
21251 A version of \f(CWsavepvn()\fR which allocates the duplicate string in memory
21252 which is shared between threads. (With the specific difference that a \f(CW\*(C`NULL\*(C'\fR
21253 pointer is not acceptable)
21254 .RS 4
21255 .Sp
21256 .Vb 1
21257 \& char * savesharedpvn(const char * const pv, const STRLEN len)
21258 .Ve
21259 .RE
21260 .RS 4
21261 .RE
21262 .ie n .IP """savesharedpvs""" 4
21263 .el .IP \f(CWsavesharedpvs\fR 4
21264 .IX Xref "savesharedpvs"
21265 .IX Item "savesharedpvs"
21266 A version of \f(CWsavepvs()\fR which allocates the duplicate string in memory
21267 which is shared between threads.
21268 .RS 4
21269 .Sp
21270 .Vb 1
21271 \& char* savesharedpvs("literal string")
21272 .Ve
21273 .RE
21274 .RS 4
21275 .RE
21276 .ie n .IP """savesharedsvpv""" 4
21277 .el .IP \f(CWsavesharedsvpv\fR 4
21278 .IX Xref "savesharedsvpv"
21279 .IX Item "savesharedsvpv"
21280 A version of \f(CWsavesharedpv()\fR which allocates the duplicate string in
21281 memory which is shared between threads.
21282 .RS 4
21283 .Sp
21284 .Vb 1
21285 \& char * savesharedsvpv(SV *sv)
21286 .Ve
21287 .RE
21288 .RS 4
21289 .RE
21290 .ie n .IP """savesvpv""" 4
21291 .el .IP \f(CWsavesvpv\fR 4
21292 .IX Xref "savesvpv"
21293 .IX Item "savesvpv"
21294 A version of \f(CWsavepv()\fR/\f(CWsavepvn()\fR which gets the string to duplicate from
21295 the passed in SV using \f(CWSvPV()\fR
21296 .Sp
21297 On some platforms, Windows for example, all allocated memory owned by a thread
21298 is deallocated when that thread ends. So if you need that not to happen, you
21299 need to use the shared memory functions, such as \f(CW"savesharedsvpv"\fR.
21300 .RS 4
21301 .Sp
21302 .Vb 1
21303 \& char * savesvpv(SV *sv)
21304 .Ve
21305 .RE
21306 .RS 4
21307 .RE
21308 .ie n .IP """strEQ""" 4
21309 .el .IP \f(CWstrEQ\fR 4
21310 .IX Xref "strEQ"
21311 .IX Item "strEQ"
21312 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal. Returns true or
21313 false.
21314 .RS 4
21315 .Sp
21316 .Vb 1
21317 \& bool strEQ(char* s1, char* s2)
21318 .Ve
21319 .RE
21320 .RS 4
21321 .RE
21322 .ie n .IP """strGE""" 4
21323 .el .IP \f(CWstrGE\fR 4
21324 .IX Xref "strGE"
21325 .IX Item "strGE"
21326 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than
21327 or equal to the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21328 .RS 4
21329 .Sp
21330 .Vb 1
21331 \& bool strGE(char* s1, char* s2)
21332 .Ve
21333 .RE
21334 .RS 4
21335 .RE
21336 .ie n .IP """strGT""" 4
21337 .el .IP \f(CWstrGT\fR 4
21338 .IX Xref "strGT"
21339 .IX Item "strGT"
21340 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than
21341 the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21342 .RS 4
21343 .Sp
21344 .Vb 1
21345 \& bool strGT(char* s1, char* s2)
21346 .Ve
21347 .RE
21348 .RS 4
21349 .RE
21350 .ie n .IP """STRINGIFY""" 4
21351 .el .IP \f(CWSTRINGIFY\fR 4
21352 .IX Xref "STRINGIFY"
21353 .IX Item "STRINGIFY"
21354 This macro surrounds its token with double quotes.
21355 .RS 4
21356 .Sp
21357 .Vb 1
21358 \& string STRINGIFY(token x)
21359 .Ve
21360 .RE
21361 .RS 4
21362 .RE
21363 .ie n .IP """strLE""" 4
21364 .el .IP \f(CWstrLE\fR 4
21365 .IX Xref "strLE"
21366 .IX Item "strLE"
21367 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than or
21368 equal to the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21369 .RS 4
21370 .Sp
21371 .Vb 1
21372 \& bool strLE(char* s1, char* s2)
21373 .Ve
21374 .RE
21375 .RS 4
21376 .RE
21377 .ie n .IP """STRLEN""" 4
21378 .el .IP \f(CWSTRLEN\fR 4
21379 .IX Item "STRLEN"
21380 Described in perlguts.
21381 .ie n .IP """strLT""" 4
21382 .el .IP \f(CWstrLT\fR 4
21383 .IX Xref "strLT"
21384 .IX Item "strLT"
21385 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is less than the
21386 second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21387 .RS 4
21388 .Sp
21389 .Vb 1
21390 \& bool strLT(char* s1, char* s2)
21391 .Ve
21392 .RE
21393 .RS 4
21394 .RE
21395 .ie n .IP """strNE""" 4
21396 .el .IP \f(CWstrNE\fR 4
21397 .IX Xref "strNE"
21398 .IX Item "strNE"
21399 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different. Returns true
21400 or false.
21401 .RS 4
21402 .Sp
21403 .Vb 1
21404 \& bool strNE(char* s1, char* s2)
21405 .Ve
21406 .RE
21407 .RS 4
21408 .RE
21409 .ie n .IP """strnEQ""" 4
21410 .el .IP \f(CWstrnEQ\fR 4
21411 .IX Xref "strnEQ"
21412 .IX Item "strnEQ"
21413 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal. The \f(CW\*(C`len\*(C'\fR
21414 parameter indicates the number of bytes to compare. Returns true or false. (A
21415 wrapper for \f(CW\*(C`strncmp\*(C'\fR).
21416 .RS 4
21417 .Sp
21418 .Vb 1
21419 \& bool strnEQ(char* s1, char* s2, STRLEN len)
21420 .Ve
21421 .RE
21422 .RS 4
21423 .RE
21424 .ie n .IP """strnNE""" 4
21425 .el .IP \f(CWstrnNE\fR 4
21426 .IX Xref "strnNE"
21427 .IX Item "strnNE"
21428 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different. The \f(CW\*(C`len\*(C'\fR
21429 parameter indicates the number of bytes to compare. Returns true or false. (A
21430 wrapper for \f(CW\*(C`strncmp\*(C'\fR).
21431 .RS 4
21432 .Sp
21433 .Vb 1
21434 \& bool strnNE(char* s1, char* s2, STRLEN len)
21435 .Ve
21436 .RE
21437 .RS 4
21438 .RE
21439 .ie n .IP """STR_WITH_LEN""" 4
21440 .el .IP \f(CWSTR_WITH_LEN\fR 4
21441 .IX Xref "STR_WITH_LEN"
21442 .IX Item "STR_WITH_LEN"
21443 Returns two comma separated tokens of the input literal string, and its length.
21444 This is convenience macro which helps out in some API calls.
21445 Note that it can't be used as an argument to macros or functions that under
21446 some configurations might be macros, which means that it requires the full
21447 Perl_xxx(aTHX_ ...) form for any API calls where it's used.
21448 .RS 4
21449 .Sp
21450 .Vb 1
21451 \& pair STR_WITH_LEN("literal string")
21452 .Ve
21453 .RE
21454 .RS 4
21455 .RE
21456 .ie n .IP """Zero""" 4
21457 .el .IP \f(CWZero\fR 4
21458 .IX Item "Zero"
21459 .PD 0
21460 .ie n .IP """ZeroD""" 4
21461 .el .IP \f(CWZeroD\fR 4
21462 .IX Xref "Zero ZeroD"
21463 .IX Item "ZeroD"
21464 .PD
21465 The XSUB-writer's interface to the C \f(CW\*(C`memzero\*(C'\fR function. The \f(CW\*(C`dest\*(C'\fR is the
21466 destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is the type.
21467 .Sp
21468 \&\f(CW\*(C`ZeroD\*(C'\fR is like \f(CW\*(C`Zero\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful
21469 for encouraging compilers to tail-call
21470 optimise.
21471 .RS 4
21472 .Sp
21473 .Vb 2
21474 \& void Zero (void* dest, int nitems, type)
21475 \& void * ZeroD(void* dest, int nitems, type)
21476 .Ve
21477 .RE
21478 .RS 4
21479 .RE
21480 .SH "SV Flags"
21481 .IX Header "SV Flags"
21482 .ie n .IP """SVt_IV""" 4
21483 .el .IP \f(CWSVt_IV\fR 4
21484 .IX Xref "SVt_IV"
21485 .IX Item "SVt_IV"
21486 Type flag for scalars. See "svtype".
21487 .ie n .IP """SVt_NULL""" 4
21488 .el .IP \f(CWSVt_NULL\fR 4
21489 .IX Xref "SVt_NULL"
21490 .IX Item "SVt_NULL"
21491 Type flag for scalars. See "svtype".
21492 .ie n .IP """SVt_NV""" 4
21493 .el .IP \f(CWSVt_NV\fR 4
21494 .IX Xref "SVt_NV"
21495 .IX Item "SVt_NV"
21496 Type flag for scalars. See "svtype".
21497 .ie n .IP """SVt_PV""" 4
21498 .el .IP \f(CWSVt_PV\fR 4
21499 .IX Xref "SVt_PV"
21500 .IX Item "SVt_PV"
21501 Type flag for scalars. See "svtype".
21502 .ie n .IP """SVt_PVAV""" 4
21503 .el .IP \f(CWSVt_PVAV\fR 4
21504 .IX Xref "SVt_PVAV"
21505 .IX Item "SVt_PVAV"
21506 Type flag for arrays. See "svtype".
21507 .ie n .IP """SVt_PVCV""" 4
21508 .el .IP \f(CWSVt_PVCV\fR 4
21509 .IX Xref "SVt_PVCV"
21510 .IX Item "SVt_PVCV"
21511 Type flag for subroutines. See "svtype".
21512 .ie n .IP """SVt_PVFM""" 4
21513 .el .IP \f(CWSVt_PVFM\fR 4
21514 .IX Xref "SVt_PVFM"
21515 .IX Item "SVt_PVFM"
21516 Type flag for formats. See "svtype".
21517 .ie n .IP """SVt_PVGV""" 4
21518 .el .IP \f(CWSVt_PVGV\fR 4
21519 .IX Xref "SVt_PVGV"
21520 .IX Item "SVt_PVGV"
21521 Type flag for typeglobs. See "svtype".
21522 .ie n .IP """SVt_PVHV""" 4
21523 .el .IP \f(CWSVt_PVHV\fR 4
21524 .IX Xref "SVt_PVHV"
21525 .IX Item "SVt_PVHV"
21526 Type flag for hashes. See "svtype".
21527 .ie n .IP """SVt_PVIO""" 4
21528 .el .IP \f(CWSVt_PVIO\fR 4
21529 .IX Xref "SVt_PVIO"
21530 .IX Item "SVt_PVIO"
21531 Type flag for I/O objects. See "svtype".
21532 .ie n .IP """SVt_PVIV""" 4
21533 .el .IP \f(CWSVt_PVIV\fR 4
21534 .IX Xref "SVt_PVIV"
21535 .IX Item "SVt_PVIV"
21536 Type flag for scalars. See "svtype".
21537 .ie n .IP """SVt_PVLV""" 4
21538 .el .IP \f(CWSVt_PVLV\fR 4
21539 .IX Xref "SVt_PVLV"
21540 .IX Item "SVt_PVLV"
21541 Type flag for scalars. See "svtype".
21542 .ie n .IP """SVt_PVMG""" 4
21543 .el .IP \f(CWSVt_PVMG\fR 4
21544 .IX Xref "SVt_PVMG"
21545 .IX Item "SVt_PVMG"
21546 Type flag for scalars. See "svtype".
21547 .ie n .IP """SVt_PVNV""" 4
21548 .el .IP \f(CWSVt_PVNV\fR 4
21549 .IX Xref "SVt_PVNV"
21550 .IX Item "SVt_PVNV"
21551 Type flag for scalars. See "svtype".
21552 .ie n .IP """SVt_PVOBJ""" 4
21553 .el .IP \f(CWSVt_PVOBJ\fR 4
21554 .IX Xref "SVt_PVOBJ"
21555 .IX Item "SVt_PVOBJ"
21556 NOTE: \f(CW\*(C`SVt_PVOBJ\*(C'\fR is \fBexperimental\fR and may change or be
21557 removed without notice.
21558 .Sp
21559 Type flag for object instances. See "svtype".
21560 .ie n .IP """SVt_REGEXP""" 4
21561 .el .IP \f(CWSVt_REGEXP\fR 4
21562 .IX Xref "SVt_REGEXP"
21563 .IX Item "SVt_REGEXP"
21564 Type flag for regular expressions. See "svtype".
21565 .ie n .IP """svtype""" 4
21566 .el .IP \f(CWsvtype\fR 4
21567 .IX Xref "svtype"
21568 .IX Item "svtype"
21569 An enum of flags for Perl types. These are found in the file \fIsv.h\fR
21570 in the \f(CW\*(C`svtype\*(C'\fR enum. Test these flags with the \f(CW\*(C`SvTYPE\*(C'\fR macro.
21571 .Sp
21572 The types are:
21573 .Sp
21574 .Vb 10
21575 \& SVt_NULL
21576 \& SVt_IV
21577 \& SVt_NV
21578 \& SVt_RV
21579 \& SVt_PV
21580 \& SVt_PVIV
21581 \& SVt_PVNV
21582 \& SVt_PVMG
21583 \& SVt_INVLIST
21584 \& SVt_REGEXP
21585 \& SVt_PVGV
21586 \& SVt_PVLV
21587 \& SVt_PVAV
21588 \& SVt_PVHV
21589 \& SVt_PVCV
21590 \& SVt_PVFM
21591 \& SVt_PVIO
21592 \& SVt_PVOBJ
21593 .Ve
21594 .Sp
21595 These are most easily explained from the bottom up.
21596 .Sp
21597 \&\f(CW\*(C`SVt_PVOBJ\*(C'\fR is for object instances of the new `use feature 'class'` kind.
21598 \&\f(CW\*(C`SVt_PVIO\*(C'\fR is for I/O objects, \f(CW\*(C`SVt_PVFM\*(C'\fR for formats, \f(CW\*(C`SVt_PVCV\*(C'\fR for
21599 subroutines, \f(CW\*(C`SVt_PVHV\*(C'\fR for hashes and \f(CW\*(C`SVt_PVAV\*(C'\fR for arrays.
21600 .Sp
21601 All the others are scalar types, that is, things that can be bound to a
21602 \&\f(CW\*(C`$\*(C'\fR variable. For these, the internal types are mostly orthogonal to
21603 types in the Perl language.
21604 .Sp
21605 Hence, checking \f(CW\*(C`SvTYPE(sv) < SVt_PVAV\*(C'\fR is the best way to see whether
21606 something is a scalar.
21607 .Sp
21608 \&\f(CW\*(C`SVt_PVGV\*(C'\fR represents a typeglob. If \f(CW\*(C`!SvFAKE(sv)\*(C'\fR, then it is a real,
21609 incoercible typeglob. If \f(CWSvFAKE(sv)\fR, then it is a scalar to which a
21610 typeglob has been assigned. Assigning to it again will stop it from being
21611 a typeglob. \f(CW\*(C`SVt_PVLV\*(C'\fR represents a scalar that delegates to another scalar
21612 behind the scenes. It is used, e.g., for the return value of \f(CW\*(C`substr\*(C'\fR and
21613 for tied hash and array elements. It can hold any scalar value, including
21614 a typeglob. \f(CW\*(C`SVt_REGEXP\*(C'\fR is for regular
21615 expressions. \f(CW\*(C`SVt_INVLIST\*(C'\fR is for Perl
21616 core internal use only.
21617 .Sp
21618 \&\f(CW\*(C`SVt_PVMG\*(C'\fR represents a "normal" scalar (not a typeglob, regular expression,
21619 or delegate). Since most scalars do not need all the internal fields of a
21620 PVMG, we save memory by allocating smaller structs when possible. All the
21621 other types are just simpler forms of \f(CW\*(C`SVt_PVMG\*(C'\fR, with fewer internal fields.
21622 \&\f(CW\*(C`SVt_NULL\*(C'\fR can only hold undef. \f(CW\*(C`SVt_IV\*(C'\fR can hold undef, an integer, or a
21623 reference. (\f(CW\*(C`SVt_RV\*(C'\fR is an alias for \f(CW\*(C`SVt_IV\*(C'\fR, which exists for backward
21624 compatibility.) \f(CW\*(C`SVt_NV\*(C'\fR can hold undef or a double. (In builds that support
21625 headless NVs, these could also hold a reference via a suitable offset, in the
21626 same way that SVt_IV does, but this is not currently supported and seems to
21627 be a rare use case.) \f(CW\*(C`SVt_PV\*(C'\fR can hold \f(CW\*(C`undef\*(C'\fR, a string, or a reference.
21628 \&\f(CW\*(C`SVt_PVIV\*(C'\fR is a superset of \f(CW\*(C`SVt_PV\*(C'\fR and \f(CW\*(C`SVt_IV\*(C'\fR. \f(CW\*(C`SVt_PVNV\*(C'\fR is a
21629 superset of \f(CW\*(C`SVt_PV\*(C'\fR and \f(CW\*(C`SVt_NV\*(C'\fR. \f(CW\*(C`SVt_PVMG\*(C'\fR can hold anything \f(CW\*(C`SVt_PVNV\*(C'\fR
21630 can hold, but it may also be blessed or magical.
21631 .SH "SV Handling"
21632 .IX Xref "SV_CATBYTES SV_CATUTF8 SV_COW_DROP_PV SV_FORCE_UTF8_UPGRADE SV_GMAGIC SV_HAS_TRAILING_NUL SV_IMMEDIATE_UNREF SV_NOSTEAL SV_SMAGIC SV_UTF8_NO_ENCODING SVs_TEMP"
21633 .IX Header "SV Handling"
21634 .ie n .IP """AV_FROM_REF""" 4
21635 .el .IP \f(CWAV_FROM_REF\fR 4
21636 .IX Item "AV_FROM_REF"
21637 .PD 0
21638 .ie n .IP """CV_FROM_REF""" 4
21639 .el .IP \f(CWCV_FROM_REF\fR 4
21640 .IX Item "CV_FROM_REF"
21641 .ie n .IP """HV_FROM_REF""" 4
21642 .el .IP \f(CWHV_FROM_REF\fR 4
21643 .IX Xref "AV_FROM_REF CV_FROM_REF HV_FROM_REF"
21644 .IX Item "HV_FROM_REF"
21645 .PD
21646 The \f(CW\*(C`\fR\f(CI*\fR\f(CWV_FROM_REF\*(C'\fR macros extract the \f(CWSvRV()\fR from a given reference SV
21647 and return a suitably-cast to pointer to the referenced SV. When running
21648 under \f(CW\*(C`\-DDEBUGGING\*(C'\fR, assertions are also applied that check that \fIref\fR is
21649 definitely a reference SV that refers to an SV of the right type.
21650 .RS 4
21651 .Sp
21652 .Vb 3
21653 \& AV * AV_FROM_REF(SV * ref)
21654 \& CV * CV_FROM_REF(SV * ref)
21655 \& HV * HV_FROM_REF(SV * ref)
21656 .Ve
21657 .RE
21658 .RS 4
21659 .RE
21660 .ie n .IP """BOOL_INTERNALS_sv_isbool""" 4
21661 .el .IP \f(CWBOOL_INTERNALS_sv_isbool\fR 4
21662 .IX Xref "BOOL_INTERNALS_sv_isbool"
21663 .IX Item "BOOL_INTERNALS_sv_isbool"
21664 Checks if a \f(CWSvBoolFlagsOK()\fR sv is a bool. \fBNote\fR that it is the
21665 caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR before
21666 calling this. This is only useful in specialized logic like
21667 serialization code where performance is critical and the flags have
21668 already been checked to be correct. Almost always you should be using
21669 \&\f(CWsv_isbool(sv)\fR instead.
21670 .RS 4
21671 .Sp
21672 .Vb 1
21673 \& bool BOOL_INTERNALS_sv_isbool(SV* sv)
21674 .Ve
21675 .RE
21676 .RS 4
21677 .RE
21678 .ie n .IP """BOOL_INTERNALS_sv_isbool_false""" 4
21679 .el .IP \f(CWBOOL_INTERNALS_sv_isbool_false\fR 4
21680 .IX Xref "BOOL_INTERNALS_sv_isbool_false"
21681 .IX Item "BOOL_INTERNALS_sv_isbool_false"
21682 Checks if a \f(CWSvBoolFlagsOK()\fR sv is a false bool. \fBNote\fR that it is
21683 the caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR
21684 before calling this. This is only useful in specialized logic like
21685 serialization code where performance is critical and the flags have
21686 already been checked to be correct. This is \fBNOT\fR what you should use
21687 to check if an SV is "false", for that you should be using
21688 \&\f(CW\*(C`!SvTRUE(sv)\*(C'\fR instead.
21689 .RS 4
21690 .Sp
21691 .Vb 1
21692 \& bool BOOL_INTERNALS_sv_isbool_false(SV* sv)
21693 .Ve
21694 .RE
21695 .RS 4
21696 .RE
21697 .ie n .IP """BOOL_INTERNALS_sv_isbool_true""" 4
21698 .el .IP \f(CWBOOL_INTERNALS_sv_isbool_true\fR 4
21699 .IX Xref "BOOL_INTERNALS_sv_isbool_true"
21700 .IX Item "BOOL_INTERNALS_sv_isbool_true"
21701 Checks if a \f(CWSvBoolFlagsOK()\fR sv is a true bool. \fBNote\fR that it is
21702 the caller's responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR
21703 before calling this. This is only useful in specialized logic like
21704 serialization code where performance is critical and the flags have
21705 already been checked to be correct. This is \fBNOT\fR what you should use
21706 to check if an SV is "true", for that you should be using
21707 \&\f(CWSvTRUE(sv)\fR instead.
21708 .RS 4
21709 .Sp
21710 .Vb 1
21711 \& bool BOOL_INTERNALS_sv_isbool_true(SV* sv)
21712 .Ve
21713 .RE
21714 .RS 4
21715 .RE
21716 .ie n .IP """boolSV""" 4
21717 .el .IP \f(CWboolSV\fR 4
21718 .IX Xref "boolSV"
21719 .IX Item "boolSV"
21720 Returns a true SV if \f(CW\*(C`b\*(C'\fR is a true value, or a false SV if \f(CW\*(C`b\*(C'\fR is 0.
21721 .Sp
21722 See also \f(CW"PL_sv_yes"\fR and \f(CW"PL_sv_no"\fR.
21723 .RS 4
21724 .Sp
21725 .Vb 1
21726 \& SV * boolSV(bool b)
21727 .Ve
21728 .RE
21729 .RS 4
21730 .RE
21731 .ie n .IP """croak_xs_usage""" 4
21732 .el .IP \f(CWcroak_xs_usage\fR 4
21733 .IX Xref "croak_xs_usage"
21734 .IX Item "croak_xs_usage"
21735 A specialised variant of \f(CWcroak()\fR for emitting the usage message for xsubs
21736 .Sp
21737 .Vb 1
21738 \& croak_xs_usage(cv, "eee_yow");
21739 .Ve
21740 .Sp
21741 works out the package name and subroutine name from \f(CW\*(C`cv\*(C'\fR, and then calls
21742 \&\f(CWcroak()\fR. Hence if \f(CW\*(C`cv\*(C'\fR is \f(CW&ouch::awk\fR, it would call \f(CW\*(C`croak\*(C'\fR as:
21743 .Sp
21744 .Vb 3
21745 \& diag_listed_as: SKIPME
21746 \& Perl_croak(aTHX_ "Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
21747 \& "eee_yow");
21748 .Ve
21749 .RS 4
21750 .Sp
21751 .Vb 2
21752 \& void croak_xs_usage(const CV * const cv,
21753 \& const char * const params)
21754 .Ve
21755 .RE
21756 .RS 4
21757 .RE
21758 .ie n .IP """DEFSV""" 4
21759 .el .IP \f(CWDEFSV\fR 4
21760 .IX Xref "DEFSV"
21761 .IX Item "DEFSV"
21762 Returns the SV associated with \f(CW$_\fR
21763 .RS 4
21764 .Sp
21765 .Vb 1
21766 \& SV * DEFSV
21767 .Ve
21768 .RE
21769 .RS 4
21770 .RE
21771 .ie n .IP """DEFSV_set""" 4
21772 .el .IP \f(CWDEFSV_set\fR 4
21773 .IX Xref "DEFSV_set"
21774 .IX Item "DEFSV_set"
21775 Associate \f(CW\*(C`sv\*(C'\fR with \f(CW$_\fR
21776 .RS 4
21777 .Sp
21778 .Vb 1
21779 \& void DEFSV_set(SV * sv)
21780 .Ve
21781 .RE
21782 .RS 4
21783 .RE
21784 .ie n .IP """get_sv""" 4
21785 .el .IP \f(CWget_sv\fR 4
21786 .IX Xref "get_sv"
21787 .IX Item "get_sv"
21788 Returns the SV of the specified Perl scalar. \f(CW\*(C`flags\*(C'\fR are passed to
21789 "\f(CW\*(C`gv_fetchpv\*(C'\fR". If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
21790 Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero
21791 and the variable does not exist then NULL is returned.
21792 .Sp
21793 NOTE: the \f(CWperl_get_sv()\fR form is \fBdeprecated\fR.
21794 .RS 4
21795 .Sp
21796 .Vb 1
21797 \& SV * get_sv(const char *name, I32 flags)
21798 .Ve
21799 .RE
21800 .RS 4
21801 .RE
21802 .ie n .IP """isGV_with_GP""" 4
21803 .el .IP \f(CWisGV_with_GP\fR 4
21804 .IX Xref "isGV_with_GP"
21805 .IX Item "isGV_with_GP"
21806 Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR is a GV with a pointer to a GP
21807 (glob pointer).
21808 .RS 4
21809 .Sp
21810 .Vb 1
21811 \& bool isGV_with_GP(SV * sv)
21812 .Ve
21813 .RE
21814 .RS 4
21815 .RE
21816 .ie n .IP """looks_like_number""" 4
21817 .el .IP \f(CWlooks_like_number\fR 4
21818 .IX Xref "looks_like_number"
21819 .IX Item "looks_like_number"
21820 Test if the content of an SV looks like a number (or is a number).
21821 \&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Infinity\*(C'\fR are treated as numbers (so will not issue a
21822 non-numeric warning), even if your \f(CWatof()\fR doesn't grok them. Get-magic is
21823 ignored.
21824 .RS 4
21825 .Sp
21826 .Vb 1
21827 \& I32 looks_like_number(SV * const sv)
21828 .Ve
21829 .RE
21830 .RS 4
21831 .RE
21832 .ie n .IP """MUTABLE_AV""" 4
21833 .el .IP \f(CWMUTABLE_AV\fR 4
21834 .IX Item "MUTABLE_AV"
21835 .PD 0
21836 .ie n .IP """MUTABLE_CV""" 4
21837 .el .IP \f(CWMUTABLE_CV\fR 4
21838 .IX Item "MUTABLE_CV"
21839 .ie n .IP """MUTABLE_GV""" 4
21840 .el .IP \f(CWMUTABLE_GV\fR 4
21841 .IX Item "MUTABLE_GV"
21842 .ie n .IP """MUTABLE_HV""" 4
21843 .el .IP \f(CWMUTABLE_HV\fR 4
21844 .IX Item "MUTABLE_HV"
21845 .ie n .IP """MUTABLE_IO""" 4
21846 .el .IP \f(CWMUTABLE_IO\fR 4
21847 .IX Item "MUTABLE_IO"
21848 .ie n .IP """MUTABLE_PTR""" 4
21849 .el .IP \f(CWMUTABLE_PTR\fR 4
21850 .IX Item "MUTABLE_PTR"
21851 .ie n .IP """MUTABLE_SV""" 4
21852 .el .IP \f(CWMUTABLE_SV\fR 4
21853 .IX Xref "MUTABLE_AV MUTABLE_CV MUTABLE_GV MUTABLE_HV MUTABLE_IO MUTABLE_PTR MUTABLE_SV"
21854 .IX Item "MUTABLE_SV"
21855 .PD
21856 The \f(CW\*(C`MUTABLE_\fR\f(CI*\fR\f(CW\*(C'\fR() macros cast pointers to the types shown, in such a way
21857 (compiler permitting) that casting away const-ness will give a warning;
21858 e.g.:
21859 .Sp
21860 .Vb 4
21861 \& const SV *sv = ...;
21862 \& AV *av1 = (AV*)sv; <== BAD: the const has been silently
21863 \& cast away
21864 \& AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
21865 .Ve
21866 .Sp
21867 \&\f(CW\*(C`MUTABLE_PTR\*(C'\fR is the base macro used to derive new casts. The other
21868 already-built-in ones return pointers to what their names indicate.
21869 .RS 4
21870 .Sp
21871 .Vb 7
21872 \& AV * MUTABLE_AV (AV * p)
21873 \& CV * MUTABLE_CV (CV * p)
21874 \& GV * MUTABLE_GV (GV * p)
21875 \& HV * MUTABLE_HV (HV * p)
21876 \& IO * MUTABLE_IO (IO * p)
21877 \& void * MUTABLE_PTR(void * p)
21878 \& SV * MUTABLE_SV (SV * p)
21879 .Ve
21880 .RE
21881 .RS 4
21882 .RE
21883 .ie n .IP """newRV""" 4
21884 .el .IP \f(CWnewRV\fR 4
21885 .IX Item "newRV"
21886 .PD 0
21887 .ie n .IP """newRV_inc""" 4
21888 .el .IP \f(CWnewRV_inc\fR 4
21889 .IX Xref "newRV newRV_inc"
21890 .IX Item "newRV_inc"
21891 .PD
21892 These are identical. They create an RV wrapper for an SV. The reference count
21893 for the original SV is incremented.
21894 .RS 4
21895 .Sp
21896 .Vb 1
21897 \& SV * newRV(SV * const sv)
21898 .Ve
21899 .RE
21900 .RS 4
21901 .RE
21902 .ie n .IP """newRV_noinc""" 4
21903 .el .IP \f(CWnewRV_noinc\fR 4
21904 .IX Xref "newRV_noinc"
21905 .IX Item "newRV_noinc"
21906 Creates an RV wrapper for an SV. The reference count for the original
21907 SV is \fBnot\fR incremented.
21908 .RS 4
21909 .Sp
21910 .Vb 1
21911 \& SV * newRV_noinc(SV * const tmpRef)
21912 .Ve
21913 .RE
21914 .RS 4
21915 .RE
21916 .ie n .IP """newSV""" 4
21917 .el .IP \f(CWnewSV\fR 4
21918 .IX Xref "newSV"
21919 .IX Item "newSV"
21920 Creates a new SV. A non-zero \f(CW\*(C`len\*(C'\fR parameter indicates the number of
21921 bytes of preallocated string space the SV should have. An extra byte for a
21922 trailing \f(CW\*(C`NUL\*(C'\fR is also reserved. (\f(CW\*(C`SvPOK\*(C'\fR is not set for the SV even if string
21923 space is allocated.) The reference count for the new SV is set to 1.
21924 .Sp
21925 In 5.9.3, \f(CWnewSV()\fR replaces the older \f(CWNEWSV()\fR API, and drops the first
21926 parameter, \fIx\fR, a debug aid which allowed callers to identify themselves.
21927 This aid has been superseded by a new build option, \f(CW\*(C`PERL_MEM_LOG\*(C'\fR (see
21928 "PERL_MEM_LOG" in perlhacktips). The older API is still there for use in XS
21929 modules supporting older perls.
21930 .RS 4
21931 .Sp
21932 .Vb 1
21933 \& SV * newSV(const STRLEN len)
21934 .Ve
21935 .RE
21936 .RS 4
21937 .RE
21938 .ie n .IP """newSVbool""" 4
21939 .el .IP \f(CWnewSVbool\fR 4
21940 .IX Xref "newSVbool"
21941 .IX Item "newSVbool"
21942 Creates a new SV boolean.
21943 .RS 4
21944 .Sp
21945 .Vb 1
21946 \& SV * newSVbool(const bool bool_val)
21947 .Ve
21948 .RE
21949 .RS 4
21950 .RE
21951 .ie n .IP """newSV_false""" 4
21952 .el .IP \f(CWnewSV_false\fR 4
21953 .IX Xref "newSV_false"
21954 .IX Item "newSV_false"
21955 Creates a new SV that is a boolean false.
21956 .RS 4
21957 .Sp
21958 .Vb 1
21959 \& SV * newSV_false()
21960 .Ve
21961 .RE
21962 .RS 4
21963 .RE
21964 .ie n .IP """newSVhek""" 4
21965 .el .IP \f(CWnewSVhek\fR 4
21966 .IX Xref "newSVhek"
21967 .IX Item "newSVhek"
21968 Creates a new SV from the hash key structure. It will generate scalars that
21969 point to the shared string table where possible. Returns a new (undefined)
21970 SV if \f(CW\*(C`hek\*(C'\fR is NULL.
21971 .RS 4
21972 .Sp
21973 .Vb 1
21974 \& SV * newSVhek(const HEK * const hek)
21975 .Ve
21976 .RE
21977 .RS 4
21978 .RE
21979 .ie n .IP """newSVhek_mortal""" 4
21980 .el .IP \f(CWnewSVhek_mortal\fR 4
21981 .IX Xref "newSVhek_mortal"
21982 .IX Item "newSVhek_mortal"
21983 Creates a new mortal SV from the hash key structure. It will generate
21984 scalars that point to the shared string table where possible. Returns
21985 a new (undefined) SV if \f(CW\*(C`hek\*(C'\fR is NULL.
21986 .Sp
21987 This is more efficient than using sv_2mortal(newSVhek( ... ))
21988 .RS 4
21989 .Sp
21990 .Vb 1
21991 \& SV * newSVhek_mortal(const HEK * const hek)
21992 .Ve
21993 .RE
21994 .RS 4
21995 .RE
21996 .ie n .IP """newSViv""" 4
21997 .el .IP \f(CWnewSViv\fR 4
21998 .IX Xref "newSViv"
21999 .IX Item "newSViv"
22000 Creates a new SV and copies an integer into it. The reference count for the
22001 SV is set to 1.
22002 .RS 4
22003 .Sp
22004 .Vb 1
22005 \& SV * newSViv(const IV i)
22006 .Ve
22007 .RE
22008 .RS 4
22009 .RE
22010 .ie n .IP """newSVnv""" 4
22011 .el .IP \f(CWnewSVnv\fR 4
22012 .IX Xref "newSVnv"
22013 .IX Item "newSVnv"
22014 Creates a new SV and copies a floating point value into it.
22015 The reference count for the SV is set to 1.
22016 .RS 4
22017 .Sp
22018 .Vb 1
22019 \& SV * newSVnv(const NV n)
22020 .Ve
22021 .RE
22022 .RS 4
22023 .RE
22024 .ie n .IP """newSVpadname""" 4
22025 .el .IP \f(CWnewSVpadname\fR 4
22026 .IX Xref "newSVpadname"
22027 .IX Item "newSVpadname"
22028 NOTE: \f(CW\*(C`newSVpadname\*(C'\fR is \fBexperimental\fR and may change or be
22029 removed without notice.
22030 .Sp
22031 Creates a new SV containing the pad name.
22032 .RS 4
22033 .Sp
22034 .Vb 1
22035 \& SV* newSVpadname(PADNAME *pn)
22036 .Ve
22037 .RE
22038 .RS 4
22039 .RE
22040 .ie n .IP """newSVpv""" 4
22041 .el .IP \f(CWnewSVpv\fR 4
22042 .IX Xref "newSVpv"
22043 .IX Item "newSVpv"
22044 Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
22045 characters) into it. The reference count for the
22046 SV is set to 1. If \f(CW\*(C`len\*(C'\fR is zero, Perl will compute the length using
22047 \&\f(CWstrlen()\fR, (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded
22048 \&\f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte).
22049 .Sp
22050 This function can cause reliability issues if you are likely to pass in
22051 empty strings that are not null terminated, because it will run
22052 strlen on the string and potentially run past valid memory.
22053 .Sp
22054 Using "newSVpvn" is a safer alternative for non \f(CW\*(C`NUL\*(C'\fR terminated strings.
22055 For string literals use "newSVpvs" instead. This function will work fine for
22056 \&\f(CW\*(C`NUL\*(C'\fR terminated strings, but if you want to avoid the if statement on whether
22057 to call \f(CW\*(C`strlen\*(C'\fR use \f(CW\*(C`newSVpvn\*(C'\fR instead (calling \f(CW\*(C`strlen\*(C'\fR yourself).
22058 .RS 4
22059 .Sp
22060 .Vb 1
22061 \& SV * newSVpv(const char * const s, const STRLEN len)
22062 .Ve
22063 .RE
22064 .RS 4
22065 .RE
22066 .ie n .IP """newSVpvf""" 4
22067 .el .IP \f(CWnewSVpvf\fR 4
22068 .IX Xref "newSVpvf"
22069 .IX Item "newSVpvf"
22070 Creates a new SV and initializes it with the string formatted like
22071 \&\f(CW\*(C`sv_catpvf\*(C'\fR.
22072 .Sp
22073 NOTE: \f(CW\*(C`newSVpvf\*(C'\fR must be explicitly called as
22074 \&\f(CW\*(C`Perl_newSVpvf\*(C'\fR
22075 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
22076 .RS 4
22077 .Sp
22078 .Vb 1
22079 \& SV * Perl_newSVpvf(pTHX_ const char * const pat, ...)
22080 .Ve
22081 .RE
22082 .RS 4
22083 .RE
22084 .ie n .IP """newSVpvf_nocontext""" 4
22085 .el .IP \f(CWnewSVpvf_nocontext\fR 4
22086 .IX Xref "newSVpvf_nocontext"
22087 .IX Item "newSVpvf_nocontext"
22088 Like \f(CW"newSVpvf"\fR but does not take a thread context (\f(CW\*(C`aTHX\*(C'\fR) parameter,
22089 so is used in situations where the caller doesn't already have the thread
22090 context.
22091 .RS 4
22092 .Sp
22093 .Vb 1
22094 \& SV * newSVpvf_nocontext(const char * const pat, ...)
22095 .Ve
22096 .RE
22097 .RS 4
22098 .RE
22099 .ie n .IP """newSVpvn""" 4
22100 .el .IP \f(CWnewSVpvn\fR 4
22101 .IX Xref "newSVpvn"
22102 .IX Item "newSVpvn"
22103 Creates a new SV and copies a string into it, which may contain \f(CW\*(C`NUL\*(C'\fR characters
22104 (\f(CW\*(C`\e0\*(C'\fR) and other binary data. The reference count for the SV is set to 1.
22105 Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length (Perl) string. You
22106 are responsible for ensuring that the source buffer is at least
22107 \&\f(CW\*(C`len\*(C'\fR bytes long. If the \f(CW\*(C`buffer\*(C'\fR argument is NULL the new SV will be
22108 undefined.
22109 .RS 4
22110 .Sp
22111 .Vb 1
22112 \& SV * newSVpvn(const char * const buffer, const STRLEN len)
22113 .Ve
22114 .RE
22115 .RS 4
22116 .RE
22117 .ie n .IP """newSVpvn_flags""" 4
22118 .el .IP \f(CWnewSVpvn_flags\fR 4
22119 .IX Xref "newSVpvn_flags"
22120 .IX Item "newSVpvn_flags"
22121 Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
22122 characters) into it. The reference count for the
22123 SV is set to 1. Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length
22124 string. You are responsible for ensuring that the source string is at least
22125 \&\f(CW\*(C`len\*(C'\fR bytes long. If the \f(CW\*(C`s\*(C'\fR argument is NULL the new SV will be undefined.
22126 Currently the only flag bits accepted are \f(CW\*(C`SVf_UTF8\*(C'\fR and \f(CW\*(C`SVs_TEMP\*(C'\fR.
22127 If \f(CW\*(C`SVs_TEMP\*(C'\fR is set, then \f(CWsv_2mortal()\fR is called on the result before
22128 returning. If \f(CW\*(C`SVf_UTF8\*(C'\fR is set, \f(CW\*(C`s\*(C'\fR
22129 is considered to be in UTF\-8 and the
22130 \&\f(CW\*(C`SVf_UTF8\*(C'\fR flag will be set on the new SV.
22131 \&\f(CWnewSVpvn_utf8()\fR is a convenience wrapper for this function, defined as
22132 .Sp
22133 .Vb 2
22134 \& #define newSVpvn_utf8(s, len, u) \e
22135 \& newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
22136 .Ve
22137 .RS 4
22138 .Sp
22139 .Vb 2
22140 \& SV * newSVpvn_flags(const char * const s, const STRLEN len,
22141 \& const U32 flags)
22142 .Ve
22143 .RE
22144 .RS 4
22145 .RE
22146 .ie n .IP """newSVpvn_share""" 4
22147 .el .IP \f(CWnewSVpvn_share\fR 4
22148 .IX Xref "newSVpvn_share"
22149 .IX Item "newSVpvn_share"
22150 Creates a new SV with its \f(CW\*(C`SvPVX_const\*(C'\fR pointing to a shared string in the string
22151 table. If the string does not already exist in the table, it is
22152 created first. Turns on the \f(CW\*(C`SvIsCOW\*(C'\fR flag (or \f(CW\*(C`READONLY\*(C'\fR
22153 and \f(CW\*(C`FAKE\*(C'\fR in 5.16 and earlier). If the \f(CW\*(C`hash\*(C'\fR parameter
22154 is non-zero, that value is used; otherwise the hash is computed.
22155 The string's hash can later be retrieved from the SV
22156 with the \f(CW"SvSHARED_HASH"\fR macro. The idea here is
22157 that as the string table is used for shared hash keys these strings will have
22158 \&\f(CW\*(C`SvPVX_const == HeKEY\*(C'\fR and hash lookup will avoid string compare.
22159 .RS 4
22160 .Sp
22161 .Vb 1
22162 \& SV * newSVpvn_share(const char *s, I32 len, U32 hash)
22163 .Ve
22164 .RE
22165 .RS 4
22166 .RE
22167 .ie n .IP """newSVpvn_utf8""" 4
22168 .el .IP \f(CWnewSVpvn_utf8\fR 4
22169 .IX Xref "newSVpvn_utf8"
22170 .IX Item "newSVpvn_utf8"
22171 Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
22172 characters) into it. If \f(CW\*(C`utf8\*(C'\fR is true, calls
22173 \&\f(CW\*(C`SvUTF8_on\*(C'\fR on the new SV. Implemented as a wrapper around \f(CW\*(C`newSVpvn_flags\*(C'\fR.
22174 .RS 4
22175 .Sp
22176 .Vb 1
22177 \& SV* newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
22178 .Ve
22179 .RE
22180 .RS 4
22181 .RE
22182 .ie n .IP """newSVpvs""" 4
22183 .el .IP \f(CWnewSVpvs\fR 4
22184 .IX Xref "newSVpvs"
22185 .IX Item "newSVpvs"
22186 Like \f(CW\*(C`newSVpvn\*(C'\fR, but takes a literal string instead of a
22187 string/length pair.
22188 .RS 4
22189 .Sp
22190 .Vb 1
22191 \& SV* newSVpvs("literal string")
22192 .Ve
22193 .RE
22194 .RS 4
22195 .RE
22196 .ie n .IP """newSVpvs_flags""" 4
22197 .el .IP \f(CWnewSVpvs_flags\fR 4
22198 .IX Xref "newSVpvs_flags"
22199 .IX Item "newSVpvs_flags"
22200 Like \f(CW\*(C`newSVpvn_flags\*(C'\fR, but takes a literal string instead of
22201 a string/length pair.
22202 .RS 4
22203 .Sp
22204 .Vb 1
22205 \& SV* newSVpvs_flags("literal string", U32 flags)
22206 .Ve
22207 .RE
22208 .RS 4
22209 .RE
22210 .ie n .IP """newSVpv_share""" 4
22211 .el .IP \f(CWnewSVpv_share\fR 4
22212 .IX Xref "newSVpv_share"
22213 .IX Item "newSVpv_share"
22214 Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a \f(CW\*(C`NUL\*(C'\fR\-terminated string instead of a
22215 string/length pair.
22216 .RS 4
22217 .Sp
22218 .Vb 1
22219 \& SV * newSVpv_share(const char *s, U32 hash)
22220 .Ve
22221 .RE
22222 .RS 4
22223 .RE
22224 .ie n .IP """newSVpvs_share""" 4
22225 .el .IP \f(CWnewSVpvs_share\fR 4
22226 .IX Xref "newSVpvs_share"
22227 .IX Item "newSVpvs_share"
22228 Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a literal string instead of
22229 a string/length pair and omits the hash parameter.
22230 .RS 4
22231 .Sp
22232 .Vb 1
22233 \& SV* newSVpvs_share("literal string")
22234 .Ve
22235 .RE
22236 .RS 4
22237 .RE
22238 .ie n .IP """newSVrv""" 4
22239 .el .IP \f(CWnewSVrv\fR 4
22240 .IX Xref "newSVrv"
22241 .IX Item "newSVrv"
22242 Creates a new SV for the existing RV, \f(CW\*(C`rv\*(C'\fR, to point to. If \f(CW\*(C`rv\*(C'\fR is not an
22243 RV then it will be upgraded to one. If \f(CW\*(C`classname\*(C'\fR is non-null then the new
22244 SV will be blessed in the specified package. The new SV is returned and its
22245 reference count is 1. The reference count 1 is owned by \f(CW\*(C`rv\*(C'\fR. See also
22246 \&\fBnewRV_inc()\fR and \fBnewRV_noinc()\fR for creating a new RV properly.
22247 .RS 4
22248 .Sp
22249 .Vb 1
22250 \& SV * newSVrv(SV * const rv, const char * const classname)
22251 .Ve
22252 .RE
22253 .RS 4
22254 .RE
22255 .ie n .IP """newSVsv""" 4
22256 .el .IP \f(CWnewSVsv\fR 4
22257 .IX Item "newSVsv"
22258 .PD 0
22259 .ie n .IP """newSVsv_flags""" 4
22260 .el .IP \f(CWnewSVsv_flags\fR 4
22261 .IX Item "newSVsv_flags"
22262 .ie n .IP """newSVsv_nomg""" 4
22263 .el .IP \f(CWnewSVsv_nomg\fR 4
22264 .IX Xref "newSVsv newSVsv_flags newSVsv_nomg"
22265 .IX Item "newSVsv_nomg"
22266 .PD
22267 These create a new SV which is an exact duplicate of the original SV
22268 (using \f(CW\*(C`sv_setsv\*(C'\fR.)
22269 .Sp
22270 They differ only in that \f(CW\*(C`newSVsv\*(C'\fR performs 'get' magic; \f(CW\*(C`newSVsv_nomg\*(C'\fR skips
22271 any magic; and \f(CW\*(C`newSVsv_flags\*(C'\fR allows you to explicitly set a \f(CW\*(C`flags\*(C'\fR
22272 parameter.
22273 .RS 4
22274 .Sp
22275 .Vb 3
22276 \& SV * newSVsv (SV * const old)
22277 \& SV * newSVsv_flags(SV * const old, I32 flags)
22278 \& SV * newSVsv_nomg (SV * const old)
22279 .Ve
22280 .RE
22281 .RS 4
22282 .RE
22283 .ie n .IP """newSV_true""" 4
22284 .el .IP \f(CWnewSV_true\fR 4
22285 .IX Xref "newSV_true"
22286 .IX Item "newSV_true"
22287 Creates a new SV that is a boolean true.
22288 .RS 4
22289 .Sp
22290 .Vb 1
22291 \& SV * newSV_true()
22292 .Ve
22293 .RE
22294 .RS 4
22295 .RE
22296 .ie n .IP """newSV_type""" 4
22297 .el .IP \f(CWnewSV_type\fR 4
22298 .IX Xref "newSV_type"
22299 .IX Item "newSV_type"
22300 Creates a new SV, of the type specified. The reference count for the new SV
22301 is set to 1.
22302 .RS 4
22303 .Sp
22304 .Vb 1
22305 \& SV * newSV_type(const svtype type)
22306 .Ve
22307 .RE
22308 .RS 4
22309 .RE
22310 .ie n .IP """newSV_type_mortal""" 4
22311 .el .IP \f(CWnewSV_type_mortal\fR 4
22312 .IX Xref "newSV_type_mortal"
22313 .IX Item "newSV_type_mortal"
22314 Creates a new mortal SV, of the type specified. The reference count for the
22315 new SV is set to 1.
22316 .Sp
22317 This is equivalent to
22318 SV* sv = sv_2mortal(newSV_type(<some type>))
22319 and
22320 SV* sv = \fBsv_newmortal()\fR;
22321 sv_upgrade(sv, <some_type>)
22322 but should be more efficient than both of them. (Unless sv_2mortal is inlined
22323 at some point in the future.)
22324 .RS 4
22325 .Sp
22326 .Vb 1
22327 \& SV * newSV_type_mortal(const svtype type)
22328 .Ve
22329 .RE
22330 .RS 4
22331 .RE
22332 .ie n .IP """newSVuv""" 4
22333 .el .IP \f(CWnewSVuv\fR 4
22334 .IX Xref "newSVuv"
22335 .IX Item "newSVuv"
22336 Creates a new SV and copies an unsigned integer into it.
22337 The reference count for the SV is set to 1.
22338 .RS 4
22339 .Sp
22340 .Vb 1
22341 \& SV * newSVuv(const UV u)
22342 .Ve
22343 .RE
22344 .RS 4
22345 .RE
22346 .ie n .IP """Nullsv""" 4
22347 .el .IP \f(CWNullsv\fR 4
22348 .IX Xref "Nullsv"
22349 .IX Item "Nullsv"
22350 Null SV pointer. (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is defined.)
22351 .ie n .IP """PL_sv_no""" 4
22352 .el .IP \f(CWPL_sv_no\fR 4
22353 .IX Xref "PL_sv_no"
22354 .IX Item "PL_sv_no"
22355 This is the \f(CW\*(C`false\*(C'\fR SV. It is readonly. See \f(CW"PL_sv_yes"\fR. Always refer
22356 to this as \f(CW&PL_sv_no\fR.
22357 .RS 4
22358 .Sp
22359 .Vb 1
22360 \& SV PL_sv_no
22361 .Ve
22362 .RE
22363 .RS 4
22364 .RE
22365 .ie n .IP """PL_sv_undef""" 4
22366 .el .IP \f(CWPL_sv_undef\fR 4
22367 .IX Xref "PL_sv_undef"
22368 .IX Item "PL_sv_undef"
22369 This is the \f(CW\*(C`undef\*(C'\fR SV. It is readonly. Always refer to this as
22370 \&\f(CW&PL_sv_undef\fR.
22371 .RS 4
22372 .Sp
22373 .Vb 1
22374 \& SV PL_sv_undef
22375 .Ve
22376 .RE
22377 .RS 4
22378 .RE
22379 .ie n .IP """PL_sv_yes""" 4
22380 .el .IP \f(CWPL_sv_yes\fR 4
22381 .IX Xref "PL_sv_yes"
22382 .IX Item "PL_sv_yes"
22383 This is the \f(CW\*(C`true\*(C'\fR SV. It is readonly. See \f(CW"PL_sv_no"\fR. Always refer to
22384 this as \f(CW&PL_sv_yes\fR.
22385 .RS 4
22386 .Sp
22387 .Vb 1
22388 \& SV PL_sv_yes
22389 .Ve
22390 .RE
22391 .RS 4
22392 .RE
22393 .ie n .IP """PL_sv_zero""" 4
22394 .el .IP \f(CWPL_sv_zero\fR 4
22395 .IX Xref "PL_sv_zero"
22396 .IX Item "PL_sv_zero"
22397 This readonly SV has a zero numeric value and a \f(CW"0"\fR string value. It's
22398 similar to \f(CW"PL_sv_no"\fR except for its string value. Can be used as a
22399 cheap alternative to \f(CWmXPUSHi(0)\fR for example. Always refer to this as
22400 \&\f(CW&PL_sv_zero\fR. Introduced in 5.28.
22401 .RS 4
22402 .Sp
22403 .Vb 1
22404 \& SV PL_sv_zero
22405 .Ve
22406 .RE
22407 .RS 4
22408 .RE
22409 .ie n .IP """SAVE_DEFSV""" 4
22410 .el .IP \f(CWSAVE_DEFSV\fR 4
22411 .IX Xref "SAVE_DEFSV"
22412 .IX Item "SAVE_DEFSV"
22413 Localize \f(CW$_\fR. See "Localizing changes" in perlguts.
22414 .RS 4
22415 .Sp
22416 .Vb 1
22417 \& void SAVE_DEFSV
22418 .Ve
22419 .RE
22420 .RS 4
22421 .RE
22422 .ie n .IP """sortsv""" 4
22423 .el .IP \f(CWsortsv\fR 4
22424 .IX Xref "sortsv"
22425 .IX Item "sortsv"
22426 In-place sort an array of SV pointers with the given comparison routine.
22427 .Sp
22428 Currently this always uses mergesort. See \f(CW"sortsv_flags"\fR for a more
22429 flexible routine.
22430 .RS 4
22431 .Sp
22432 .Vb 1
22433 \& void sortsv(SV **array, size_t num_elts, SVCOMPARE_t cmp)
22434 .Ve
22435 .RE
22436 .RS 4
22437 .RE
22438 .ie n .IP """sortsv_flags""" 4
22439 .el .IP \f(CWsortsv_flags\fR 4
22440 .IX Xref "sortsv_flags"
22441 .IX Item "sortsv_flags"
22442 In-place sort an array of SV pointers with the given comparison routine,
22443 with various SORTf_* flag options.
22444 .RS 4
22445 .Sp
22446 .Vb 2
22447 \& void sortsv_flags(SV **array, size_t num_elts, SVCOMPARE_t cmp,
22448 \& U32 flags)
22449 .Ve
22450 .RE
22451 .RS 4
22452 .RE
22453 .ie n .IP """SV""" 4
22454 .el .IP \f(CWSV\fR 4
22455 .IX Item "SV"
22456 Described in perlguts.
22457 .ie n .IP """SvAMAGIC""" 4
22458 .el .IP \f(CWSvAMAGIC\fR 4
22459 .IX Xref "SvAMAGIC"
22460 .IX Item "SvAMAGIC"
22461 Returns a boolean as to whether \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled or
22462 not.
22463 .RS 4
22464 .Sp
22465 .Vb 1
22466 \& bool SvAMAGIC(SV * sv)
22467 .Ve
22468 .RE
22469 .RS 4
22470 .RE
22471 .ie n .IP """SvAMAGIC_off""" 4
22472 .el .IP \f(CWSvAMAGIC_off\fR 4
22473 .IX Xref "SvAMAGIC_off"
22474 .IX Item "SvAMAGIC_off"
22475 Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) disabled.
22476 .RS 4
22477 .Sp
22478 .Vb 1
22479 \& void SvAMAGIC_off(SV *sv)
22480 .Ve
22481 .RE
22482 .RS 4
22483 .RE
22484 .ie n .IP """SvAMAGIC_on""" 4
22485 .el .IP \f(CWSvAMAGIC_on\fR 4
22486 .IX Xref "SvAMAGIC_on"
22487 .IX Item "SvAMAGIC_on"
22488 Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled.
22489 .RS 4
22490 .Sp
22491 .Vb 1
22492 \& void SvAMAGIC_on(SV *sv)
22493 .Ve
22494 .RE
22495 .RS 4
22496 .RE
22497 .ie n .IP """sv_backoff""" 4
22498 .el .IP \f(CWsv_backoff\fR 4
22499 .IX Xref "sv_backoff"
22500 .IX Item "sv_backoff"
22501 Remove any string offset. You should normally use the \f(CW\*(C`SvOOK_off\*(C'\fR macro
22502 wrapper instead.
22503 .RS 4
22504 .Sp
22505 .Vb 1
22506 \& void sv_backoff(SV * const sv)
22507 .Ve
22508 .RE
22509 .RS 4
22510 .RE
22511 .ie n .IP """sv_bless""" 4
22512 .el .IP \f(CWsv_bless\fR 4
22513 .IX Xref "sv_bless"
22514 .IX Item "sv_bless"
22515 Blesses an SV into a specified package. The SV must be an RV. The package
22516 must be designated by its stash (see \f(CW"gv_stashpv"\fR). The reference count
22517 of the SV is unaffected.
22518 .RS 4
22519 .Sp
22520 .Vb 1
22521 \& SV * sv_bless(SV * const sv, HV * const stash)
22522 .Ve
22523 .RE
22524 .RS 4
22525 .RE
22526 .ie n .IP """SvBoolFlagsOK""" 4
22527 .el .IP \f(CWSvBoolFlagsOK\fR 4
22528 .IX Xref "SvBoolFlagsOK"
22529 .IX Item "SvBoolFlagsOK"
22530 Returns a bool indicating whether the SV has the right flags set such
22531 that it is safe to call \f(CWBOOL_INTERNALS_sv_isbool()\fR or
22532 \&\f(CWBOOL_INTERNALS_sv_isbool_true()\fR or
22533 \&\f(CWBOOL_INTERNALS_sv_isbool_false()\fR. Currently equivalent to
22534 \&\f(CWSvIandPOK(sv)\fR or \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR. Serialization may want to
22535 unroll this check. If so you are strongly recommended to add code like
22536 \&\f(CW\*(C`assert(SvBoolFlagsOK(sv));\*(C'\fR \fBbefore\fR calling using any of the
22537 BOOL_INTERNALS macros.
22538 .RS 4
22539 .Sp
22540 .Vb 1
22541 \& U32 SvBoolFlagsOK(SV* sv)
22542 .Ve
22543 .RE
22544 .RS 4
22545 .RE
22546 .ie n .IP """sv_catpv""" 4
22547 .el .IP \f(CWsv_catpv\fR 4
22548 .IX Item "sv_catpv"
22549 .PD 0
22550 .ie n .IP """sv_catpv_flags""" 4
22551 .el .IP \f(CWsv_catpv_flags\fR 4
22552 .IX Item "sv_catpv_flags"
22553 .ie n .IP """sv_catpv_mg""" 4
22554 .el .IP \f(CWsv_catpv_mg\fR 4
22555 .IX Item "sv_catpv_mg"
22556 .ie n .IP """sv_catpv_nomg""" 4
22557 .el .IP \f(CWsv_catpv_nomg\fR 4
22558 .IX Xref "sv_catpv sv_catpv_flags sv_catpv_mg sv_catpv_nomg"
22559 .IX Item "sv_catpv_nomg"
22560 .PD
22561 These concatenate the \f(CW\*(C`NUL\*(C'\fR\-terminated string \f(CW\*(C`sstr\*(C'\fR onto the end of the
22562 string which is in the SV.
22563 If the SV has the UTF\-8 status set, then the bytes appended should be
22564 valid UTF\-8.
22565 .Sp
22566 They differ only in how they handle magic:
22567 .Sp
22568 \&\f(CW\*(C`sv_catpv_mg\*(C'\fR performs both 'get' and 'set' magic.
22569 .Sp
22570 \&\f(CW\*(C`sv_catpv\*(C'\fR performs only 'get' magic.
22571 .Sp
22572 \&\f(CW\*(C`sv_catpv_nomg\*(C'\fR skips all magic.
22573 .Sp
22574 \&\f(CW\*(C`sv_catpv_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to specify
22575 any combination of magic handling (using \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR), and
22576 to also override the UTF\-8 handling. By supplying the \f(CW\*(C`SV_CATUTF8\*(C'\fR flag, the
22577 appended string is forced to be interpreted as UTF\-8; by supplying instead the
22578 \&\f(CW\*(C`SV_CATBYTES\*(C'\fR flag, it will be interpreted as just bytes. Either the SV or
22579 the string appended will be upgraded to UTF\-8 if necessary.
22580 .RS 4
22581 .Sp
22582 .Vb 4
22583 \& void sv_catpv (SV * const dsv, const char *sstr)
22584 \& void sv_catpv_flags(SV *dsv, const char *sstr, const I32 flags)
22585 \& void sv_catpv_mg (SV * const dsv, const char * const sstr)
22586 \& void sv_catpv_nomg (SV * const dsv, const char *sstr)
22587 .Ve
22588 .RE
22589 .RS 4
22590 .RE
22591 .ie n .IP """sv_catpvf""" 4
22592 .el .IP \f(CWsv_catpvf\fR 4
22593 .IX Item "sv_catpvf"
22594 .PD 0
22595 .ie n .IP """sv_catpvf_mg""" 4
22596 .el .IP \f(CWsv_catpvf_mg\fR 4
22597 .IX Item "sv_catpvf_mg"
22598 .ie n .IP """sv_catpvf_mg_nocontext""" 4
22599 .el .IP \f(CWsv_catpvf_mg_nocontext\fR 4
22600 .IX Item "sv_catpvf_mg_nocontext"
22601 .ie n .IP """sv_catpvf_nocontext""" 4
22602 .el .IP \f(CWsv_catpvf_nocontext\fR 4
22603 .IX Xref "sv_catpvf sv_catpvf_mg sv_catpvf_mg_nocontext sv_catpvf_nocontext"
22604 .IX Item "sv_catpvf_nocontext"
22605 .PD
22606 These process their arguments like \f(CW\*(C`sprintf\*(C'\fR, and append the formatted
22607 output to an SV. As with \f(CW\*(C`sv_vcatpvfn\*(C'\fR, argument reordering is not supporte
22608 when called with a non-null C\-style variable argument list.
22609 .Sp
22610 If the appended data contains "wide" characters
22611 (including, but not limited to, SVs with a UTF\-8 PV formatted with \f(CW%s\fR,
22612 and characters >255 formatted with \f(CW%c\fR), the original SV might get
22613 upgraded to UTF\-8.
22614 .Sp
22615 If the original SV was UTF\-8, the pattern should be
22616 valid UTF\-8; if the original SV was bytes, the pattern should be too.
22617 .Sp
22618 All perform 'get' magic, but only \f(CW\*(C`sv_catpvf_mg\*(C'\fR and \f(CW\*(C`sv_catpvf_mg_nocontext\*(C'\fR
22619 perform 'set' magic.
22620 .Sp
22621 \&\f(CW\*(C`sv_catpvf_nocontext\*(C'\fR and \f(CW\*(C`sv_catpvf_mg_nocontext\*(C'\fR do not take a thread
22622 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller
22623 doesn't already have the thread context.
22624 .Sp
22625 NOTE: \f(CW\*(C`sv_catpvf\*(C'\fR must be explicitly called as
22626 \&\f(CW\*(C`Perl_sv_catpvf\*(C'\fR
22627 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
22628 .Sp
22629 NOTE: \f(CW\*(C`sv_catpvf_mg\*(C'\fR must be explicitly called as
22630 \&\f(CW\*(C`Perl_sv_catpvf_mg\*(C'\fR
22631 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
22632 .RS 4
22633 .Sp
22634 .Vb 8
22635 \& void Perl_sv_catpvf (pTHX_ SV * const sv,
22636 \& const char * const pat, ...)
22637 \& void Perl_sv_catpvf_mg (pTHX_ SV * const sv,
22638 \& const char * const pat, ...)
22639 \& void sv_catpvf_mg_nocontext(SV * const sv,
22640 \& const char * const pat, ...)
22641 \& void sv_catpvf_nocontext (SV * const sv,
22642 \& const char * const pat, ...)
22643 .Ve
22644 .RE
22645 .RS 4
22646 .RE
22647 .ie n .IP """sv_catpvn""" 4
22648 .el .IP \f(CWsv_catpvn\fR 4
22649 .IX Item "sv_catpvn"
22650 .PD 0
22651 .ie n .IP """sv_catpvn_flags""" 4
22652 .el .IP \f(CWsv_catpvn_flags\fR 4
22653 .IX Item "sv_catpvn_flags"
22654 .ie n .IP """sv_catpvn_mg""" 4
22655 .el .IP \f(CWsv_catpvn_mg\fR 4
22656 .IX Item "sv_catpvn_mg"
22657 .ie n .IP """sv_catpvn_nomg""" 4
22658 .el .IP \f(CWsv_catpvn_nomg\fR 4
22659 .IX Xref "sv_catpvn sv_catpvn_flags sv_catpvn_mg sv_catpvn_nomg"
22660 .IX Item "sv_catpvn_nomg"
22661 .PD
22662 These concatenate the \f(CW\*(C`len\*(C'\fR bytes of the string beginning at \f(CW\*(C`ptr\*(C'\fR onto the
22663 end of the string which is in \f(CW\*(C`dsv\*(C'\fR. The caller must make sure \f(CW\*(C`ptr\*(C'\fR
22664 contains at least \f(CW\*(C`len\*(C'\fR bytes.
22665 .Sp
22666 For all but \f(CW\*(C`sv_catpvn_flags\*(C'\fR, the string appended is assumed to be valid
22667 UTF\-8 if the SV has the UTF\-8 status set, and a string of bytes otherwise.
22668 .Sp
22669 They differ in that:
22670 .Sp
22671 \&\f(CW\*(C`sv_catpvn_mg\*(C'\fR performs both 'get' and 'set' magic on \f(CW\*(C`dsv\*(C'\fR.
22672 .Sp
22673 \&\f(CW\*(C`sv_catpvn\*(C'\fR performs only 'get' magic.
22674 .Sp
22675 \&\f(CW\*(C`sv_catpvn_nomg\*(C'\fR skips all magic.
22676 .Sp
22677 \&\f(CW\*(C`sv_catpvn_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to specify
22678 any combination of magic handling (using \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR) and
22679 to also override the UTF\-8 handling. By supplying the \f(CW\*(C`SV_CATBYTES\*(C'\fR flag, the
22680 appended string is interpreted as plain bytes; by supplying instead the
22681 \&\f(CW\*(C`SV_CATUTF8\*(C'\fR flag, it will be interpreted as UTF\-8, and the \f(CW\*(C`dsv\*(C'\fR will be
22682 upgraded to UTF\-8 if necessary.
22683 .Sp
22684 \&\f(CW\*(C`sv_catpvn\*(C'\fR, \f(CW\*(C`sv_catpvn_mg\*(C'\fR, and \f(CW\*(C`sv_catpvn_nomg\*(C'\fR are implemented
22685 in terms of \f(CW\*(C`sv_catpvn_flags\*(C'\fR.
22686 .RS 4
22687 .Sp
22688 .Vb 5
22689 \& void sv_catpvn (SV *dsv, const char *sstr, STRLEN len)
22690 \& void sv_catpvn_flags(SV * const dsv, const char *sstr,
22691 \& const STRLEN len, const I32 flags)
22692 \& void sv_catpvn_mg (SV *dsv, const char *sstr, STRLEN len)
22693 \& void sv_catpvn_nomg (SV *dsv, const char *sstr, STRLEN len)
22694 .Ve
22695 .RE
22696 .RS 4
22697 .RE
22698 .ie n .IP """sv_catpvs""" 4
22699 .el .IP \f(CWsv_catpvs\fR 4
22700 .IX Xref "sv_catpvs"
22701 .IX Item "sv_catpvs"
22702 Like \f(CW\*(C`sv_catpvn\*(C'\fR, but takes a literal string instead of a
22703 string/length pair.
22704 .RS 4
22705 .Sp
22706 .Vb 1
22707 \& void sv_catpvs(SV* sv, "literal string")
22708 .Ve
22709 .RE
22710 .RS 4
22711 .RE
22712 .ie n .IP """sv_catpvs_flags""" 4
22713 .el .IP \f(CWsv_catpvs_flags\fR 4
22714 .IX Xref "sv_catpvs_flags"
22715 .IX Item "sv_catpvs_flags"
22716 Like \f(CW\*(C`sv_catpvn_flags\*(C'\fR, but takes a literal string instead
22717 of a string/length pair.
22718 .RS 4
22719 .Sp
22720 .Vb 1
22721 \& void sv_catpvs_flags(SV* sv, "literal string", I32 flags)
22722 .Ve
22723 .RE
22724 .RS 4
22725 .RE
22726 .ie n .IP """sv_catpvs_mg""" 4
22727 .el .IP \f(CWsv_catpvs_mg\fR 4
22728 .IX Xref "sv_catpvs_mg"
22729 .IX Item "sv_catpvs_mg"
22730 Like \f(CW\*(C`sv_catpvn_mg\*(C'\fR, but takes a literal string instead of a
22731 string/length pair.
22732 .RS 4
22733 .Sp
22734 .Vb 1
22735 \& void sv_catpvs_mg(SV* sv, "literal string")
22736 .Ve
22737 .RE
22738 .RS 4
22739 .RE
22740 .ie n .IP """sv_catpvs_nomg""" 4
22741 .el .IP \f(CWsv_catpvs_nomg\fR 4
22742 .IX Xref "sv_catpvs_nomg"
22743 .IX Item "sv_catpvs_nomg"
22744 Like \f(CW\*(C`sv_catpvn_nomg\*(C'\fR, but takes a literal string instead of
22745 a string/length pair.
22746 .RS 4
22747 .Sp
22748 .Vb 1
22749 \& void sv_catpvs_nomg(SV* sv, "literal string")
22750 .Ve
22751 .RE
22752 .RS 4
22753 .RE
22754 .ie n .IP """sv_catsv""" 4
22755 .el .IP \f(CWsv_catsv\fR 4
22756 .IX Item "sv_catsv"
22757 .PD 0
22758 .ie n .IP """sv_catsv_flags""" 4
22759 .el .IP \f(CWsv_catsv_flags\fR 4
22760 .IX Item "sv_catsv_flags"
22761 .ie n .IP """sv_catsv_mg""" 4
22762 .el .IP \f(CWsv_catsv_mg\fR 4
22763 .IX Item "sv_catsv_mg"
22764 .ie n .IP """sv_catsv_nomg""" 4
22765 .el .IP \f(CWsv_catsv_nomg\fR 4
22766 .IX Xref "sv_catsv sv_catsv_flags sv_catsv_mg sv_catsv_nomg"
22767 .IX Item "sv_catsv_nomg"
22768 .PD
22769 These concatenate the string from SV \f(CW\*(C`sstr\*(C'\fR onto the end of the string in SV
22770 \&\f(CW\*(C`dsv\*(C'\fR. If \f(CW\*(C`sstr\*(C'\fR is null, these are no-ops; otherwise only \f(CW\*(C`dsv\*(C'\fR is
22771 modified.
22772 .Sp
22773 They differ only in what magic they perform:
22774 .Sp
22775 \&\f(CW\*(C`sv_catsv_mg\*(C'\fR performs 'get' magic on both SVs before the copy, and 'set' magic
22776 on \f(CW\*(C`dsv\*(C'\fR afterwards.
22777 .Sp
22778 \&\f(CW\*(C`sv_catsv\*(C'\fR performs just 'get' magic, on both SVs.
22779 .Sp
22780 \&\f(CW\*(C`sv_catsv_nomg\*(C'\fR skips all magic.
22781 .Sp
22782 \&\f(CW\*(C`sv_catsv_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to use
22783 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR to specify any combination of magic handling
22784 (although either both or neither SV will have 'get' magic applied to it.)
22785 .Sp
22786 \&\f(CW\*(C`sv_catsv\*(C'\fR, \f(CW\*(C`sv_catsv_mg\*(C'\fR, and \f(CW\*(C`sv_catsv_nomg\*(C'\fR are implemented
22787 in terms of \f(CW\*(C`sv_catsv_flags\*(C'\fR.
22788 .RS 4
22789 .Sp
22790 .Vb 5
22791 \& void sv_catsv (SV *dsv, SV *sstr)
22792 \& void sv_catsv_flags(SV * const dsv, SV * const sstr,
22793 \& const I32 flags)
22794 \& void sv_catsv_mg (SV *dsv, SV *sstr)
22795 \& void sv_catsv_nomg (SV *dsv, SV *sstr)
22796 .Ve
22797 .RE
22798 .RS 4
22799 .RE
22800 .ie n .IP """SV_CHECK_THINKFIRST""" 4
22801 .el .IP \f(CWSV_CHECK_THINKFIRST\fR 4
22802 .IX Xref "SV_CHECK_THINKFIRST"
22803 .IX Item "SV_CHECK_THINKFIRST"
22804 Remove any encumbrances from \f(CW\*(C`sv\*(C'\fR, that need to be taken care of before it
22805 is modifiable. For example if it is Copy on Write (COW), now is the time to
22806 make that copy.
22807 .Sp
22808 If you know that you are about to change the PV value of \f(CW\*(C`sv\*(C'\fR, instead use
22809 "\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" to avoid the write that would be
22810 immediately written again.
22811 .RS 4
22812 .Sp
22813 .Vb 1
22814 \& void SV_CHECK_THINKFIRST(SV * sv)
22815 .Ve
22816 .RE
22817 .RS 4
22818 .RE
22819 .ie n .IP """SV_CHECK_THINKFIRST_COW_DROP""" 4
22820 .el .IP \f(CWSV_CHECK_THINKFIRST_COW_DROP\fR 4
22821 .IX Xref "SV_CHECK_THINKFIRST_COW_DROP"
22822 .IX Item "SV_CHECK_THINKFIRST_COW_DROP"
22823 Call this when you are about to replace the PV value in \f(CW\*(C`sv\*(C'\fR, which is
22824 potentially copy-on-write. It stops any sharing with other SVs, so that no
22825 Copy on Write (COW) actually happens. This COW would be useless, as it would
22826 immediately get changed to something else. This function also removes any
22827 other encumbrances that would be problematic when changing \f(CW\*(C`sv\*(C'\fR.
22828 .RS 4
22829 .Sp
22830 .Vb 1
22831 \& void SV_CHECK_THINKFIRST_COW_DROP(SV * sv)
22832 .Ve
22833 .RE
22834 .RS 4
22835 .RE
22836 .ie n .IP """sv_chop""" 4
22837 .el .IP \f(CWsv_chop\fR 4
22838 .IX Xref "sv_chop"
22839 .IX Item "sv_chop"
22840 Efficient removal of characters from the beginning of the string buffer.
22841 \&\f(CWSvPOK(sv)\fR, or at least \f(CWSvPOKp(sv)\fR, must be true and \f(CW\*(C`ptr\*(C'\fR must be a
22842 pointer to somewhere inside the string buffer. \f(CW\*(C`ptr\*(C'\fR becomes the first
22843 character of the adjusted string. Uses the \f(CW\*(C`OOK\*(C'\fR hack. On return, only
22844 \&\f(CWSvPOK(sv)\fR and \f(CWSvPOKp(sv)\fR among the \f(CW\*(C`OK\*(C'\fR flags will be true.
22845 .Sp
22846 Beware: after this function returns, \f(CW\*(C`ptr\*(C'\fR and SvPVX_const(sv) may no longer
22847 refer to the same chunk of data.
22848 .Sp
22849 The unfortunate similarity of this function's name to that of Perl's \f(CW\*(C`chop\*(C'\fR
22850 operator is strictly coincidental. This function works from the left;
22851 \&\f(CW\*(C`chop\*(C'\fR works from the right.
22852 .RS 4
22853 .Sp
22854 .Vb 1
22855 \& void sv_chop(SV * const sv, const char * const ptr)
22856 .Ve
22857 .RE
22858 .RS 4
22859 .RE
22860 .ie n .IP """sv_clear""" 4
22861 .el .IP \f(CWsv_clear\fR 4
22862 .IX Xref "sv_clear"
22863 .IX Item "sv_clear"
22864 Clear an SV: call any destructors, free up any memory used by the body,
22865 and free the body itself. The SV's head is \fInot\fR freed, although
22866 its type is set to all 1's so that it won't inadvertently be assumed
22867 to be live during global destruction etc.
22868 This function should only be called when \f(CW\*(C`REFCNT\*(C'\fR is zero. Most of the time
22869 you'll want to call \f(CW\*(C`SvREFCNT_dec\*(C'\fR instead.
22870 .RS 4
22871 .Sp
22872 .Vb 1
22873 \& void sv_clear(SV * const orig_sv)
22874 .Ve
22875 .RE
22876 .RS 4
22877 .RE
22878 .ie n .IP """sv_cmp""" 4
22879 .el .IP \f(CWsv_cmp\fR 4
22880 .IX Xref "sv_cmp"
22881 .IX Item "sv_cmp"
22882 Compares the strings in two SVs. Returns \-1, 0, or 1 indicating whether the
22883 string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in
22884 \&\f(CW\*(C`sv2\*(C'\fR. Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware, handles get magic, and will
22885 coerce its args to strings if necessary. See also \f(CW"sv_cmp_locale"\fR.
22886 .RS 4
22887 .Sp
22888 .Vb 1
22889 \& I32 sv_cmp(SV * const sv1, SV * const sv2)
22890 .Ve
22891 .RE
22892 .RS 4
22893 .RE
22894 .ie n .IP """sv_cmp_flags""" 4
22895 .el .IP \f(CWsv_cmp_flags\fR 4
22896 .IX Xref "sv_cmp_flags"
22897 .IX Item "sv_cmp_flags"
22898 Compares the strings in two SVs. Returns \-1, 0, or 1 indicating whether the
22899 string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string in
22900 \&\f(CW\*(C`sv2\*(C'\fR. Is UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware and will coerce its args to strings
22901 if necessary. If the flags has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles get magic. See
22902 also \f(CW"sv_cmp_locale_flags"\fR.
22903 .RS 4
22904 .Sp
22905 .Vb 1
22906 \& I32 sv_cmp_flags(SV * const sv1, SV * const sv2, const U32 flags)
22907 .Ve
22908 .RE
22909 .RS 4
22910 .RE
22911 .ie n .IP """sv_cmp_locale""" 4
22912 .el .IP \f(CWsv_cmp_locale\fR 4
22913 .IX Xref "sv_cmp_locale"
22914 .IX Item "sv_cmp_locale"
22915 Compares the strings in two SVs in a locale-aware manner. Is UTF\-8 and
22916 \&\f(CW\*(Aquse\ bytes\*(Aq\fR aware, handles get magic, and will coerce its args to strings
22917 if necessary. See also \f(CW"sv_cmp"\fR.
22918 .RS 4
22919 .Sp
22920 .Vb 1
22921 \& I32 sv_cmp_locale(SV * const sv1, SV * const sv2)
22922 .Ve
22923 .RE
22924 .RS 4
22925 .RE
22926 .ie n .IP """sv_cmp_locale_flags""" 4
22927 .el .IP \f(CWsv_cmp_locale_flags\fR 4
22928 .IX Xref "sv_cmp_locale_flags"
22929 .IX Item "sv_cmp_locale_flags"
22930 Compares the strings in two SVs in a locale-aware manner. Is UTF\-8 and
22931 \&\f(CW\*(Aquse\ bytes\*(Aq\fR aware and will coerce its args to strings if necessary. If
22932 the flags contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, it handles get magic. See also
22933 \&\f(CW"sv_cmp_flags"\fR.
22934 .RS 4
22935 .Sp
22936 .Vb 2
22937 \& I32 sv_cmp_locale_flags(SV * const sv1, SV * const sv2,
22938 \& const U32 flags)
22939 .Ve
22940 .RE
22941 .RS 4
22942 .RE
22943 .ie n .IP """sv_collxfrm""" 4
22944 .el .IP \f(CWsv_collxfrm\fR 4
22945 .IX Xref "sv_collxfrm"
22946 .IX Item "sv_collxfrm"
22947 This calls \f(CW\*(C`sv_collxfrm_flags\*(C'\fR with the SV_GMAGIC flag. See
22948 \&\f(CW"sv_collxfrm_flags"\fR.
22949 .RS 4
22950 .Sp
22951 .Vb 1
22952 \& char * sv_collxfrm(SV * const sv, STRLEN * const nxp)
22953 .Ve
22954 .RE
22955 .RS 4
22956 .RE
22957 .ie n .IP """sv_collxfrm_flags""" 4
22958 .el .IP \f(CWsv_collxfrm_flags\fR 4
22959 .IX Xref "sv_collxfrm_flags"
22960 .IX Item "sv_collxfrm_flags"
22961 Add Collate Transform magic to an SV if it doesn't already have it. If the
22962 flags contain \f(CW\*(C`SV_GMAGIC\*(C'\fR, it handles get-magic.
22963 .Sp
22964 Any scalar variable may carry \f(CW\*(C`PERL_MAGIC_collxfrm\*(C'\fR magic that contains the
22965 scalar data of the variable, but transformed to such a format that a normal
22966 memory comparison can be used to compare the data according to the locale
22967 settings.
22968 .RS 4
22969 .Sp
22970 .Vb 2
22971 \& char * sv_collxfrm_flags(SV * const sv, STRLEN * const nxp,
22972 \& I32 const flags)
22973 .Ve
22974 .RE
22975 .RS 4
22976 .RE
22977 .ie n .IP """sv_copypv""" 4
22978 .el .IP \f(CWsv_copypv\fR 4
22979 .IX Item "sv_copypv"
22980 .PD 0
22981 .ie n .IP """sv_copypv_flags""" 4
22982 .el .IP \f(CWsv_copypv_flags\fR 4
22983 .IX Item "sv_copypv_flags"
22984 .ie n .IP """sv_copypv_nomg""" 4
22985 .el .IP \f(CWsv_copypv_nomg\fR 4
22986 .IX Xref "sv_copypv sv_copypv_flags sv_copypv_nomg"
22987 .IX Item "sv_copypv_nomg"
22988 .PD
22989 These copy a stringified representation of the source SV into the
22990 destination SV. They automatically perform coercion of numeric values into
22991 strings. Guaranteed to preserve the \f(CW\*(C`UTF8\*(C'\fR flag even from overloaded objects.
22992 Similar in nature to \f(CW\*(C`sv_2pv[_flags]\*(C'\fR but they operate directly on an SV
22993 instead of just the string. Mostly they use "\f(CW\*(C`sv_2pv_flags\*(C'\fR" to
22994 do the work, except when that would lose the UTF\-8'ness of the PV.
22995 .Sp
22996 The three forms differ only in whether or not they perform 'get magic' on
22997 \&\f(CW\*(C`sv\*(C'\fR. \f(CW\*(C`sv_copypv_nomg\*(C'\fR skips 'get magic'; \f(CW\*(C`sv_copypv\*(C'\fR performs it; and
22998 \&\f(CW\*(C`sv_copypv_flags\*(C'\fR either performs it (if the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit is set in
22999 \&\f(CW\*(C`flags\*(C'\fR) or doesn't (if that bit is cleared).
23000 .RS 4
23001 .Sp
23002 .Vb 4
23003 \& void sv_copypv (SV * const dsv, SV * const ssv)
23004 \& void sv_copypv_flags(SV * const dsv, SV * const ssv,
23005 \& const I32 flags)
23006 \& void sv_copypv_nomg (SV * const dsv, SV * const ssv)
23007 .Ve
23008 .RE
23009 .RS 4
23010 .RE
23011 .ie n .IP """SvCUR""" 4
23012 .el .IP \f(CWSvCUR\fR 4
23013 .IX Xref "SvCUR"
23014 .IX Item "SvCUR"
23015 Returns the length, in bytes, of the PV inside the SV.
23016 Note that this may not match Perl's \f(CW\*(C`length\*(C'\fR; for that, use
23017 \&\f(CWsv_len_utf8(sv)\fR. See \f(CW"SvLEN"\fR also.
23018 .RS 4
23019 .Sp
23020 .Vb 1
23021 \& STRLEN SvCUR(SV* sv)
23022 .Ve
23023 .RE
23024 .RS 4
23025 .RE
23026 .ie n .IP """SvCUR_set""" 4
23027 .el .IP \f(CWSvCUR_set\fR 4
23028 .IX Xref "SvCUR_set"
23029 .IX Item "SvCUR_set"
23030 Sets the current length, in bytes, of the C string which is in the SV.
23031 See \f(CW"SvCUR"\fR and \f(CW\*(C`SvIV_set\*(C'\fR>.
23032 .RS 4
23033 .Sp
23034 .Vb 1
23035 \& void SvCUR_set(SV* sv, STRLEN len)
23036 .Ve
23037 .RE
23038 .RS 4
23039 .RE
23040 .ie n .IP """sv_2cv""" 4
23041 .el .IP \f(CWsv_2cv\fR 4
23042 .IX Xref "sv_2cv"
23043 .IX Item "sv_2cv"
23044 Using various gambits, try to get a CV from an SV; in addition, try if
23045 possible to set \f(CW*st\fR and \f(CW*gvp\fR to the stash and GV associated with it.
23046 The flags in \f(CW\*(C`lref\*(C'\fR are passed to \f(CW\*(C`gv_fetchsv\*(C'\fR.
23047 .RS 4
23048 .Sp
23049 .Vb 2
23050 \& CV * sv_2cv(SV *sv, HV ** const st, GV ** const gvp,
23051 \& const I32 lref)
23052 .Ve
23053 .RE
23054 .RS 4
23055 .RE
23056 .ie n .IP """sv_dec""" 4
23057 .el .IP \f(CWsv_dec\fR 4
23058 .IX Item "sv_dec"
23059 .PD 0
23060 .ie n .IP """sv_dec_nomg""" 4
23061 .el .IP \f(CWsv_dec_nomg\fR 4
23062 .IX Xref "sv_dec sv_dec_nomg"
23063 .IX Item "sv_dec_nomg"
23064 .PD
23065 These auto-decrement the value in the SV, doing string to numeric conversion
23066 if necessary. They both handle operator overloading.
23067 .Sp
23068 They differ only in that:
23069 .Sp
23070 \&\f(CW\*(C`sv_dec\*(C'\fR handles 'get' magic; \f(CW\*(C`sv_dec_nomg\*(C'\fR skips 'get' magic.
23071 .RS 4
23072 .Sp
23073 .Vb 1
23074 \& void sv_dec(SV * const sv)
23075 .Ve
23076 .RE
23077 .RS 4
23078 .RE
23079 .ie n .IP """sv_derived_from""" 4
23080 .el .IP \f(CWsv_derived_from\fR 4
23081 .IX Xref "sv_derived_from"
23082 .IX Item "sv_derived_from"
23083 Exactly like "sv_derived_from_pv", but doesn't take a \f(CW\*(C`flags\*(C'\fR parameter.
23084 .RS 4
23085 .Sp
23086 .Vb 1
23087 \& bool sv_derived_from(SV *sv, const char * const name)
23088 .Ve
23089 .RE
23090 .RS 4
23091 .RE
23092 .ie n .IP """sv_derived_from_hv""" 4
23093 .el .IP \f(CWsv_derived_from_hv\fR 4
23094 .IX Xref "sv_derived_from_hv"
23095 .IX Item "sv_derived_from_hv"
23096 Exactly like "sv_derived_from_pvn", but takes the name string as the
23097 \&\f(CW\*(C`HvNAME\*(C'\fR of the given HV (which would presumably represent a stash).
23098 .RS 4
23099 .Sp
23100 .Vb 1
23101 \& bool sv_derived_from_hv(SV *sv, HV *hv)
23102 .Ve
23103 .RE
23104 .RS 4
23105 .RE
23106 .ie n .IP """sv_derived_from_pv""" 4
23107 .el .IP \f(CWsv_derived_from_pv\fR 4
23108 .IX Xref "sv_derived_from_pv"
23109 .IX Item "sv_derived_from_pv"
23110 Exactly like "sv_derived_from_pvn", but takes a nul-terminated string
23111 instead of a string/length pair.
23112 .RS 4
23113 .Sp
23114 .Vb 2
23115 \& bool sv_derived_from_pv(SV *sv, const char * const name,
23116 \& U32 flags)
23117 .Ve
23118 .RE
23119 .RS 4
23120 .RE
23121 .ie n .IP """sv_derived_from_pvn""" 4
23122 .el .IP \f(CWsv_derived_from_pvn\fR 4
23123 .IX Xref "sv_derived_from_pvn"
23124 .IX Item "sv_derived_from_pvn"
23125 Returns a boolean indicating whether the SV is derived from the specified class
23126 \&\fIat the C level\fR. To check derivation at the Perl level, call \f(CWisa()\fR as a
23127 normal Perl method.
23128 .Sp
23129 Currently, the only significant value for \f(CW\*(C`flags\*(C'\fR is SVf_UTF8.
23130 .RS 4
23131 .Sp
23132 .Vb 2
23133 \& bool sv_derived_from_pvn(SV *sv, const char * const name,
23134 \& const STRLEN len, U32 flags)
23135 .Ve
23136 .RE
23137 .RS 4
23138 .RE
23139 .ie n .IP """sv_derived_from_sv""" 4
23140 .el .IP \f(CWsv_derived_from_sv\fR 4
23141 .IX Xref "sv_derived_from_sv"
23142 .IX Item "sv_derived_from_sv"
23143 Exactly like "sv_derived_from_pvn", but takes the name string in the form
23144 of an SV instead of a string/length pair. This is the advised form.
23145 .RS 4
23146 .Sp
23147 .Vb 1
23148 \& bool sv_derived_from_sv(SV *sv, SV *namesv, U32 flags)
23149 .Ve
23150 .RE
23151 .RS 4
23152 .RE
23153 .ie n .IP """sv_does""" 4
23154 .el .IP \f(CWsv_does\fR 4
23155 .IX Xref "sv_does"
23156 .IX Item "sv_does"
23157 Like "sv_does_pv", but doesn't take a \f(CW\*(C`flags\*(C'\fR parameter.
23158 .RS 4
23159 .Sp
23160 .Vb 1
23161 \& bool sv_does(SV *sv, const char * const name)
23162 .Ve
23163 .RE
23164 .RS 4
23165 .RE
23166 .ie n .IP """sv_does_pv""" 4
23167 .el .IP \f(CWsv_does_pv\fR 4
23168 .IX Xref "sv_does_pv"
23169 .IX Item "sv_does_pv"
23170 Like "sv_does_sv", but takes a nul-terminated string instead of an SV.
23171 .RS 4
23172 .Sp
23173 .Vb 1
23174 \& bool sv_does_pv(SV *sv, const char * const name, U32 flags)
23175 .Ve
23176 .RE
23177 .RS 4
23178 .RE
23179 .ie n .IP """sv_does_pvn""" 4
23180 .el .IP \f(CWsv_does_pvn\fR 4
23181 .IX Xref "sv_does_pvn"
23182 .IX Item "sv_does_pvn"
23183 Like "sv_does_sv", but takes a string/length pair instead of an SV.
23184 .RS 4
23185 .Sp
23186 .Vb 2
23187 \& bool sv_does_pvn(SV *sv, const char * const name,
23188 \& const STRLEN len, U32 flags)
23189 .Ve
23190 .RE
23191 .RS 4
23192 .RE
23193 .ie n .IP """sv_does_sv""" 4
23194 .el .IP \f(CWsv_does_sv\fR 4
23195 .IX Xref "sv_does_sv"
23196 .IX Item "sv_does_sv"
23197 Returns a boolean indicating whether the SV performs a specific, named role.
23198 The SV can be a Perl object or the name of a Perl class.
23199 .RS 4
23200 .Sp
23201 .Vb 1
23202 \& bool sv_does_sv(SV *sv, SV *namesv, U32 flags)
23203 .Ve
23204 .RE
23205 .RS 4
23206 .RE
23207 .ie n .IP """SvEND""" 4
23208 .el .IP \f(CWSvEND\fR 4
23209 .IX Xref "SvEND"
23210 .IX Item "SvEND"
23211 Returns a pointer to the spot just after the last character in
23212 the string which is in the SV, where there is usually a trailing
23213 \&\f(CW\*(C`NUL\*(C'\fR character (even though Perl scalars do not strictly require it).
23214 See \f(CW"SvCUR"\fR. Access the character as \f(CW\*(C`*(SvEND(sv))\*(C'\fR.
23215 .Sp
23216 Warning: If \f(CW\*(C`SvCUR\*(C'\fR is equal to \f(CW\*(C`SvLEN\*(C'\fR, then \f(CW\*(C`SvEND\*(C'\fR points to
23217 unallocated memory.
23218 .RS 4
23219 .Sp
23220 .Vb 1
23221 \& char* SvEND(SV* sv)
23222 .Ve
23223 .RE
23224 .RS 4
23225 .RE
23226 .ie n .IP """sv_eq""" 4
23227 .el .IP \f(CWsv_eq\fR 4
23228 .IX Item "sv_eq"
23229 .PD 0
23230 .ie n .IP """sv_eq_flags""" 4
23231 .el .IP \f(CWsv_eq_flags\fR 4
23232 .IX Xref "sv_eq sv_eq_flags"
23233 .IX Item "sv_eq_flags"
23234 .PD
23235 These each return a boolean indicating whether or not the strings in the two
23236 SVs are equal. If \f(CW\*(Aquse\ bytes\*(Aq\fR is in effect, the comparison is
23237 byte-by-byte; otherwise character-by-character. Each will coerce its args to
23238 strings if necessary.
23239 .Sp
23240 They differ only in that \f(CW\*(C`sv_eq\*(C'\fR always processes get magic, while
23241 \&\f(CW\*(C`sv_eq_flags\*(C'\fR processes get magic only when the \f(CW\*(C`flags\*(C'\fR parameter has the
23242 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR bit set.
23243 .Sp
23244 These functions do not handle operator overloading. For versions that do,
23245 see instead \f(CW"sv_streq"\fR or \f(CW"sv_streq_flags"\fR.
23246 .RS 4
23247 .Sp
23248 .Vb 2
23249 \& I32 sv_eq (SV *sv1, SV *sv2)
23250 \& I32 sv_eq_flags(SV *sv1, SV *sv2, const U32 flags)
23251 .Ve
23252 .RE
23253 .RS 4
23254 .RE
23255 .ie n .IP """sv_force_normal""" 4
23256 .el .IP \f(CWsv_force_normal\fR 4
23257 .IX Xref "sv_force_normal"
23258 .IX Item "sv_force_normal"
23259 Undo various types of fakery on an SV: if the PV is a shared string, make
23260 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
23261 an \f(CW\*(C`xpvmg\*(C'\fR. See also \f(CW"sv_force_normal_flags"\fR.
23262 .RS 4
23263 .Sp
23264 .Vb 1
23265 \& void sv_force_normal(SV *sv)
23266 .Ve
23267 .RE
23268 .RS 4
23269 .RE
23270 .ie n .IP """sv_force_normal_flags""" 4
23271 .el .IP \f(CWsv_force_normal_flags\fR 4
23272 .IX Xref "sv_force_normal_flags"
23273 .IX Item "sv_force_normal_flags"
23274 Undo various types of fakery on an SV, where fakery means
23275 "more than" a string: if the PV is a shared string, make
23276 a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
23277 an \f(CW\*(C`xpvmg\*(C'\fR; if we're a copy-on-write scalar, this is the on-write time when
23278 we do the copy, and is also used locally; if this is a
23279 vstring, drop the vstring magic. If \f(CW\*(C`SV_COW_DROP_PV\*(C'\fR is set
23280 then a copy-on-write scalar drops its PV buffer (if any) and becomes
23281 \&\f(CW\*(C`SvPOK_off\*(C'\fR rather than making a copy. (Used where this
23282 scalar is about to be set to some other value.) In addition,
23283 the \f(CW\*(C`flags\*(C'\fR parameter gets passed to \f(CWsv_unref_flags()\fR
23284 when unreffing. \f(CW\*(C`sv_force_normal\*(C'\fR calls this function
23285 with flags set to 0.
23286 .Sp
23287 This function is expected to be used to signal to perl that this SV is
23288 about to be written to, and any extra book-keeping needs to be taken care
23289 of. Hence, it croaks on read-only values.
23290 .RS 4
23291 .Sp
23292 .Vb 1
23293 \& void sv_force_normal_flags(SV * const sv, const U32 flags)
23294 .Ve
23295 .RE
23296 .RS 4
23297 .RE
23298 .ie n .IP """sv_free""" 4
23299 .el .IP \f(CWsv_free\fR 4
23300 .IX Xref "sv_free"
23301 .IX Item "sv_free"
23302 Decrement an SV's reference count, and if it drops to zero, call
23303 \&\f(CW\*(C`sv_clear\*(C'\fR to invoke destructors and free up any memory used by
23304 the body; finally, deallocating the SV's head itself.
23305 Normally called via a wrapper macro \f(CW\*(C`SvREFCNT_dec\*(C'\fR.
23306 .RS 4
23307 .Sp
23308 .Vb 1
23309 \& void sv_free(SV * const sv)
23310 .Ve
23311 .RE
23312 .RS 4
23313 .RE
23314 .ie n .IP """SvGAMAGIC""" 4
23315 .el .IP \f(CWSvGAMAGIC\fR 4
23316 .IX Xref "SvGAMAGIC"
23317 .IX Item "SvGAMAGIC"
23318 Returns true if the SV has get magic or
23319 overloading. If either is true then
23320 the scalar is active data, and has the potential to return a new value every
23321 time it is accessed. Hence you must be careful to
23322 only read it once per user logical operation and work
23323 with that returned value. If neither is true then
23324 the scalar's value cannot change unless written to.
23325 .RS 4
23326 .Sp
23327 .Vb 1
23328 \& U32 SvGAMAGIC(SV* sv)
23329 .Ve
23330 .RE
23331 .RS 4
23332 .RE
23333 .ie n .IP """sv_get_backrefs""" 4
23334 .el .IP \f(CWsv_get_backrefs\fR 4
23335 .IX Xref "sv_get_backrefs"
23336 .IX Item "sv_get_backrefs"
23337 NOTE: \f(CW\*(C`sv_get_backrefs\*(C'\fR is \fBexperimental\fR and may change or be
23338 removed without notice.
23339 .Sp
23340 If \f(CW\*(C`sv\*(C'\fR is the target of a weak reference then it returns the back
23341 references structure associated with the sv; otherwise return \f(CW\*(C`NULL\*(C'\fR.
23342 .Sp
23343 When returning a non-null result the type of the return is relevant. If it
23344 is an AV then the elements of the AV are the weak reference RVs which
23345 point at this item. If it is any other type then the item itself is the
23346 weak reference.
23347 .Sp
23348 See also \f(CWPerl_sv_add_backref()\fR, \f(CWPerl_sv_del_backref()\fR,
23349 \&\f(CWPerl_sv_kill_backrefs()\fR
23350 .RS 4
23351 .Sp
23352 .Vb 1
23353 \& SV * sv_get_backrefs(SV * const sv)
23354 .Ve
23355 .RE
23356 .RS 4
23357 .RE
23358 .ie n .IP """SvGETMAGIC""" 4
23359 .el .IP \f(CWSvGETMAGIC\fR 4
23360 .IX Xref "SvGETMAGIC"
23361 .IX Item "SvGETMAGIC"
23362 Invokes \f(CW"mg_get"\fR on an SV if it has 'get' magic. For example, this
23363 will call \f(CW\*(C`FETCH\*(C'\fR on a tied variable. As of 5.37.1, this function is
23364 guaranteed to evaluate its argument exactly once.
23365 .RS 4
23366 .Sp
23367 .Vb 1
23368 \& void SvGETMAGIC(SV *sv)
23369 .Ve
23370 .RE
23371 .RS 4
23372 .RE
23373 .ie n .IP """sv_gets""" 4
23374 .el .IP \f(CWsv_gets\fR 4
23375 .IX Xref "sv_gets"
23376 .IX Item "sv_gets"
23377 Get a line from the filehandle and store it into the SV, optionally
23378 appending to the currently-stored string. If \f(CW\*(C`append\*(C'\fR is not 0, the
23379 line is appended to the SV instead of overwriting it. \f(CW\*(C`append\*(C'\fR should
23380 be set to the byte offset that the appended string should start at
23381 in the SV (typically, \f(CWSvCUR(sv)\fR is a suitable choice).
23382 .RS 4
23383 .Sp
23384 .Vb 1
23385 \& char * sv_gets(SV * const sv, PerlIO * const fp, I32 append)
23386 .Ve
23387 .RE
23388 .RS 4
23389 .RE
23390 .ie n .IP """SvGROW""" 4
23391 .el .IP \f(CWSvGROW\fR 4
23392 .IX Xref "SvGROW"
23393 .IX Item "SvGROW"
23394 Expands the character buffer in the SV so that it has room for the
23395 indicated number of bytes (remember to reserve space for an extra trailing
23396 \&\f(CW\*(C`NUL\*(C'\fR character). Calls \f(CW\*(C`sv_grow\*(C'\fR to perform the expansion if necessary.
23397 Returns a pointer to the character
23398 buffer. SV must be of type >= \f(CW\*(C`SVt_PV\*(C'\fR. One
23399 alternative is to call \f(CW\*(C`sv_grow\*(C'\fR if you are not sure of the type of SV.
23400 .Sp
23401 You might mistakenly think that \f(CW\*(C`len\*(C'\fR is the number of bytes to add to the
23402 existing size, but instead it is the total size \f(CW\*(C`sv\*(C'\fR should be.
23403 .RS 4
23404 .Sp
23405 .Vb 1
23406 \& char * SvGROW(SV* sv, STRLEN len)
23407 .Ve
23408 .RE
23409 .RS 4
23410 .RE
23411 .ie n .IP """SvIandPOK""" 4
23412 .el .IP \f(CWSvIandPOK\fR 4
23413 .IX Xref "SvIandPOK"
23414 .IX Item "SvIandPOK"
23415 Returns a bool indicating whether the SV is both \f(CWSvPOK()\fR and
23416 \&\f(CWSvIOK()\fR at the same time. Equivalent to \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR but
23417 more efficient.
23418 .RS 4
23419 .Sp
23420 .Vb 1
23421 \& U32 SvIandPOK(SV* sv)
23422 .Ve
23423 .RE
23424 .RS 4
23425 .RE
23426 .ie n .IP """SvIandPOK_off""" 4
23427 .el .IP \f(CWSvIandPOK_off\fR 4
23428 .IX Xref "SvIandPOK_off"
23429 .IX Item "SvIandPOK_off"
23430 Unsets the PV and IV status of an SV in one operation. Equivalent to
23431 \&\f(CW\*(C`SvIOK_off(sv); SvPK_off(v);\*(C'\fR but more efficient.
23432 .RS 4
23433 .Sp
23434 .Vb 1
23435 \& void SvIandPOK_off(SV* sv)
23436 .Ve
23437 .RE
23438 .RS 4
23439 .RE
23440 .ie n .IP """SvIandPOK_on""" 4
23441 .el .IP \f(CWSvIandPOK_on\fR 4
23442 .IX Xref "SvIandPOK_on"
23443 .IX Item "SvIandPOK_on"
23444 Tells an SV that is a string and a number in one operation. Equivalent
23445 to \f(CW\*(C`SvIOK_on(sv); SvPOK_on(sv);\*(C'\fR but more efficient.
23446 .RS 4
23447 .Sp
23448 .Vb 1
23449 \& void SvIandPOK_on(SV* sv)
23450 .Ve
23451 .RE
23452 .RS 4
23453 .RE
23454 .ie n .IP """sv_inc""" 4
23455 .el .IP \f(CWsv_inc\fR 4
23456 .IX Item "sv_inc"
23457 .PD 0
23458 .ie n .IP """sv_inc_nomg""" 4
23459 .el .IP \f(CWsv_inc_nomg\fR 4
23460 .IX Xref "sv_inc sv_inc_nomg"
23461 .IX Item "sv_inc_nomg"
23462 .PD
23463 These auto-increment the value in the SV, doing string to numeric conversion
23464 if necessary. They both handle operator overloading.
23465 .Sp
23466 They differ only in that \f(CW\*(C`sv_inc\*(C'\fR performs 'get' magic; \f(CW\*(C`sv_inc_nomg\*(C'\fR skips
23467 any magic.
23468 .RS 4
23469 .Sp
23470 .Vb 1
23471 \& void sv_inc(SV * const sv)
23472 .Ve
23473 .RE
23474 .RS 4
23475 .RE
23476 .ie n .IP """sv_insert""" 4
23477 .el .IP \f(CWsv_insert\fR 4
23478 .IX Item "sv_insert"
23479 .PD 0
23480 .ie n .IP """sv_insert_flags""" 4
23481 .el .IP \f(CWsv_insert_flags\fR 4
23482 .IX Xref "sv_insert sv_insert_flags"
23483 .IX Item "sv_insert_flags"
23484 .PD
23485 These insert and/or replace a string at the specified offset/length within the
23486 SV. Similar to the Perl \f(CWsubstr()\fR function, with \f(CW\*(C`littlelen\*(C'\fR bytes starting
23487 at \f(CW\*(C`little\*(C'\fR replacing \f(CW\*(C`len\*(C'\fR bytes of the string in \f(CW\*(C`bigstr\*(C'\fR starting at
23488 \&\f(CW\*(C`offset\*(C'\fR. They handle get magic.
23489 .Sp
23490 \&\f(CW\*(C`sv_insert_flags\*(C'\fR is identical to plain \f(CW\*(C`sv_insert\*(C'\fR, but the extra \f(CW\*(C`flags\*(C'\fR
23491 are passed to the \f(CW\*(C`SvPV_force_flags\*(C'\fR operation that is internally applied to
23492 \&\f(CW\*(C`bigstr\*(C'\fR.
23493 .RS 4
23494 .Sp
23495 .Vb 6
23496 \& void sv_insert (SV * const bigstr, const STRLEN offset,
23497 \& const STRLEN len, const char * const little,
23498 \& const STRLEN littlelen)
23499 \& void sv_insert_flags(SV * const bigstr, const STRLEN offset,
23500 \& const STRLEN len, const char *little,
23501 \& const STRLEN littlelen, const U32 flags)
23502 .Ve
23503 .RE
23504 .RS 4
23505 .RE
23506 .ie n .IP """sv_2io""" 4
23507 .el .IP \f(CWsv_2io\fR 4
23508 .IX Xref "sv_2io"
23509 .IX Item "sv_2io"
23510 Using various gambits, try to get an IO from an SV: the IO slot if its a
23511 GV; or the recursive result if we're an RV; or the IO slot of the symbol
23512 named after the PV if we're a string.
23513 .Sp
23514 \&'Get' magic is ignored on the \f(CW\*(C`sv\*(C'\fR passed in, but will be called on
23515 \&\f(CWSvRV(sv)\fR if \f(CW\*(C`sv\*(C'\fR is an RV.
23516 .RS 4
23517 .Sp
23518 .Vb 1
23519 \& IO * sv_2io(SV * const sv)
23520 .Ve
23521 .RE
23522 .RS 4
23523 .RE
23524 .ie n .IP """SvIOK""" 4
23525 .el .IP \f(CWSvIOK\fR 4
23526 .IX Xref "SvIOK"
23527 .IX Item "SvIOK"
23528 Returns a U32 value indicating whether the SV contains an integer.
23529 .RS 4
23530 .Sp
23531 .Vb 1
23532 \& U32 SvIOK(SV* sv)
23533 .Ve
23534 .RE
23535 .RS 4
23536 .RE
23537 .ie n .IP """SvIOK_notUV""" 4
23538 .el .IP \f(CWSvIOK_notUV\fR 4
23539 .IX Xref "SvIOK_notUV"
23540 .IX Item "SvIOK_notUV"
23541 Returns a boolean indicating whether the SV contains a signed integer.
23542 .RS 4
23543 .Sp
23544 .Vb 1
23545 \& bool SvIOK_notUV(SV* sv)
23546 .Ve
23547 .RE
23548 .RS 4
23549 .RE
23550 .ie n .IP """SvIOK_off""" 4
23551 .el .IP \f(CWSvIOK_off\fR 4
23552 .IX Xref "SvIOK_off"
23553 .IX Item "SvIOK_off"
23554 Unsets the IV status of an SV.
23555 .RS 4
23556 .Sp
23557 .Vb 1
23558 \& void SvIOK_off(SV* sv)
23559 .Ve
23560 .RE
23561 .RS 4
23562 .RE
23563 .ie n .IP """SvIOK_on""" 4
23564 .el .IP \f(CWSvIOK_on\fR 4
23565 .IX Xref "SvIOK_on"
23566 .IX Item "SvIOK_on"
23567 Tells an SV that it is an integer.
23568 .RS 4
23569 .Sp
23570 .Vb 1
23571 \& void SvIOK_on(SV* sv)
23572 .Ve
23573 .RE
23574 .RS 4
23575 .RE
23576 .ie n .IP """SvIOK_only""" 4
23577 .el .IP \f(CWSvIOK_only\fR 4
23578 .IX Xref "SvIOK_only"
23579 .IX Item "SvIOK_only"
23580 Tells an SV that it is an integer and disables all other \f(CW\*(C`OK\*(C'\fR bits.
23581 .RS 4
23582 .Sp
23583 .Vb 1
23584 \& void SvIOK_only(SV* sv)
23585 .Ve
23586 .RE
23587 .RS 4
23588 .RE
23589 .ie n .IP """SvIOK_only_UV""" 4
23590 .el .IP \f(CWSvIOK_only_UV\fR 4
23591 .IX Xref "SvIOK_only_UV"
23592 .IX Item "SvIOK_only_UV"
23593 Tells an SV that it is an unsigned integer and disables all other \f(CW\*(C`OK\*(C'\fR bits.
23594 .RS 4
23595 .Sp
23596 .Vb 1
23597 \& void SvIOK_only_UV(SV* sv)
23598 .Ve
23599 .RE
23600 .RS 4
23601 .RE
23602 .ie n .IP """SvIOKp""" 4
23603 .el .IP \f(CWSvIOKp\fR 4
23604 .IX Xref "SvIOKp"
23605 .IX Item "SvIOKp"
23606 Returns a U32 value indicating whether the SV contains an integer. Checks
23607 the \fBprivate\fR setting. Use \f(CW\*(C`SvIOK\*(C'\fR instead.
23608 .RS 4
23609 .Sp
23610 .Vb 1
23611 \& U32 SvIOKp(SV* sv)
23612 .Ve
23613 .RE
23614 .RS 4
23615 .RE
23616 .ie n .IP """SvIOK_UV""" 4
23617 .el .IP \f(CWSvIOK_UV\fR 4
23618 .IX Xref "SvIOK_UV"
23619 .IX Item "SvIOK_UV"
23620 Returns a boolean indicating whether the SV contains an integer that must be
23621 interpreted as unsigned. A non-negative integer whose value is within the
23622 range of both an IV and a UV may be flagged as either \f(CW\*(C`SvUOK\*(C'\fR or \f(CW\*(C`SvIOK\*(C'\fR.
23623 .RS 4
23624 .Sp
23625 .Vb 1
23626 \& bool SvIOK_UV(SV* sv)
23627 .Ve
23628 .RE
23629 .RS 4
23630 .RE
23631 .ie n .IP """sv_isa""" 4
23632 .el .IP \f(CWsv_isa\fR 4
23633 .IX Xref "sv_isa"
23634 .IX Item "sv_isa"
23635 Returns a boolean indicating whether the SV is blessed into the specified
23636 class.
23637 .Sp
23638 This does not check for subtypes or method overloading. Use \f(CW\*(C`sv_isa_sv\*(C'\fR to
23639 verify an inheritance relationship in the same way as the \f(CW\*(C`isa\*(C'\fR operator by
23640 respecting any \f(CWisa()\fR method overloading; or \f(CW\*(C`sv_derived_from_sv\*(C'\fR to test
23641 directly on the actual object type.
23642 .RS 4
23643 .Sp
23644 .Vb 1
23645 \& int sv_isa(SV *sv, const char * const name)
23646 .Ve
23647 .RE
23648 .RS 4
23649 .RE
23650 .ie n .IP """sv_isa_sv""" 4
23651 .el .IP \f(CWsv_isa_sv\fR 4
23652 .IX Xref "sv_isa_sv"
23653 .IX Item "sv_isa_sv"
23654 Returns a boolean indicating whether the SV is an object reference and is
23655 derived from the specified class, respecting any \f(CWisa()\fR method overloading
23656 it may have. Returns false if \f(CW\*(C`sv\*(C'\fR is not a reference to an object, or is
23657 not derived from the specified class.
23658 .Sp
23659 This is the function used to implement the behaviour of the \f(CW\*(C`isa\*(C'\fR operator.
23660 .Sp
23661 Does not invoke magic on \f(CW\*(C`sv\*(C'\fR.
23662 .Sp
23663 Not to be confused with the older \f(CW\*(C`sv_isa\*(C'\fR function, which does not use an
23664 overloaded \f(CWisa()\fR method, nor will check subclassing.
23665 .RS 4
23666 .Sp
23667 .Vb 1
23668 \& bool sv_isa_sv(SV *sv, SV *namesv)
23669 .Ve
23670 .RE
23671 .RS 4
23672 .RE
23673 .ie n .IP """SvIsBOOL""" 4
23674 .el .IP \f(CWSvIsBOOL\fR 4
23675 .IX Xref "SvIsBOOL"
23676 .IX Item "SvIsBOOL"
23677 Returns true if the SV is one of the special boolean constants (PL_sv_yes or
23678 PL_sv_no), or is a regular SV whose last assignment stored a copy of one.
23679 .RS 4
23680 .Sp
23681 .Vb 1
23682 \& bool SvIsBOOL(SV* sv)
23683 .Ve
23684 .RE
23685 .RS 4
23686 .RE
23687 .ie n .IP """SvIsCOW""" 4
23688 .el .IP \f(CWSvIsCOW\fR 4
23689 .IX Xref "SvIsCOW"
23690 .IX Item "SvIsCOW"
23691 Returns a U32 value indicating whether the SV is Copy-On-Write (either shared
23692 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
23693 COW).
23694 .RS 4
23695 .Sp
23696 .Vb 1
23697 \& U32 SvIsCOW(SV* sv)
23698 .Ve
23699 .RE
23700 .RS 4
23701 .RE
23702 .ie n .IP """SvIsCOW_shared_hash""" 4
23703 .el .IP \f(CWSvIsCOW_shared_hash\fR 4
23704 .IX Xref "SvIsCOW_shared_hash"
23705 .IX Item "SvIsCOW_shared_hash"
23706 Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
23707 scalar.
23708 .RS 4
23709 .Sp
23710 .Vb 1
23711 \& bool SvIsCOW_shared_hash(SV* sv)
23712 .Ve
23713 .RE
23714 .RS 4
23715 .RE
23716 .ie n .IP """sv_isobject""" 4
23717 .el .IP \f(CWsv_isobject\fR 4
23718 .IX Xref "sv_isobject"
23719 .IX Item "sv_isobject"
23720 Returns a boolean indicating whether the SV is an RV pointing to a blessed
23721 object. If the SV is not an RV, or if the object is not blessed, then this
23722 will return false.
23723 .RS 4
23724 .Sp
23725 .Vb 1
23726 \& int sv_isobject(SV *sv)
23727 .Ve
23728 .RE
23729 .RS 4
23730 .RE
23731 .ie n .IP """SvIV""" 4
23732 .el .IP \f(CWSvIV\fR 4
23733 .IX Item "SvIV"
23734 .PD 0
23735 .ie n .IP """SvIV_nomg""" 4
23736 .el .IP \f(CWSvIV_nomg\fR 4
23737 .IX Item "SvIV_nomg"
23738 .ie n .IP """SvIVx""" 4
23739 .el .IP \f(CWSvIVx\fR 4
23740 .IX Xref "SvIV SvIV_nomg SvIVx"
23741 .IX Item "SvIVx"
23742 .PD
23743 These each coerce the given SV to IV and return it. The returned value in many
23744 circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's IV slot, but not in all cases. (Use
23745 \&\f(CW"sv_setiv"\fR to make sure it does).
23746 .Sp
23747 As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
23748 .Sp
23749 \&\f(CW\*(C`SvIVx\*(C'\fR is now identical to \f(CW\*(C`SvIV\*(C'\fR, but prior to 5.37.1, it was the only form
23750 guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
23751 .Sp
23752 \&\f(CW\*(C`SvIV_nomg\*(C'\fR is the same as \f(CW\*(C`SvIV\*(C'\fR, but does not perform 'get' magic.
23753 .RS 4
23754 .Sp
23755 .Vb 1
23756 \& IV SvIV(SV *sv)
23757 .Ve
23758 .RE
23759 .RS 4
23760 .RE
23761 .ie n .IP """sv_2iv_flags""" 4
23762 .el .IP \f(CWsv_2iv_flags\fR 4
23763 .IX Xref "sv_2iv_flags"
23764 .IX Item "sv_2iv_flags"
23765 Return the integer value of an SV, doing any necessary string
23766 conversion. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first.
23767 Normally used via the \f(CWSvIV(sv)\fR and \f(CWSvIVx(sv)\fR macros.
23768 .RS 4
23769 .Sp
23770 .Vb 1
23771 \& IV sv_2iv_flags(SV * const sv, const I32 flags)
23772 .Ve
23773 .RE
23774 .RS 4
23775 .RE
23776 .ie n .IP """SvIV_set""" 4
23777 .el .IP \f(CWSvIV_set\fR 4
23778 .IX Xref "SvIV_set"
23779 .IX Item "SvIV_set"
23780 Set the value of the IV pointer in sv to val. It is possible to perform
23781 the same function of this macro with an lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR.
23782 With future Perls, however, it will be more efficient to use
23783 \&\f(CW\*(C`SvIV_set\*(C'\fR instead of the lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR.
23784 .RS 4
23785 .Sp
23786 .Vb 1
23787 \& void SvIV_set(SV* sv, IV val)
23788 .Ve
23789 .RE
23790 .RS 4
23791 .RE
23792 .ie n .IP """SvIVX""" 4
23793 .el .IP \f(CWSvIVX\fR 4
23794 .IX Xref "SvIVX"
23795 .IX Item "SvIVX"
23796 Returns the raw value in the SV's IV slot, without checks or conversions.
23797 Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true. See also \f(CW"SvIV"\fR.
23798 .RS 4
23799 .Sp
23800 .Vb 1
23801 \& IV SvIVX(SV* sv)
23802 .Ve
23803 .RE
23804 .RS 4
23805 .RE
23806 .ie n .IP """SvLEN""" 4
23807 .el .IP \f(CWSvLEN\fR 4
23808 .IX Xref "SvLEN"
23809 .IX Item "SvLEN"
23810 Returns the size of the string buffer in the SV, not including any part
23811 attributable to \f(CW\*(C`SvOOK\*(C'\fR. See \f(CW"SvCUR"\fR.
23812 .RS 4
23813 .Sp
23814 .Vb 1
23815 \& STRLEN SvLEN(SV* sv)
23816 .Ve
23817 .RE
23818 .RS 4
23819 .RE
23820 .ie n .IP """sv_len""" 4
23821 .el .IP \f(CWsv_len\fR 4
23822 .IX Xref "sv_len"
23823 .IX Item "sv_len"
23824 Returns the length of the string in the SV. Handles magic and type
23825 coercion and sets the UTF8 flag appropriately. See also \f(CW"SvCUR"\fR, which
23826 gives raw access to the \f(CW\*(C`xpv_cur\*(C'\fR slot.
23827 .RS 4
23828 .Sp
23829 .Vb 1
23830 \& STRLEN sv_len(SV * const sv)
23831 .Ve
23832 .RE
23833 .RS 4
23834 .RE
23835 .ie n .IP """SvLEN_set""" 4
23836 .el .IP \f(CWSvLEN_set\fR 4
23837 .IX Xref "SvLEN_set"
23838 .IX Item "SvLEN_set"
23839 Set the size of the string buffer for the SV. See \f(CW"SvLEN"\fR.
23840 .RS 4
23841 .Sp
23842 .Vb 1
23843 \& void SvLEN_set(SV* sv, STRLEN len)
23844 .Ve
23845 .RE
23846 .RS 4
23847 .RE
23848 .ie n .IP """sv_len_utf8""" 4
23849 .el .IP \f(CWsv_len_utf8\fR 4
23850 .IX Item "sv_len_utf8"
23851 .PD 0
23852 .ie n .IP """sv_len_utf8_nomg""" 4
23853 .el .IP \f(CWsv_len_utf8_nomg\fR 4
23854 .IX Xref "sv_len_utf8 sv_len_utf8_nomg"
23855 .IX Item "sv_len_utf8_nomg"
23856 .PD
23857 These return the number of characters in the string in an SV, counting wide
23858 UTF\-8 bytes as a single character. Both handle type coercion.
23859 They differ only in that \f(CW\*(C`sv_len_utf8\*(C'\fR performs 'get' magic;
23860 \&\f(CW\*(C`sv_len_utf8_nomg\*(C'\fR skips any magic.
23861 .RS 4
23862 .Sp
23863 .Vb 1
23864 \& STRLEN sv_len_utf8(SV * const sv)
23865 .Ve
23866 .RE
23867 .RS 4
23868 .RE
23869 .ie n .IP """SvLOCK""" 4
23870 .el .IP \f(CWSvLOCK\fR 4
23871 .IX Xref "SvLOCK"
23872 .IX Item "SvLOCK"
23873 Arranges for a mutual exclusion lock to be obtained on \f(CW\*(C`sv\*(C'\fR if a suitable module
23874 has been loaded.
23875 .RS 4
23876 .Sp
23877 .Vb 1
23878 \& void SvLOCK(SV* sv)
23879 .Ve
23880 .RE
23881 .RS 4
23882 .RE
23883 .ie n .IP """sv_magic""" 4
23884 .el .IP \f(CWsv_magic\fR 4
23885 .IX Xref "sv_magic"
23886 .IX Item "sv_magic"
23887 Adds magic to an SV. First upgrades \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR if
23888 necessary, then adds a new magic item of type \f(CW\*(C`how\*(C'\fR to the head of the
23889 magic list.
23890 .Sp
23891 See \f(CW"sv_magicext"\fR (which \f(CW\*(C`sv_magic\*(C'\fR now calls) for a description of the
23892 handling of the \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments.
23893 .Sp
23894 You need to use \f(CW\*(C`sv_magicext\*(C'\fR to add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs and also
23895 to add more than one instance of the same \f(CW\*(C`how\*(C'\fR.
23896 .RS 4
23897 .Sp
23898 .Vb 2
23899 \& void sv_magic(SV * const sv, SV * const obj, const int how,
23900 \& const char * const name, const I32 namlen)
23901 .Ve
23902 .RE
23903 .RS 4
23904 .RE
23905 .ie n .IP """sv_magicext""" 4
23906 .el .IP \f(CWsv_magicext\fR 4
23907 .IX Xref "sv_magicext"
23908 .IX Item "sv_magicext"
23909 Adds magic to an SV, upgrading it if necessary. Applies the
23910 supplied \f(CW\*(C`vtable\*(C'\fR and returns a pointer to the magic added.
23911 .Sp
23912 Note that \f(CW\*(C`sv_magicext\*(C'\fR will allow things that \f(CW\*(C`sv_magic\*(C'\fR will not.
23913 In particular, you can add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs, and add more than
23914 one instance of the same \f(CW\*(C`how\*(C'\fR.
23915 .Sp
23916 If \f(CW\*(C`namlen\*(C'\fR is greater than zero then a \f(CW\*(C`savepvn\*(C'\fR \fIcopy\fR of \f(CW\*(C`name\*(C'\fR is
23917 stored, if \f(CW\*(C`namlen\*(C'\fR is zero then \f(CW\*(C`name\*(C'\fR is stored as-is and \- as another
23918 special case \- if \f(CW\*(C`(name && namlen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed
23919 to contain an SV* and is stored as-is with its \f(CW\*(C`REFCNT\*(C'\fR incremented.
23920 .Sp
23921 (This is now used as a subroutine by \f(CW\*(C`sv_magic\*(C'\fR.)
23922 .RS 4
23923 .Sp
23924 .Vb 3
23925 \& MAGIC * sv_magicext(SV * const sv, SV * const obj, const int how,
23926 \& const MGVTBL * const vtbl,
23927 \& const char * const name, const I32 namlen)
23928 .Ve
23929 .RE
23930 .RS 4
23931 .RE
23932 .ie n .IP """SvMAGIC_set""" 4
23933 .el .IP \f(CWSvMAGIC_set\fR 4
23934 .IX Xref "SvMAGIC_set"
23935 .IX Item "SvMAGIC_set"
23936 Set the value of the MAGIC pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
23937 .RS 4
23938 .Sp
23939 .Vb 1
23940 \& void SvMAGIC_set(SV* sv, MAGIC* val)
23941 .Ve
23942 .RE
23943 .RS 4
23944 .RE
23945 .ie n .IP """sv_2mortal""" 4
23946 .el .IP \f(CWsv_2mortal\fR 4
23947 .IX Xref "sv_2mortal"
23948 .IX Item "sv_2mortal"
23949 Marks an existing SV as mortal. The SV will be destroyed "soon", either
23950 by an explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as
23951 statement boundaries. \f(CWSvTEMP()\fR is turned on which means that the SV's
23952 string buffer can be "stolen" if this SV is copied. See also
23953 \&\f(CW"sv_newmortal"\fR and \f(CW"sv_mortalcopy"\fR.
23954 .RS 4
23955 .Sp
23956 .Vb 1
23957 \& SV * sv_2mortal(SV * const sv)
23958 .Ve
23959 .RE
23960 .RS 4
23961 .RE
23962 .ie n .IP """sv_mortalcopy""" 4
23963 .el .IP \f(CWsv_mortalcopy\fR 4
23964 .IX Xref "sv_mortalcopy"
23965 .IX Item "sv_mortalcopy"
23966 Creates a new SV which is a copy of the original SV (using \f(CW\*(C`sv_setsv\*(C'\fR).
23967 The new SV is marked as mortal. It will be destroyed "soon", either by an
23968 explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as
23969 statement boundaries. See also \f(CW"sv_newmortal"\fR and \f(CW"sv_2mortal"\fR.
23970 .RS 4
23971 .Sp
23972 .Vb 1
23973 \& SV * sv_mortalcopy(SV * const oldsv)
23974 .Ve
23975 .RE
23976 .RS 4
23977 .RE
23978 .ie n .IP """sv_mortalcopy_flags""" 4
23979 .el .IP \f(CWsv_mortalcopy_flags\fR 4
23980 .IX Xref "sv_mortalcopy_flags"
23981 .IX Item "sv_mortalcopy_flags"
23982 Like \f(CW\*(C`sv_mortalcopy\*(C'\fR, but the extra \f(CW\*(C`flags\*(C'\fR are passed to the
23983 \&\f(CW\*(C`sv_setsv_flags\*(C'\fR.
23984 .RS 4
23985 .Sp
23986 .Vb 1
23987 \& SV * sv_mortalcopy_flags(SV * const oldsv, U32 flags)
23988 .Ve
23989 .RE
23990 .RS 4
23991 .RE
23992 .ie n .IP """sv_newmortal""" 4
23993 .el .IP \f(CWsv_newmortal\fR 4
23994 .IX Xref "sv_newmortal"
23995 .IX Item "sv_newmortal"
23996 Creates a new null SV which is mortal. The reference count of the SV is
23997 set to 1. It will be destroyed "soon", either by an explicit call to
23998 \&\f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as statement boundaries.
23999 See also \f(CW"sv_mortalcopy"\fR and \f(CW"sv_2mortal"\fR.
24000 .RS 4
24001 .Sp
24002 .Vb 1
24003 \& SV * sv_newmortal()
24004 .Ve
24005 .RE
24006 .RS 4
24007 .RE
24008 .ie n .IP """SvNIOK""" 4
24009 .el .IP \f(CWSvNIOK\fR 4
24010 .IX Xref "SvNIOK"
24011 .IX Item "SvNIOK"
24012 Returns a U32 value indicating whether the SV contains a number, integer or
24013 double.
24014 .RS 4
24015 .Sp
24016 .Vb 1
24017 \& U32 SvNIOK(SV* sv)
24018 .Ve
24019 .RE
24020 .RS 4
24021 .RE
24022 .ie n .IP """SvNIOK_off""" 4
24023 .el .IP \f(CWSvNIOK_off\fR 4
24024 .IX Xref "SvNIOK_off"
24025 .IX Item "SvNIOK_off"
24026 Unsets the NV/IV status of an SV.
24027 .RS 4
24028 .Sp
24029 .Vb 1
24030 \& void SvNIOK_off(SV* sv)
24031 .Ve
24032 .RE
24033 .RS 4
24034 .RE
24035 .ie n .IP """SvNIOKp""" 4
24036 .el .IP \f(CWSvNIOKp\fR 4
24037 .IX Xref "SvNIOKp"
24038 .IX Item "SvNIOKp"
24039 Returns a U32 value indicating whether the SV contains a number, integer or
24040 double. Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvNIOK\*(C'\fR instead.
24041 .RS 4
24042 .Sp
24043 .Vb 1
24044 \& U32 SvNIOKp(SV* sv)
24045 .Ve
24046 .RE
24047 .RS 4
24048 .RE
24049 .ie n .IP """SvNOK""" 4
24050 .el .IP \f(CWSvNOK\fR 4
24051 .IX Xref "SvNOK"
24052 .IX Item "SvNOK"
24053 Returns a U32 value indicating whether the SV contains a double.
24054 .RS 4
24055 .Sp
24056 .Vb 1
24057 \& U32 SvNOK(SV* sv)
24058 .Ve
24059 .RE
24060 .RS 4
24061 .RE
24062 .ie n .IP """SvNOK_off""" 4
24063 .el .IP \f(CWSvNOK_off\fR 4
24064 .IX Xref "SvNOK_off"
24065 .IX Item "SvNOK_off"
24066 Unsets the NV status of an SV.
24067 .RS 4
24068 .Sp
24069 .Vb 1
24070 \& void SvNOK_off(SV* sv)
24071 .Ve
24072 .RE
24073 .RS 4
24074 .RE
24075 .ie n .IP """SvNOK_on""" 4
24076 .el .IP \f(CWSvNOK_on\fR 4
24077 .IX Xref "SvNOK_on"
24078 .IX Item "SvNOK_on"
24079 Tells an SV that it is a double.
24080 .RS 4
24081 .Sp
24082 .Vb 1
24083 \& void SvNOK_on(SV* sv)
24084 .Ve
24085 .RE
24086 .RS 4
24087 .RE
24088 .ie n .IP """SvNOK_only""" 4
24089 .el .IP \f(CWSvNOK_only\fR 4
24090 .IX Xref "SvNOK_only"
24091 .IX Item "SvNOK_only"
24092 Tells an SV that it is a double and disables all other OK bits.
24093 .RS 4
24094 .Sp
24095 .Vb 1
24096 \& void SvNOK_only(SV* sv)
24097 .Ve
24098 .RE
24099 .RS 4
24100 .RE
24101 .ie n .IP """SvNOKp""" 4
24102 .el .IP \f(CWSvNOKp\fR 4
24103 .IX Xref "SvNOKp"
24104 .IX Item "SvNOKp"
24105 Returns a U32 value indicating whether the SV contains a double. Checks the
24106 \&\fBprivate\fR setting. Use \f(CW\*(C`SvNOK\*(C'\fR instead.
24107 .RS 4
24108 .Sp
24109 .Vb 1
24110 \& U32 SvNOKp(SV* sv)
24111 .Ve
24112 .RE
24113 .RS 4
24114 .RE
24115 .ie n .IP """sv_nolocking""" 4
24116 .el .IP \f(CWsv_nolocking\fR 4
24117 .IX Xref "sv_nolocking"
24118 .IX Item "sv_nolocking"
24119 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`sv_nolocking\*(C'\fR
24120 from a future release of Perl. Do not use it for
24121 new code; remove it from existing code.
24122 .Sp
24123 Dummy routine which "locks" an SV when there is no locking module present.
24124 Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
24125 potentially warn under some level of strict-ness.
24126 .Sp
24127 "Superseded" by \f(CWsv_nosharing()\fR.
24128 .RS 4
24129 .Sp
24130 .Vb 1
24131 \& void sv_nolocking(SV *sv)
24132 .Ve
24133 .RE
24134 .RS 4
24135 .RE
24136 .ie n .IP """sv_nounlocking""" 4
24137 .el .IP \f(CWsv_nounlocking\fR 4
24138 .IX Xref "sv_nounlocking"
24139 .IX Item "sv_nounlocking"
24140 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`sv_nounlocking\*(C'\fR
24141 from a future release of Perl. Do not use it for
24142 new code; remove it from existing code.
24143 .Sp
24144 Dummy routine which "unlocks" an SV when there is no locking module present.
24145 Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
24146 potentially warn under some level of strict-ness.
24147 .Sp
24148 "Superseded" by \f(CWsv_nosharing()\fR.
24149 .RS 4
24150 .Sp
24151 .Vb 1
24152 \& void sv_nounlocking(SV *sv)
24153 .Ve
24154 .RE
24155 .RS 4
24156 .RE
24157 .ie n .IP """sv_numeq""" 4
24158 .el .IP \f(CWsv_numeq\fR 4
24159 .IX Xref "sv_numeq"
24160 .IX Item "sv_numeq"
24161 A convenient shortcut for calling \f(CW\*(C`sv_numeq_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR
24162 flag. This function basically behaves like the Perl code \f(CW\*(C`$sv1 == $sv2\*(C'\fR.
24163 .RS 4
24164 .Sp
24165 .Vb 1
24166 \& bool sv_numeq(SV *sv1, SV *sv2)
24167 .Ve
24168 .RE
24169 .RS 4
24170 .RE
24171 .ie n .IP """sv_numeq_flags""" 4
24172 .el .IP \f(CWsv_numeq_flags\fR 4
24173 .IX Xref "sv_numeq_flags"
24174 .IX Item "sv_numeq_flags"
24175 Returns a boolean indicating whether the numbers in the two SVs are
24176 identical. If the flags argument has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles
24177 get-magic too. Will coerce its args to numbers if necessary. Treats
24178 \&\f(CW\*(C`NULL\*(C'\fR as undef.
24179 .Sp
24180 If flags does not have the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use
24181 \&\f(CW\*(C`==\*(C'\fR overloading will be made. If such overloading does not exist or the
24182 flag is set, then regular numerical comparison will be used instead.
24183 .RS 4
24184 .Sp
24185 .Vb 1
24186 \& bool sv_numeq_flags(SV *sv1, SV *sv2, const U32 flags)
24187 .Ve
24188 .RE
24189 .RS 4
24190 .RE
24191 .ie n .IP """SvNV""" 4
24192 .el .IP \f(CWSvNV\fR 4
24193 .IX Item "SvNV"
24194 .PD 0
24195 .ie n .IP """SvNV_nomg""" 4
24196 .el .IP \f(CWSvNV_nomg\fR 4
24197 .IX Item "SvNV_nomg"
24198 .ie n .IP """SvNVx""" 4
24199 .el .IP \f(CWSvNVx\fR 4
24200 .IX Xref "SvNV SvNV_nomg SvNVx"
24201 .IX Item "SvNVx"
24202 .PD
24203 These each coerce the given SV to NV and return it. The returned value in many
24204 circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's NV slot, but not in all cases. (Use
24205 \&\f(CW"sv_setnv"\fR to make sure it does).
24206 .Sp
24207 As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
24208 .Sp
24209 \&\f(CW\*(C`SvNVx\*(C'\fR is now identical to \f(CW\*(C`SvNV\*(C'\fR, but prior to 5.37.1, it was the only form
24210 guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
24211 .Sp
24212 \&\f(CW\*(C`SvNV_nomg\*(C'\fR is the same as \f(CW\*(C`SvNV\*(C'\fR, but does not perform 'get' magic.
24213 .RS 4
24214 .Sp
24215 .Vb 1
24216 \& NV SvNV(SV *sv)
24217 .Ve
24218 .RE
24219 .RS 4
24220 .RE
24221 .ie n .IP """sv_2nv_flags""" 4
24222 .el .IP \f(CWsv_2nv_flags\fR 4
24223 .IX Xref "sv_2nv_flags"
24224 .IX Item "sv_2nv_flags"
24225 Return the num value of an SV, doing any necessary string or integer
24226 conversion. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first.
24227 Normally used via the \f(CWSvNV(sv)\fR and \f(CWSvNVx(sv)\fR macros.
24228 .RS 4
24229 .Sp
24230 .Vb 1
24231 \& NV sv_2nv_flags(SV * const sv, const I32 flags)
24232 .Ve
24233 .RE
24234 .RS 4
24235 .RE
24236 .ie n .IP """SvNV_set""" 4
24237 .el .IP \f(CWSvNV_set\fR 4
24238 .IX Xref "SvNV_set"
24239 .IX Item "SvNV_set"
24240 Set the value of the NV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
24241 .RS 4
24242 .Sp
24243 .Vb 1
24244 \& void SvNV_set(SV* sv, NV val)
24245 .Ve
24246 .RE
24247 .RS 4
24248 .RE
24249 .ie n .IP """SvNVX""" 4
24250 .el .IP \f(CWSvNVX\fR 4
24251 .IX Xref "SvNVX"
24252 .IX Item "SvNVX"
24253 Returns the raw value in the SV's NV slot, without checks or conversions.
24254 Only use when you are sure \f(CW\*(C`SvNOK\*(C'\fR is true. See also \f(CW"SvNV"\fR.
24255 .RS 4
24256 .Sp
24257 .Vb 1
24258 \& NV SvNVX(SV* sv)
24259 .Ve
24260 .RE
24261 .RS 4
24262 .RE
24263 .ie n .IP """SvOK""" 4
24264 .el .IP \f(CWSvOK\fR 4
24265 .IX Xref "SvOK"
24266 .IX Item "SvOK"
24267 Returns a U32 value indicating whether the value is defined. This is
24268 only meaningful for scalars.
24269 .RS 4
24270 .Sp
24271 .Vb 1
24272 \& U32 SvOK(SV* sv)
24273 .Ve
24274 .RE
24275 .RS 4
24276 .RE
24277 .ie n .IP """SvOOK""" 4
24278 .el .IP \f(CWSvOOK\fR 4
24279 .IX Xref "SvOOK"
24280 .IX Item "SvOOK"
24281 Returns a U32 indicating whether the pointer to the string buffer is offset.
24282 This hack is used internally to speed up removal of characters from the
24283 beginning of a \f(CW"SvPV"\fR. When \f(CW\*(C`SvOOK\*(C'\fR is true, then the start of the
24284 allocated string buffer is actually \f(CWSvOOK_offset()\fR bytes before \f(CW\*(C`SvPVX\*(C'\fR.
24285 This offset used to be stored in \f(CW\*(C`SvIVX\*(C'\fR, but is now stored within the spare
24286 part of the buffer.
24287 .RS 4
24288 .Sp
24289 .Vb 1
24290 \& U32 SvOOK(SV* sv)
24291 .Ve
24292 .RE
24293 .RS 4
24294 .RE
24295 .ie n .IP """SvOOK_off""" 4
24296 .el .IP \f(CWSvOOK_off\fR 4
24297 .IX Xref "SvOOK_off"
24298 .IX Item "SvOOK_off"
24299 Remove any string offset.
24300 .RS 4
24301 .Sp
24302 .Vb 1
24303 \& void SvOOK_off(SV * sv)
24304 .Ve
24305 .RE
24306 .RS 4
24307 .RE
24308 .ie n .IP """SvOOK_offset""" 4
24309 .el .IP \f(CWSvOOK_offset\fR 4
24310 .IX Xref "SvOOK_offset"
24311 .IX Item "SvOOK_offset"
24312 Reads into \f(CW\*(C`len\*(C'\fR the offset from \f(CW\*(C`SvPVX\*(C'\fR back to the true start of the
24313 allocated buffer, which will be non-zero if \f(CW\*(C`sv_chop\*(C'\fR has been used to
24314 efficiently remove characters from start of the buffer. Implemented as a
24315 macro, which takes the address of \f(CW\*(C`len\*(C'\fR, which must be of type \f(CW\*(C`STRLEN\*(C'\fR.
24316 Evaluates \f(CW\*(C`sv\*(C'\fR more than once. Sets \f(CW\*(C`len\*(C'\fR to 0 if \f(CWSvOOK(sv)\fR is false.
24317 .RS 4
24318 .Sp
24319 .Vb 1
24320 \& void SvOOK_offset(SV*sv, STRLEN len)
24321 .Ve
24322 .RE
24323 .RS 4
24324 .RE
24325 .ie n .IP """SvPOK""" 4
24326 .el .IP \f(CWSvPOK\fR 4
24327 .IX Xref "SvPOK"
24328 .IX Item "SvPOK"
24329 Returns a U32 value indicating whether the SV contains a character
24330 string.
24331 .RS 4
24332 .Sp
24333 .Vb 1
24334 \& U32 SvPOK(SV* sv)
24335 .Ve
24336 .RE
24337 .RS 4
24338 .RE
24339 .ie n .IP """SvPOK_off""" 4
24340 .el .IP \f(CWSvPOK_off\fR 4
24341 .IX Xref "SvPOK_off"
24342 .IX Item "SvPOK_off"
24343 Unsets the PV status of an SV.
24344 .RS 4
24345 .Sp
24346 .Vb 1
24347 \& void SvPOK_off(SV* sv)
24348 .Ve
24349 .RE
24350 .RS 4
24351 .RE
24352 .ie n .IP """SvPOK_on""" 4
24353 .el .IP \f(CWSvPOK_on\fR 4
24354 .IX Xref "SvPOK_on"
24355 .IX Item "SvPOK_on"
24356 Tells an SV that it is a string.
24357 .RS 4
24358 .Sp
24359 .Vb 1
24360 \& void SvPOK_on(SV* sv)
24361 .Ve
24362 .RE
24363 .RS 4
24364 .RE
24365 .ie n .IP """SvPOK_only""" 4
24366 .el .IP \f(CWSvPOK_only\fR 4
24367 .IX Xref "SvPOK_only"
24368 .IX Item "SvPOK_only"
24369 Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits.
24370 Will also turn off the UTF\-8 status.
24371 .RS 4
24372 .Sp
24373 .Vb 1
24374 \& void SvPOK_only(SV* sv)
24375 .Ve
24376 .RE
24377 .RS 4
24378 .RE
24379 .ie n .IP """SvPOK_only_UTF8""" 4
24380 .el .IP \f(CWSvPOK_only_UTF8\fR 4
24381 .IX Xref "SvPOK_only_UTF8"
24382 .IX Item "SvPOK_only_UTF8"
24383 Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits,
24384 and leaves the UTF\-8 status as it was.
24385 .RS 4
24386 .Sp
24387 .Vb 1
24388 \& void SvPOK_only_UTF8(SV* sv)
24389 .Ve
24390 .RE
24391 .RS 4
24392 .RE
24393 .ie n .IP """SvPOKp""" 4
24394 .el .IP \f(CWSvPOKp\fR 4
24395 .IX Xref "SvPOKp"
24396 .IX Item "SvPOKp"
24397 Returns a U32 value indicating whether the SV contains a character string.
24398 Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvPOK\*(C'\fR instead.
24399 .RS 4
24400 .Sp
24401 .Vb 1
24402 \& U32 SvPOKp(SV* sv)
24403 .Ve
24404 .RE
24405 .RS 4
24406 .RE
24407 .ie n .IP """sv_pos_b2u""" 4
24408 .el .IP \f(CWsv_pos_b2u\fR 4
24409 .IX Xref "sv_pos_b2u"
24410 .IX Item "sv_pos_b2u"
24411 Converts the value pointed to by \f(CW\*(C`offsetp\*(C'\fR from a count of bytes from the
24412 start of the string, to a count of the equivalent number of UTF\-8 chars.
24413 Handles magic and type coercion.
24414 .Sp
24415 Use \f(CW\*(C`sv_pos_b2u_flags\*(C'\fR in preference, which correctly handles strings
24416 longer than 2Gb.
24417 .RS 4
24418 .Sp
24419 .Vb 1
24420 \& void sv_pos_b2u(SV * const sv, I32 * const offsetp)
24421 .Ve
24422 .RE
24423 .RS 4
24424 .RE
24425 .ie n .IP """sv_pos_b2u_flags""" 4
24426 .el .IP \f(CWsv_pos_b2u_flags\fR 4
24427 .IX Xref "sv_pos_b2u_flags"
24428 .IX Item "sv_pos_b2u_flags"
24429 Converts \f(CW\*(C`offset\*(C'\fR from a count of bytes from the start of the string, to
24430 a count of the equivalent number of UTF\-8 chars. Handles type coercion.
24431 \&\f(CW\*(C`flags\*(C'\fR is passed to \f(CW\*(C`SvPV_flags\*(C'\fR, and usually should be
24432 \&\f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR to handle magic.
24433 .RS 4
24434 .Sp
24435 .Vb 2
24436 \& STRLEN sv_pos_b2u_flags(SV * const sv, STRLEN const offset,
24437 \& U32 flags)
24438 .Ve
24439 .RE
24440 .RS 4
24441 .RE
24442 .ie n .IP """sv_pos_u2b""" 4
24443 .el .IP \f(CWsv_pos_u2b\fR 4
24444 .IX Xref "sv_pos_u2b"
24445 .IX Item "sv_pos_u2b"
24446 Converts the value pointed to by \f(CW\*(C`offsetp\*(C'\fR from a count of UTF\-8 chars from
24447 the start of the string, to a count of the equivalent number of bytes; if
24448 \&\f(CW\*(C`lenp\*(C'\fR is non-zero, it does the same to \f(CW\*(C`lenp\*(C'\fR, but this time starting from
24449 the offset, rather than from the start of the string. Handles magic and
24450 type coercion.
24451 .Sp
24452 Use \f(CW\*(C`sv_pos_u2b_flags\*(C'\fR in preference, which correctly handles strings longer
24453 than 2Gb.
24454 .RS 4
24455 .Sp
24456 .Vb 2
24457 \& void sv_pos_u2b(SV * const sv, I32 * const offsetp,
24458 \& I32 * const lenp)
24459 .Ve
24460 .RE
24461 .RS 4
24462 .RE
24463 .ie n .IP """sv_pos_u2b_flags""" 4
24464 .el .IP \f(CWsv_pos_u2b_flags\fR 4
24465 .IX Xref "sv_pos_u2b_flags"
24466 .IX Item "sv_pos_u2b_flags"
24467 Converts the offset from a count of UTF\-8 chars from
24468 the start of the string, to a count of the equivalent number of bytes; if
24469 \&\f(CW\*(C`lenp\*(C'\fR is non-zero, it does the same to \f(CW\*(C`lenp\*(C'\fR, but this time starting from
24470 \&\f(CW\*(C`offset\*(C'\fR, rather than from the start
24471 of the string. Handles type coercion.
24472 \&\f(CW\*(C`flags\*(C'\fR is passed to \f(CW\*(C`SvPV_flags\*(C'\fR, and usually should be
24473 \&\f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR to handle magic.
24474 .RS 4
24475 .Sp
24476 .Vb 2
24477 \& STRLEN sv_pos_u2b_flags(SV * const sv, STRLEN uoffset,
24478 \& STRLEN * const lenp, U32 flags)
24479 .Ve
24480 .RE
24481 .RS 4
24482 .RE
24483 .ie n .IP """SvPV""" 4
24484 .el .IP \f(CWSvPV\fR 4
24485 .IX Item "SvPV"
24486 .PD 0
24487 .ie n .IP """SvPV_const""" 4
24488 .el .IP \f(CWSvPV_const\fR 4
24489 .IX Item "SvPV_const"
24490 .ie n .IP """SvPV_flags""" 4
24491 .el .IP \f(CWSvPV_flags\fR 4
24492 .IX Item "SvPV_flags"
24493 .ie n .IP """SvPV_flags_const""" 4
24494 .el .IP \f(CWSvPV_flags_const\fR 4
24495 .IX Item "SvPV_flags_const"
24496 .ie n .IP """SvPV_flags_mutable""" 4
24497 .el .IP \f(CWSvPV_flags_mutable\fR 4
24498 .IX Item "SvPV_flags_mutable"
24499 .ie n .IP """SvPV_mutable""" 4
24500 .el .IP \f(CWSvPV_mutable\fR 4
24501 .IX Item "SvPV_mutable"
24502 .ie n .IP """SvPV_nolen""" 4
24503 .el .IP \f(CWSvPV_nolen\fR 4
24504 .IX Item "SvPV_nolen"
24505 .ie n .IP """SvPV_nolen_const""" 4
24506 .el .IP \f(CWSvPV_nolen_const\fR 4
24507 .IX Item "SvPV_nolen_const"
24508 .ie n .IP """SvPV_nomg""" 4
24509 .el .IP \f(CWSvPV_nomg\fR 4
24510 .IX Item "SvPV_nomg"
24511 .ie n .IP """SvPV_nomg_const""" 4
24512 .el .IP \f(CWSvPV_nomg_const\fR 4
24513 .IX Item "SvPV_nomg_const"
24514 .ie n .IP """SvPV_nomg_const_nolen""" 4
24515 .el .IP \f(CWSvPV_nomg_const_nolen\fR 4
24516 .IX Item "SvPV_nomg_const_nolen"
24517 .ie n .IP """SvPV_nomg_nolen""" 4
24518 .el .IP \f(CWSvPV_nomg_nolen\fR 4
24519 .IX Item "SvPV_nomg_nolen"
24520 .ie n .IP """SvPVbyte""" 4
24521 .el .IP \f(CWSvPVbyte\fR 4
24522 .IX Item "SvPVbyte"
24523 .ie n .IP """SvPVbyte_nolen""" 4
24524 .el .IP \f(CWSvPVbyte_nolen\fR 4
24525 .IX Item "SvPVbyte_nolen"
24526 .ie n .IP """SvPVbyte_nomg""" 4
24527 .el .IP \f(CWSvPVbyte_nomg\fR 4
24528 .IX Item "SvPVbyte_nomg"
24529 .ie n .IP """SvPVbyte_or_null""" 4
24530 .el .IP \f(CWSvPVbyte_or_null\fR 4
24531 .IX Item "SvPVbyte_or_null"
24532 .ie n .IP """SvPVbyte_or_null_nomg""" 4
24533 .el .IP \f(CWSvPVbyte_or_null_nomg\fR 4
24534 .IX Item "SvPVbyte_or_null_nomg"
24535 .ie n .IP """SvPVbytex""" 4
24536 .el .IP \f(CWSvPVbytex\fR 4
24537 .IX Item "SvPVbytex"
24538 .ie n .IP """SvPVbytex_nolen""" 4
24539 .el .IP \f(CWSvPVbytex_nolen\fR 4
24540 .IX Item "SvPVbytex_nolen"
24541 .ie n .IP """SvPVutf8""" 4
24542 .el .IP \f(CWSvPVutf8\fR 4
24543 .IX Item "SvPVutf8"
24544 .ie n .IP """SvPVutf8_nolen""" 4
24545 .el .IP \f(CWSvPVutf8_nolen\fR 4
24546 .IX Item "SvPVutf8_nolen"
24547 .ie n .IP """SvPVutf8_nomg""" 4
24548 .el .IP \f(CWSvPVutf8_nomg\fR 4
24549 .IX Item "SvPVutf8_nomg"
24550 .ie n .IP """SvPVutf8_or_null""" 4
24551 .el .IP \f(CWSvPVutf8_or_null\fR 4
24552 .IX Item "SvPVutf8_or_null"
24553 .ie n .IP """SvPVutf8_or_null_nomg""" 4
24554 .el .IP \f(CWSvPVutf8_or_null_nomg\fR 4
24555 .IX Item "SvPVutf8_or_null_nomg"
24556 .ie n .IP """SvPVutf8x""" 4
24557 .el .IP \f(CWSvPVutf8x\fR 4
24558 .IX Item "SvPVutf8x"
24559 .ie n .IP """SvPVx""" 4
24560 .el .IP \f(CWSvPVx\fR 4
24561 .IX Item "SvPVx"
24562 .ie n .IP """SvPVx_const""" 4
24563 .el .IP \f(CWSvPVx_const\fR 4
24564 .IX Item "SvPVx_const"
24565 .ie n .IP """SvPVx_nolen""" 4
24566 .el .IP \f(CWSvPVx_nolen\fR 4
24567 .IX Item "SvPVx_nolen"
24568 .ie n .IP """SvPVx_nolen_const""" 4
24569 .el .IP \f(CWSvPVx_nolen_const\fR 4
24570 .IX Xref "SvPV SvPV_const SvPV_flags SvPV_flags_const SvPV_flags_mutable SvPV_mutable SvPV_nolen SvPV_nolen_const SvPV_nomg SvPV_nomg_const SvPV_nomg_const_nolen SvPV_nomg_nolen SvPVbyte SvPVbyte_nolen SvPVbyte_nomg SvPVbyte_or_null SvPVbyte_or_null_nomg SvPVbytex SvPVbytex_nolen SvPVutf8 SvPVutf8_nolen SvPVutf8_nomg SvPVutf8_or_null SvPVutf8_or_null_nomg SvPVutf8x SvPVx SvPVx_const SvPVx_nolen SvPVx_nolen_const"
24571 .IX Item "SvPVx_nolen_const"
24572 .PD
24573 These each return a pointer to the string in \f(CW\*(C`sv\*(C'\fR, or a stringified form of
24574 \&\f(CW\*(C`sv\*(C'\fR if it does not contain a string. The SV may cache the stringified
24575 version becoming \f(CW\*(C`SvPOK\*(C'\fR.
24576 .Sp
24577 This is a very basic and common operation, so there are lots of slightly
24578 different versions of it.
24579 .Sp
24580 Note that there is no guarantee that the return value of \f(CWSvPV(sv)\fR, for
24581 example, is equal to \f(CWSvPVX(sv)\fR, or that \f(CWSvPVX(sv)\fR contains valid data, or
24582 that successive calls to \f(CWSvPV(sv)\fR (or another of these forms) will return
24583 the same pointer value each time. This is due to the way that things like
24584 overloading and Copy-On-Write are handled. In these cases, the return value
24585 may point to a temporary buffer or similar. If you absolutely need the
24586 \&\f(CW\*(C`SvPVX\*(C'\fR field to be valid (for example, if you intend to write to it), then
24587 see \f(CW"SvPV_force"\fR.
24588 .Sp
24589 The differences between the forms are:
24590 .Sp
24591 The forms with neither \f(CW\*(C`byte\*(C'\fR nor \f(CW\*(C`utf8\*(C'\fR in their names (e.g., \f(CW\*(C`SvPV\*(C'\fR or
24592 \&\f(CW\*(C`SvPV_nolen\*(C'\fR) can expose the SV's internal string buffer. If
24593 that buffer consists entirely of bytes 0\-255 and includes any bytes above
24594 127, then you \fBMUST\fR consult \f(CW\*(C`SvUTF8\*(C'\fR to determine the actual code points
24595 the string is meant to contain. Generally speaking, it is probably safer to
24596 prefer \f(CW\*(C`SvPVbyte\*(C'\fR, \f(CW\*(C`SvPVutf8\*(C'\fR, and the like. See
24597 "How do I pass a Perl string to a C library?" in perlguts for more details.
24598 .Sp
24599 The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter
24600 to specify to process 'get' magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip
24601 \&'get' magic (by clearing it). The other forms process 'get' magic, except for
24602 the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip 'get' magic.
24603 .Sp
24604 The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte
24605 length of the resultant string (these are macros, so don't use \f(CW&len\fR).
24606 .Sp
24607 The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don't have a \f(CW\*(C`len\*(C'\fR
24608 parameter. They should be used only when it is known that the PV is a C
24609 string, terminated by a NUL byte, and without intermediate NUL characters; or
24610 when you don't care about its length.
24611 .Sp
24612 The forms with \f(CW\*(C`const\*(C'\fR in their names return \f(CW\*(C`const\ char\ *\*(C'\fR so that the
24613 compiler will hopefully complain if you were to try to modify the contents of
24614 the string (unless you cast away const yourself).
24615 .Sp
24616 The other forms return a mutable pointer so that the string is modifiable by
24617 the caller; this is emphasized for the ones with \f(CW\*(C`mutable\*(C'\fR in their names.
24618 .Sp
24619 As of 5.38, all forms are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR exactly once. For
24620 earlier Perls, use a form whose name ends with \f(CW\*(C`x\*(C'\fR for single evaluation.
24621 .Sp
24622 \&\f(CW\*(C`SvPVutf8\*(C'\fR is like \f(CW\*(C`SvPV\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to UTF\-8 first if not already
24623 UTF\-8. Similarly, the other forms with \f(CW\*(C`utf8\*(C'\fR in their names correspond to
24624 their respective forms without.
24625 .Sp
24626 \&\f(CW\*(C`SvPVutf8_or_null\*(C'\fR and \f(CW\*(C`SvPVutf8_or_null_nomg\*(C'\fR don't have corresponding
24627 non\-\f(CW\*(C`utf8\*(C'\fR forms. Instead they are like \f(CW\*(C`SvPVutf8_nomg\*(C'\fR, but when \f(CW\*(C`sv\*(C'\fR is
24628 undef, they return \f(CW\*(C`NULL\*(C'\fR.
24629 .Sp
24630 \&\f(CW\*(C`SvPVbyte\*(C'\fR is like \f(CW\*(C`SvPV\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to byte representation first if
24631 currently encoded as UTF\-8. If \f(CW\*(C`sv\*(C'\fR cannot be downgraded from UTF\-8, it
24632 croaks. Similarly, the other forms with \f(CW\*(C`byte\*(C'\fR in their names correspond to
24633 their respective forms without.
24634 .Sp
24635 \&\f(CW\*(C`SvPVbyte_or_null\*(C'\fR doesn't have a corresponding non\-\f(CW\*(C`byte\*(C'\fR form. Instead it
24636 is like \f(CW\*(C`SvPVbyte\*(C'\fR, but when \f(CW\*(C`sv\*(C'\fR is undef, it returns \f(CW\*(C`NULL\*(C'\fR.
24637 .RS 4
24638 .Sp
24639 .Vb 10
24640 \& char* SvPV (SV* sv, STRLEN len)
24641 \& const char* SvPV_const (SV* sv, STRLEN len)
24642 \& char* SvPV_flags (SV* sv, STRLEN len, U32 flags)
24643 \& const char* SvPV_flags_const (SV* sv, STRLEN len, U32 flags)
24644 \& char* SvPV_flags_mutable (SV* sv, STRLEN len, U32 flags)
24645 \& char* SvPV_mutable (SV* sv, STRLEN len)
24646 \& char* SvPV_nolen (SV* sv)
24647 \& const char* SvPV_nolen_const (SV* sv)
24648 \& char* SvPV_nomg (SV* sv, STRLEN len)
24649 \& const char* SvPV_nomg_const (SV* sv, STRLEN len)
24650 \& const char* SvPV_nomg_const_nolen(SV* sv)
24651 \& char* SvPV_nomg_nolen (SV* sv)
24652 \& char* SvPVbyte (SV* sv, STRLEN len)
24653 \& char* SvPVbyte_nolen (SV* sv)
24654 \& char* SvPVbyte_nomg (SV* sv, STRLEN len)
24655 \& char* SvPVbyte_or_null (SV* sv, STRLEN len)
24656 \& char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
24657 \& char* SvPVbytex (SV* sv, STRLEN len)
24658 \& char* SvPVbytex_nolen (SV* sv)
24659 \& char* SvPVutf8 (SV* sv, STRLEN len)
24660 \& char* SvPVutf8_nolen (SV* sv)
24661 \& char* SvPVutf8_nomg (SV* sv, STRLEN len)
24662 \& char* SvPVutf8_or_null (SV* sv, STRLEN len)
24663 \& char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
24664 \& char* SvPVutf8x (SV* sv, STRLEN len)
24665 \& char* SvPVx (SV* sv, STRLEN len)
24666 \& const char* SvPVx_const (SV* sv, STRLEN len)
24667 \& char* SvPVx_nolen (SV* sv)
24668 \& const char* SvPVx_nolen_const (SV* sv)
24669 .Ve
24670 .RE
24671 .RS 4
24672 .RE
24673 .ie n .IP """sv_2pv""" 4
24674 .el .IP \f(CWsv_2pv\fR 4
24675 .IX Item "sv_2pv"
24676 .PD 0
24677 .ie n .IP """sv_2pv_flags""" 4
24678 .el .IP \f(CWsv_2pv_flags\fR 4
24679 .IX Xref "sv_2pv sv_2pv_flags"
24680 .IX Item "sv_2pv_flags"
24681 .PD
24682 These implement the various forms of the "\f(CW\*(C`SvPV\*(C'\fR" in perlapi macros.
24683 The macros are the preferred interface.
24684 .Sp
24685 These return a pointer to the string value of an SV (coercing it to a string if
24686 necessary), and set \f(CW*lp\fR to its length in bytes.
24687 .Sp
24688 The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes 'get' magic; and
24689 \&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains
24690 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
24691 .RS 4
24692 .Sp
24693 .Vb 3
24694 \& char * sv_2pv (SV *sv, STRLEN *lp)
24695 \& char * sv_2pv_flags(SV * const sv, STRLEN * const lp,
24696 \& const U32 flags)
24697 .Ve
24698 .RE
24699 .RS 4
24700 .RE
24701 .ie n .IP """sv_2pvbyte""" 4
24702 .el .IP \f(CWsv_2pvbyte\fR 4
24703 .IX Item "sv_2pvbyte"
24704 .PD 0
24705 .ie n .IP """sv_2pvbyte_flags""" 4
24706 .el .IP \f(CWsv_2pvbyte_flags\fR 4
24707 .IX Xref "sv_2pvbyte sv_2pvbyte_flags"
24708 .IX Item "sv_2pvbyte_flags"
24709 .PD
24710 These implement the various forms of the "\f(CW\*(C`SvPVbyte\*(C'\fR" in perlapi macros.
24711 The macros are the preferred interface.
24712 .Sp
24713 These return a pointer to the byte-encoded representation of the SV, and set
24714 \&\f(CW*lp\fR to its length. If the SV is marked as being encoded as UTF\-8, it will
24715 be downgraded, if possible, to a byte string. If the SV cannot be downgraded,
24716 they croak.
24717 .Sp
24718 The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes 'get' magic; and
24719 \&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains
24720 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
24721 .RS 4
24722 .Sp
24723 .Vb 3
24724 \& char * sv_2pvbyte (SV *sv, STRLEN * const lp)
24725 \& char * sv_2pvbyte_flags(SV *sv, STRLEN * const lp,
24726 \& const U32 flags)
24727 .Ve
24728 .RE
24729 .RS 4
24730 .RE
24731 .ie n .IP """SvPVCLEAR""" 4
24732 .el .IP \f(CWSvPVCLEAR\fR 4
24733 .IX Xref "SvPVCLEAR"
24734 .IX Item "SvPVCLEAR"
24735 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
24736 properly null terminated. Equivalent to sv_setpvs(""), but more efficient.
24737 .RS 4
24738 .Sp
24739 .Vb 1
24740 \& char * SvPVCLEAR(SV* sv)
24741 .Ve
24742 .RE
24743 .RS 4
24744 .RE
24745 .ie n .IP """SvPVCLEAR_FRESH""" 4
24746 .el .IP \f(CWSvPVCLEAR_FRESH\fR 4
24747 .IX Xref "SvPVCLEAR_FRESH"
24748 .IX Item "SvPVCLEAR_FRESH"
24749 Like SvPVCLEAR, but optimized for newly-minted SVt_PV/PVIV/PVNV/PVMG
24750 that already have a PV buffer allocated, but no SvTHINKFIRST.
24751 .RS 4
24752 .Sp
24753 .Vb 1
24754 \& char * SvPVCLEAR_FRESH(SV* sv)
24755 .Ve
24756 .RE
24757 .RS 4
24758 .RE
24759 .ie n .IP """SvPV_force""" 4
24760 .el .IP \f(CWSvPV_force\fR 4
24761 .IX Item "SvPV_force"
24762 .PD 0
24763 .ie n .IP """SvPV_force_flags""" 4
24764 .el .IP \f(CWSvPV_force_flags\fR 4
24765 .IX Item "SvPV_force_flags"
24766 .ie n .IP """SvPV_force_flags_mutable""" 4
24767 .el .IP \f(CWSvPV_force_flags_mutable\fR 4
24768 .IX Item "SvPV_force_flags_mutable"
24769 .ie n .IP """SvPV_force_flags_nolen""" 4
24770 .el .IP \f(CWSvPV_force_flags_nolen\fR 4
24771 .IX Item "SvPV_force_flags_nolen"
24772 .ie n .IP """SvPV_force_mutable""" 4
24773 .el .IP \f(CWSvPV_force_mutable\fR 4
24774 .IX Item "SvPV_force_mutable"
24775 .ie n .IP """SvPV_force_nolen""" 4
24776 .el .IP \f(CWSvPV_force_nolen\fR 4
24777 .IX Item "SvPV_force_nolen"
24778 .ie n .IP """SvPV_force_nomg""" 4
24779 .el .IP \f(CWSvPV_force_nomg\fR 4
24780 .IX Item "SvPV_force_nomg"
24781 .ie n .IP """SvPV_force_nomg_nolen""" 4
24782 .el .IP \f(CWSvPV_force_nomg_nolen\fR 4
24783 .IX Item "SvPV_force_nomg_nolen"
24784 .ie n .IP """SvPVbyte_force""" 4
24785 .el .IP \f(CWSvPVbyte_force\fR 4
24786 .IX Item "SvPVbyte_force"
24787 .ie n .IP """SvPVbytex_force""" 4
24788 .el .IP \f(CWSvPVbytex_force\fR 4
24789 .IX Item "SvPVbytex_force"
24790 .ie n .IP """SvPVutf8_force""" 4
24791 .el .IP \f(CWSvPVutf8_force\fR 4
24792 .IX Item "SvPVutf8_force"
24793 .ie n .IP """SvPVutf8x_force""" 4
24794 .el .IP \f(CWSvPVutf8x_force\fR 4
24795 .IX Item "SvPVutf8x_force"
24796 .ie n .IP """SvPVx_force""" 4
24797 .el .IP \f(CWSvPVx_force\fR 4
24798 .IX Xref "SvPV_force SvPV_force_flags SvPV_force_flags_mutable SvPV_force_flags_nolen SvPV_force_mutable SvPV_force_nolen SvPV_force_nomg SvPV_force_nomg_nolen SvPVbyte_force SvPVbytex_force SvPVutf8_force SvPVutf8x_force SvPVx_force"
24799 .IX Item "SvPVx_force"
24800 .PD
24801 These are like \f(CW"SvPV"\fR, returning the string in the SV, but will force the
24802 SV into containing a string (\f(CW"SvPOK"\fR), and only a string
24803 (\f(CW"SvPOK_only"\fR), by hook or by crook. You need to use one of these
24804 \&\f(CW\*(C`force\*(C'\fR routines if you are going to update the \f(CW"SvPVX"\fR directly.
24805 .Sp
24806 Note that coercing an arbitrary scalar into a plain PV will potentially
24807 strip useful data from it. For example if the SV was \f(CW\*(C`SvROK\*(C'\fR, then the
24808 referent will have its reference count decremented, and the SV itself may
24809 be converted to an \f(CW\*(C`SvPOK\*(C'\fR scalar with a string buffer containing a value
24810 such as \f(CW"ARRAY(0x1234)"\fR.
24811 .Sp
24812 The differences between the forms are:
24813 .Sp
24814 The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter
24815 to specify to perform 'get' magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip
24816 \&'get' magic (by clearing it). The other forms do perform 'get' magic, except
24817 for the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip 'get' magic.
24818 .Sp
24819 The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte
24820 length of the resultant string (these are macros, so don't use \f(CW&len\fR).
24821 .Sp
24822 The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don't have a \f(CW\*(C`len\*(C'\fR
24823 parameter. They should be used only when it is known that the PV is a C
24824 string, terminated by a NUL byte, and without intermediate NUL characters; or
24825 when you don't care about its length.
24826 .Sp
24827 The forms with \f(CW\*(C`mutable\*(C'\fR in their names are effectively the same as those without,
24828 but the name emphasizes that the string is modifiable by the caller, which it is
24829 in all the forms.
24830 .Sp
24831 \&\f(CW\*(C`SvPVutf8_force\*(C'\fR is like \f(CW\*(C`SvPV_force\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to UTF\-8 first if
24832 not already UTF\-8.
24833 .Sp
24834 \&\f(CW\*(C`SvPVutf8x_force\*(C'\fR is like \f(CW\*(C`SvPVutf8_force\*(C'\fR, but guarantees to evaluate \f(CW\*(C`sv\*(C'\fR
24835 only once; use the more efficient \f(CW\*(C`SvPVutf8_force\*(C'\fR otherwise.
24836 .Sp
24837 \&\f(CW\*(C`SvPVbyte_force\*(C'\fR is like \f(CW\*(C`SvPV_force\*(C'\fR, but converts \f(CW\*(C`sv\*(C'\fR to byte
24838 representation first if currently encoded as UTF\-8. If the SV cannot be
24839 downgraded from UTF\-8, this croaks.
24840 .Sp
24841 \&\f(CW\*(C`SvPVbytex_force\*(C'\fR is like \f(CW\*(C`SvPVbyte_force\*(C'\fR, but guarantees to evaluate \f(CW\*(C`sv\*(C'\fR
24842 only once; use the more efficient \f(CW\*(C`SvPVbyte_force\*(C'\fR otherwise.
24843 .RS 4
24844 .Sp
24845 .Vb 10
24846 \& char* SvPV_force (SV* sv, STRLEN len)
24847 \& char* SvPV_force_flags (SV * sv, STRLEN len, U32 flags)
24848 \& char* SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
24849 \& char* SvPV_force_flags_nolen (SV * sv, U32 flags)
24850 \& char* SvPV_force_mutable (SV * sv, STRLEN len)
24851 \& char* SvPV_force_nolen (SV* sv)
24852 \& char* SvPV_force_nomg (SV* sv, STRLEN len)
24853 \& char* SvPV_force_nomg_nolen (SV * sv)
24854 \& char* SvPVbyte_force (SV * sv, STRLEN len)
24855 \& char* SvPVbytex_force (SV * sv, STRLEN len)
24856 \& char* SvPVutf8_force (SV * sv, STRLEN len)
24857 \& char* SvPVutf8x_force (SV * sv, STRLEN len)
24858 \& char* SvPVx_force (SV* sv, STRLEN len)
24859 .Ve
24860 .RE
24861 .RS 4
24862 .RE
24863 .ie n .IP """SvPV_free""" 4
24864 .el .IP \f(CWSvPV_free\fR 4
24865 .IX Xref "SvPV_free"
24866 .IX Item "SvPV_free"
24867 Frees the PV buffer in \f(CW\*(C`sv\*(C'\fR, leaving things in a precarious state, so should
24868 only be used as part of a larger operation
24869 .RS 4
24870 .Sp
24871 .Vb 1
24872 \& void SvPV_free(SV * sv)
24873 .Ve
24874 .RE
24875 .RS 4
24876 .RE
24877 .ie n .IP """sv_pvn_force_flags""" 4
24878 .el .IP \f(CWsv_pvn_force_flags\fR 4
24879 .IX Xref "sv_pvn_force_flags"
24880 .IX Item "sv_pvn_force_flags"
24881 Get a sensible string out of the SV somehow.
24882 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, will \f(CW"mg_get"\fR on \f(CW\*(C`sv\*(C'\fR if
24883 appropriate, else not. \f(CW\*(C`sv_pvn_force\*(C'\fR and \f(CW\*(C`sv_pvn_force_nomg\*(C'\fR are
24884 implemented in terms of this function.
24885 You normally want to use the various wrapper macros instead: see
24886 \&\f(CW"SvPV_force"\fR and \f(CW"SvPV_force_nomg"\fR.
24887 .RS 4
24888 .Sp
24889 .Vb 2
24890 \& char * sv_pvn_force_flags(SV * const sv, STRLEN * const lp,
24891 \& const U32 flags)
24892 .Ve
24893 .RE
24894 .RS 4
24895 .RE
24896 .ie n .IP """SvPV_renew""" 4
24897 .el .IP \f(CWSvPV_renew\fR 4
24898 .IX Xref "SvPV_renew"
24899 .IX Item "SvPV_renew"
24900 Low level micro optimization of \f(CW"SvGROW"\fR. It is generally better to use
24901 \&\f(CW\*(C`SvGROW\*(C'\fR instead. This is because \f(CW\*(C`SvPV_renew\*(C'\fR ignores potential issues that
24902 \&\f(CW\*(C`SvGROW\*(C'\fR handles. \f(CW\*(C`sv\*(C'\fR needs to have a real \f(CW\*(C`PV\*(C'\fR that is unencumbered by
24903 things like COW. Using \f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR or
24904 \&\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR before calling this should clean it up, but
24905 why not just use \f(CW\*(C`SvGROW\*(C'\fR if you're not sure about the provenance?
24906 .RS 4
24907 .Sp
24908 .Vb 1
24909 \& void SvPV_renew(SV* sv, STRLEN len)
24910 .Ve
24911 .RE
24912 .RS 4
24913 .RE
24914 .ie n .IP """SvPV_set""" 4
24915 .el .IP \f(CWSvPV_set\fR 4
24916 .IX Xref "SvPV_set"
24917 .IX Item "SvPV_set"
24918 This is probably not what you want to use, you probably wanted
24919 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
24920 .Sp
24921 Set the value of the PV pointer in \f(CW\*(C`sv\*(C'\fR to the Perl allocated
24922 \&\f(CW\*(C`NUL\*(C'\fR\-terminated string \f(CW\*(C`val\*(C'\fR. See also \f(CW"SvIV_set"\fR.
24923 .Sp
24924 Remember to free the previous PV buffer. There are many things to check.
24925 Beware that the existing pointer may be involved in copy-on-write or other
24926 mischief, so do \f(CWSvOOK_off(sv)\fR and use \f(CW\*(C`sv_force_normal\*(C'\fR or
24927 \&\f(CW\*(C`SvPV_force\*(C'\fR (or check the \f(CW\*(C`SvIsCOW\*(C'\fR flag) first to make sure this
24928 modification is safe. Then finally, if it is not a COW, call
24929 \&\f(CW"SvPV_free"\fR to free the previous PV buffer.
24930 .RS 4
24931 .Sp
24932 .Vb 1
24933 \& void SvPV_set(SV* sv, char* val)
24934 .Ve
24935 .RE
24936 .RS 4
24937 .RE
24938 .ie n .IP """SvPV_shrink_to_cur""" 4
24939 .el .IP \f(CWSvPV_shrink_to_cur\fR 4
24940 .IX Xref "SvPV_shrink_to_cur"
24941 .IX Item "SvPV_shrink_to_cur"
24942 Trim any trailing unused memory in the PV of \f(CW\*(C`sv\*(C'\fR, which needs to have a real
24943 \&\f(CW\*(C`PV\*(C'\fR that is unencumbered by things like COW. Think first before using this
24944 functionality. Is the space saving really worth giving up COW? Will the
24945 needed size of \f(CW\*(C`sv\*(C'\fR stay the same?
24946 .Sp
24947 If the answers are both yes, then use "\f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR" or
24948 "\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" before calling this.
24949 .RS 4
24950 .Sp
24951 .Vb 1
24952 \& void SvPV_shrink_to_cur(SV* sv)
24953 .Ve
24954 .RE
24955 .RS 4
24956 .RE
24957 .ie n .IP """sv_2pvutf8""" 4
24958 .el .IP \f(CWsv_2pvutf8\fR 4
24959 .IX Item "sv_2pvutf8"
24960 .PD 0
24961 .ie n .IP """sv_2pvutf8_flags""" 4
24962 .el .IP \f(CWsv_2pvutf8_flags\fR 4
24963 .IX Xref "sv_2pvutf8 sv_2pvutf8_flags"
24964 .IX Item "sv_2pvutf8_flags"
24965 .PD
24966 These implement the various forms of the "\f(CW\*(C`SvPVutf8\*(C'\fR" in perlapi macros.
24967 The macros are the preferred interface.
24968 .Sp
24969 These return a pointer to the UTF\-8\-encoded representation of the SV, and set
24970 \&\f(CW*lp\fR to its length in bytes. They may cause the SV to be upgraded to UTF\-8
24971 as a side-effect.
24972 .Sp
24973 The forms differ in that plain \f(CW\*(C`sv_2pvutf8\*(C'\fR always processes 'get' magic; and
24974 \&\f(CW\*(C`sv_2pvutf8_flags\*(C'\fR processes 'get' magic if and only if \f(CW\*(C`flags\*(C'\fR contains
24975 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
24976 .RS 4
24977 .Sp
24978 .Vb 3
24979 \& char * sv_2pvutf8 (SV *sv, STRLEN * const lp)
24980 \& char * sv_2pvutf8_flags(SV *sv, STRLEN * const lp,
24981 \& const U32 flags)
24982 .Ve
24983 .RE
24984 .RS 4
24985 .RE
24986 .ie n .IP """SvPVX""" 4
24987 .el .IP \f(CWSvPVX\fR 4
24988 .IX Item "SvPVX"
24989 .PD 0
24990 .ie n .IP """SvPVX_const""" 4
24991 .el .IP \f(CWSvPVX_const\fR 4
24992 .IX Item "SvPVX_const"
24993 .ie n .IP """SvPVX_mutable""" 4
24994 .el .IP \f(CWSvPVX_mutable\fR 4
24995 .IX Item "SvPVX_mutable"
24996 .ie n .IP """SvPVXx""" 4
24997 .el .IP \f(CWSvPVXx\fR 4
24998 .IX Xref "SvPVX SvPVX_const SvPVX_mutable SvPVXx"
24999 .IX Item "SvPVXx"
25000 .PD
25001 These return a pointer to the physical string in the SV. The SV must contain a
25002 string. Prior to 5.9.3 it is not safe to execute these unless the SV's
25003 type >= \f(CW\*(C`SVt_PV\*(C'\fR.
25004 .Sp
25005 These are also used to store the name of an autoloaded subroutine in an XS
25006 AUTOLOAD routine. See "Autoloading with XSUBs" in perlguts.
25007 .Sp
25008 \&\f(CW\*(C`SvPVXx\*(C'\fR is identical to \f(CW\*(C`SvPVX\*(C'\fR.
25009 .Sp
25010 \&\f(CW\*(C`SvPVX_mutable\*(C'\fR is merely a synonym for \f(CW\*(C`SvPVX\*(C'\fR, but its name emphasizes that
25011 the string is modifiable by the caller.
25012 .Sp
25013 \&\f(CW\*(C`SvPVX_const\*(C'\fR differs in that the return value has been cast so that the
25014 compiler will complain if you were to try to modify the contents of the string,
25015 (unless you cast away const yourself).
25016 .RS 4
25017 .Sp
25018 .Vb 4
25019 \& char* SvPVX (SV* sv)
25020 \& const char* SvPVX_const (SV* sv)
25021 \& char* SvPVX_mutable(SV* sv)
25022 \& char* SvPVXx (SV* sv)
25023 .Ve
25024 .RE
25025 .RS 4
25026 .RE
25027 .ie n .IP """SvPVXtrue""" 4
25028 .el .IP \f(CWSvPVXtrue\fR 4
25029 .IX Xref "SvPVXtrue"
25030 .IX Item "SvPVXtrue"
25031 Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR contains a PV that is considered
25032 TRUE. FALSE is returned if \f(CW\*(C`sv\*(C'\fR doesn't contain a PV, or if the PV it does
25033 contain is zero length, or consists of just the single character '0'. Every
25034 other PV value is considered TRUE.
25035 .Sp
25036 As of Perl v5.37.1, \f(CW\*(C`sv\*(C'\fR is evaluated exactly once; in earlier releases, it
25037 could be evaluated more than once.
25038 .RS 4
25039 .Sp
25040 .Vb 1
25041 \& bool SvPVXtrue(SV *sv)
25042 .Ve
25043 .RE
25044 .RS 4
25045 .RE
25046 .ie n .IP """SvREADONLY""" 4
25047 .el .IP \f(CWSvREADONLY\fR 4
25048 .IX Xref "SvREADONLY"
25049 .IX Item "SvREADONLY"
25050 Returns true if the argument is readonly, otherwise returns false.
25051 Exposed to perl code via \fBInternals::SvREADONLY()\fR.
25052 .RS 4
25053 .Sp
25054 .Vb 1
25055 \& U32 SvREADONLY(SV* sv)
25056 .Ve
25057 .RE
25058 .RS 4
25059 .RE
25060 .ie n .IP """SvREADONLY_off""" 4
25061 .el .IP \f(CWSvREADONLY_off\fR 4
25062 .IX Xref "SvREADONLY_off"
25063 .IX Item "SvREADONLY_off"
25064 Mark an object as not-readonly. Exactly what this mean depends on the
25065 object type. Exposed to perl code via \fBInternals::SvREADONLY()\fR.
25066 .RS 4
25067 .Sp
25068 .Vb 1
25069 \& U32 SvREADONLY_off(SV* sv)
25070 .Ve
25071 .RE
25072 .RS 4
25073 .RE
25074 .ie n .IP """SvREADONLY_on""" 4
25075 .el .IP \f(CWSvREADONLY_on\fR 4
25076 .IX Xref "SvREADONLY_on"
25077 .IX Item "SvREADONLY_on"
25078 Mark an object as readonly. Exactly what this means depends on the object
25079 type. Exposed to perl code via \fBInternals::SvREADONLY()\fR.
25080 .RS 4
25081 .Sp
25082 .Vb 1
25083 \& U32 SvREADONLY_on(SV* sv)
25084 .Ve
25085 .RE
25086 .RS 4
25087 .RE
25088 .ie n .IP """sv_ref""" 4
25089 .el .IP \f(CWsv_ref\fR 4
25090 .IX Xref "sv_ref"
25091 .IX Item "sv_ref"
25092 Returns a SV describing what the SV passed in is a reference to.
25093 .Sp
25094 dst can be a SV to be set to the description or NULL, in which case a
25095 mortal SV is returned.
25096 .Sp
25097 If ob is true and the SV is blessed, the description is the class
25098 name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
25099 .RS 4
25100 .Sp
25101 .Vb 1
25102 \& SV * sv_ref(SV *dst, const SV * const sv, const int ob)
25103 .Ve
25104 .RE
25105 .RS 4
25106 .RE
25107 .ie n .IP """SvREFCNT""" 4
25108 .el .IP \f(CWSvREFCNT\fR 4
25109 .IX Xref "SvREFCNT"
25110 .IX Item "SvREFCNT"
25111 Returns the value of the object's reference count. Exposed
25112 to perl code via \fBInternals::SvREFCNT()\fR.
25113 .RS 4
25114 .Sp
25115 .Vb 1
25116 \& U32 SvREFCNT(SV* sv)
25117 .Ve
25118 .RE
25119 .RS 4
25120 .RE
25121 .ie n .IP """SvREFCNT_dec""" 4
25122 .el .IP \f(CWSvREFCNT_dec\fR 4
25123 .IX Item "SvREFCNT_dec"
25124 .PD 0
25125 .ie n .IP """SvREFCNT_dec_set_NULL""" 4
25126 .el .IP \f(CWSvREFCNT_dec_set_NULL\fR 4
25127 .IX Item "SvREFCNT_dec_set_NULL"
25128 .ie n .IP """SvREFCNT_dec_ret_NULL""" 4
25129 .el .IP \f(CWSvREFCNT_dec_ret_NULL\fR 4
25130 .IX Item "SvREFCNT_dec_ret_NULL"
25131 .ie n .IP """SvREFCNT_dec_NN""" 4
25132 .el .IP \f(CWSvREFCNT_dec_NN\fR 4
25133 .IX Xref "SvREFCNT_dec SvREFCNT_dec_set_NULL SvREFCNT_dec_ret_NULL SvREFCNT_dec_NN"
25134 .IX Item "SvREFCNT_dec_NN"
25135 .PD
25136 These decrement the reference count of the given SV.
25137 .Sp
25138 \&\f(CW\*(C`SvREFCNT_dec_NN\*(C'\fR may only be used when \f(CW\*(C`sv\*(C'\fR is known to not be \f(CW\*(C`NULL\*(C'\fR.
25139 .Sp
25140 The function \f(CWSvREFCNT_dec_ret_NULL()\fR is identical to the
25141 \&\f(CWSvREFCNT_dec()\fR except it returns a NULL \f(CW\*(C`SV *\*(C'\fR. It is used by
25142 \&\f(CWSvREFCNT_dec_set_NULL()\fR which is a macro which will, when passed a
25143 non-NULL argument, decrement the reference count of its argument and
25144 then set it to NULL. You can replace code of the following form:
25145 .Sp
25146 .Vb 4
25147 \& if (sv) {
25148 \& SvREFCNT_dec_NN(sv);
25149 \& sv = NULL;
25150 \& }
25151 .Ve
25152 .Sp
25153 with
25154 .Sp
25155 .Vb 1
25156 \& SvREFCNT_dec_set_NULL(sv);
25157 .Ve
25158 .RS 4
25159 .Sp
25160 .Vb 4
25161 \& void SvREFCNT_dec (SV *sv)
25162 \& void SvREFCNT_dec_set_NULL(SV *sv)
25163 \& SV * SvREFCNT_dec_ret_NULL(SV *sv)
25164 \& void SvREFCNT_dec_NN (SV *sv)
25165 .Ve
25166 .RE
25167 .RS 4
25168 .RE
25169 .ie n .IP """SvREFCNT_inc""" 4
25170 .el .IP \f(CWSvREFCNT_inc\fR 4
25171 .IX Item "SvREFCNT_inc"
25172 .PD 0
25173 .ie n .IP """SvREFCNT_inc_NN""" 4
25174 .el .IP \f(CWSvREFCNT_inc_NN\fR 4
25175 .IX Item "SvREFCNT_inc_NN"
25176 .ie n .IP """SvREFCNT_inc_simple""" 4
25177 .el .IP \f(CWSvREFCNT_inc_simple\fR 4
25178 .IX Item "SvREFCNT_inc_simple"
25179 .ie n .IP """SvREFCNT_inc_simple_NN""" 4
25180 .el .IP \f(CWSvREFCNT_inc_simple_NN\fR 4
25181 .IX Item "SvREFCNT_inc_simple_NN"
25182 .ie n .IP """SvREFCNT_inc_simple_void""" 4
25183 .el .IP \f(CWSvREFCNT_inc_simple_void\fR 4
25184 .IX Item "SvREFCNT_inc_simple_void"
25185 .ie n .IP """SvREFCNT_inc_simple_void_NN""" 4
25186 .el .IP \f(CWSvREFCNT_inc_simple_void_NN\fR 4
25187 .IX Item "SvREFCNT_inc_simple_void_NN"
25188 .ie n .IP """SvREFCNT_inc_void""" 4
25189 .el .IP \f(CWSvREFCNT_inc_void\fR 4
25190 .IX Item "SvREFCNT_inc_void"
25191 .ie n .IP """SvREFCNT_inc_void_NN""" 4
25192 .el .IP \f(CWSvREFCNT_inc_void_NN\fR 4
25193 .IX Xref "SvREFCNT_inc SvREFCNT_inc_NN SvREFCNT_inc_simple SvREFCNT_inc_simple_NN SvREFCNT_inc_simple_void SvREFCNT_inc_simple_void_NN SvREFCNT_inc_void SvREFCNT_inc_void_NN"
25194 .IX Item "SvREFCNT_inc_void_NN"
25195 .PD
25196 These all increment the reference count of the given SV.
25197 The ones without \f(CW\*(C`void\*(C'\fR in their names return the SV.
25198 .Sp
25199 \&\f(CW\*(C`SvREFCNT_inc\*(C'\fR is the base operation; the rest are optimizations if various
25200 input constraints are known to be true; hence, all can be replaced with
25201 \&\f(CW\*(C`SvREFCNT_inc\*(C'\fR.
25202 .Sp
25203 \&\f(CW\*(C`SvREFCNT_inc_NN\*(C'\fR can only be used if you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. Since we
25204 don't have to check the NULLness, it's faster and smaller.
25205 .Sp
25206 \&\f(CW\*(C`SvREFCNT_inc_void\*(C'\fR can only be used if you don't need the
25207 return value. The macro doesn't need to return a meaningful value.
25208 .Sp
25209 \&\f(CW\*(C`SvREFCNT_inc_void_NN\*(C'\fR can only be used if you both don't need the return
25210 value, and you know that \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. The macro doesn't need to
25211 return a meaningful value, or check for NULLness, so it's smaller and faster.
25212 .Sp
25213 \&\f(CW\*(C`SvREFCNT_inc_simple\*(C'\fR can only be used with expressions without side
25214 effects. Since we don't have to store a temporary value, it's faster.
25215 .Sp
25216 \&\f(CW\*(C`SvREFCNT_inc_simple_NN\*(C'\fR can only be used with expressions without side
25217 effects and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. Since we don't have to store a
25218 temporary value, nor check for NULLness, it's faster and smaller.
25219 .Sp
25220 \&\f(CW\*(C`SvREFCNT_inc_simple_void\*(C'\fR can only be used with expressions without side
25221 effects and you don't need the return value.
25222 .Sp
25223 \&\f(CW\*(C`SvREFCNT_inc_simple_void_NN\*(C'\fR can only be used with expressions without side
25224 effects, you don't need the return value, and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR.
25225 .RS 4
25226 .Sp
25227 .Vb 8
25228 \& SV * SvREFCNT_inc (SV *sv)
25229 \& SV * SvREFCNT_inc_NN (SV *sv)
25230 \& SV* SvREFCNT_inc_simple (SV* sv)
25231 \& SV* SvREFCNT_inc_simple_NN (SV* sv)
25232 \& void SvREFCNT_inc_simple_void (SV* sv)
25233 \& void SvREFCNT_inc_simple_void_NN(SV* sv)
25234 \& void SvREFCNT_inc_void (SV *sv)
25235 \& void SvREFCNT_inc_void_NN (SV* sv)
25236 .Ve
25237 .RE
25238 .RS 4
25239 .RE
25240 .ie n .IP """sv_reftype""" 4
25241 .el .IP \f(CWsv_reftype\fR 4
25242 .IX Xref "sv_reftype"
25243 .IX Item "sv_reftype"
25244 Returns a string describing what the SV is a reference to.
25245 .Sp
25246 If ob is true and the SV is blessed, the string is the class name,
25247 otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
25248 .RS 4
25249 .Sp
25250 .Vb 1
25251 \& const char * sv_reftype(const SV * const sv, const int ob)
25252 .Ve
25253 .RE
25254 .RS 4
25255 .RE
25256 .ie n .IP """sv_replace""" 4
25257 .el .IP \f(CWsv_replace\fR 4
25258 .IX Xref "sv_replace"
25259 .IX Item "sv_replace"
25260 Make the first argument a copy of the second, then delete the original.
25261 The target SV physically takes over ownership of the body of the source SV
25262 and inherits its flags; however, the target keeps any magic it owns,
25263 and any magic in the source is discarded.
25264 Note that this is a rather specialist SV copying operation; most of the
25265 time you'll want to use \f(CW\*(C`sv_setsv\*(C'\fR or one of its many macro front-ends.
25266 .RS 4
25267 .Sp
25268 .Vb 1
25269 \& void sv_replace(SV * const sv, SV * const nsv)
25270 .Ve
25271 .RE
25272 .RS 4
25273 .RE
25274 .ie n .IP """sv_report_used""" 4
25275 .el .IP \f(CWsv_report_used\fR 4
25276 .IX Xref "sv_report_used"
25277 .IX Item "sv_report_used"
25278 Dump the contents of all SVs not yet freed (debugging aid).
25279 .RS 4
25280 .Sp
25281 .Vb 1
25282 \& void sv_report_used()
25283 .Ve
25284 .RE
25285 .RS 4
25286 .RE
25287 .ie n .IP """sv_reset""" 4
25288 .el .IP \f(CWsv_reset\fR 4
25289 .IX Xref "sv_reset"
25290 .IX Item "sv_reset"
25291 Underlying implementation for the \f(CW\*(C`reset\*(C'\fR Perl function.
25292 Note that the perl-level function is vaguely deprecated.
25293 .RS 4
25294 .Sp
25295 .Vb 1
25296 \& void sv_reset(const char *s, HV * const stash)
25297 .Ve
25298 .RE
25299 .RS 4
25300 .RE
25301 .ie n .IP """SvROK""" 4
25302 .el .IP \f(CWSvROK\fR 4
25303 .IX Xref "SvROK"
25304 .IX Item "SvROK"
25305 Tests if the SV is an RV.
25306 .RS 4
25307 .Sp
25308 .Vb 1
25309 \& U32 SvROK(SV* sv)
25310 .Ve
25311 .RE
25312 .RS 4
25313 .RE
25314 .ie n .IP """SvROK_off""" 4
25315 .el .IP \f(CWSvROK_off\fR 4
25316 .IX Xref "SvROK_off"
25317 .IX Item "SvROK_off"
25318 Unsets the RV status of an SV.
25319 .RS 4
25320 .Sp
25321 .Vb 1
25322 \& void SvROK_off(SV* sv)
25323 .Ve
25324 .RE
25325 .RS 4
25326 .RE
25327 .ie n .IP """SvROK_on""" 4
25328 .el .IP \f(CWSvROK_on\fR 4
25329 .IX Xref "SvROK_on"
25330 .IX Item "SvROK_on"
25331 Tells an SV that it is an RV.
25332 .RS 4
25333 .Sp
25334 .Vb 1
25335 \& void SvROK_on(SV* sv)
25336 .Ve
25337 .RE
25338 .RS 4
25339 .RE
25340 .ie n .IP """SvRV""" 4
25341 .el .IP \f(CWSvRV\fR 4
25342 .IX Xref "SvRV"
25343 .IX Item "SvRV"
25344 Dereferences an RV to return the SV.
25345 .RS 4
25346 .Sp
25347 .Vb 1
25348 \& SV* SvRV(SV* sv)
25349 .Ve
25350 .RE
25351 .RS 4
25352 .RE
25353 .ie n .IP """SvRV_set""" 4
25354 .el .IP \f(CWSvRV_set\fR 4
25355 .IX Xref "SvRV_set"
25356 .IX Item "SvRV_set"
25357 Set the value of the RV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
25358 .RS 4
25359 .Sp
25360 .Vb 1
25361 \& void SvRV_set(SV* sv, SV* val)
25362 .Ve
25363 .RE
25364 .RS 4
25365 .RE
25366 .ie n .IP """sv_rvunweaken""" 4
25367 .el .IP \f(CWsv_rvunweaken\fR 4
25368 .IX Xref "sv_rvunweaken"
25369 .IX Item "sv_rvunweaken"
25370 Unweaken a reference: Clear the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; remove
25371 the backreference to this RV from the array of backreferences
25372 associated with the target SV, increment the refcount of the target.
25373 Silently ignores \f(CW\*(C`undef\*(C'\fR and warns on non-weak references.
25374 .RS 4
25375 .Sp
25376 .Vb 1
25377 \& SV * sv_rvunweaken(SV * const sv)
25378 .Ve
25379 .RE
25380 .RS 4
25381 .RE
25382 .ie n .IP """sv_rvweaken""" 4
25383 .el .IP \f(CWsv_rvweaken\fR 4
25384 .IX Xref "sv_rvweaken"
25385 .IX Item "sv_rvweaken"
25386 Weaken a reference: set the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; give the
25387 referred-to SV \f(CW\*(C`PERL_MAGIC_backref\*(C'\fR magic if it hasn't already; and
25388 push a back-reference to this RV onto the array of backreferences
25389 associated with that magic. If the RV is magical, set magic will be
25390 called after the RV is cleared. Silently ignores \f(CW\*(C`undef\*(C'\fR and warns
25391 on already-weak references.
25392 .RS 4
25393 .Sp
25394 .Vb 1
25395 \& SV * sv_rvweaken(SV * const sv)
25396 .Ve
25397 .RE
25398 .RS 4
25399 .RE
25400 .ie n .IP """sv_setbool""" 4
25401 .el .IP \f(CWsv_setbool\fR 4
25402 .IX Item "sv_setbool"
25403 .PD 0
25404 .ie n .IP """sv_setbool_mg""" 4
25405 .el .IP \f(CWsv_setbool_mg\fR 4
25406 .IX Xref "sv_setbool sv_setbool_mg"
25407 .IX Item "sv_setbool_mg"
25408 .PD
25409 These set an SV to a true or false boolean value, upgrading first if necessary.
25410 .Sp
25411 They differ only in that \f(CW\*(C`sv_setbool_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setbool\*(C'\fR
25412 does not.
25413 .RS 4
25414 .Sp
25415 .Vb 1
25416 \& void sv_setbool(SV *sv, bool b)
25417 .Ve
25418 .RE
25419 .RS 4
25420 .RE
25421 .ie n .IP """sv_set_bool""" 4
25422 .el .IP \f(CWsv_set_bool\fR 4
25423 .IX Xref "sv_set_bool"
25424 .IX Item "sv_set_bool"
25425 Equivalent to \f(CW\*(C`sv_setsv(sv, bool_val ? &Pl_sv_yes : &PL_sv_no)\*(C'\fR, but
25426 may be made more efficient in the future. Doesn't handle set magic.
25427 .Sp
25428 The perl equivalent is \f(CW\*(C`$sv = !!$expr;\*(C'\fR.
25429 .Sp
25430 Introduced in perl 5.35.11.
25431 .RS 4
25432 .Sp
25433 .Vb 1
25434 \& void sv_set_bool(SV *sv, const bool bool_val)
25435 .Ve
25436 .RE
25437 .RS 4
25438 .RE
25439 .ie n .IP """sv_set_false""" 4
25440 .el .IP \f(CWsv_set_false\fR 4
25441 .IX Xref "sv_set_false"
25442 .IX Item "sv_set_false"
25443 Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_no)\*(C'\fR, but may be made more
25444 efficient in the future. Doesn't handle set magic.
25445 .Sp
25446 The perl equivalent is \f(CW\*(C`$sv = !1;\*(C'\fR.
25447 .Sp
25448 Introduced in perl 5.35.11.
25449 .RS 4
25450 .Sp
25451 .Vb 1
25452 \& void sv_set_false(SV *sv)
25453 .Ve
25454 .RE
25455 .RS 4
25456 .RE
25457 .ie n .IP """sv_setiv""" 4
25458 .el .IP \f(CWsv_setiv\fR 4
25459 .IX Item "sv_setiv"
25460 .PD 0
25461 .ie n .IP """sv_setiv_mg""" 4
25462 .el .IP \f(CWsv_setiv_mg\fR 4
25463 .IX Xref "sv_setiv sv_setiv_mg"
25464 .IX Item "sv_setiv_mg"
25465 .PD
25466 These copy an integer into the given SV, upgrading first if necessary.
25467 .Sp
25468 They differ only in that \f(CW\*(C`sv_setiv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setiv\*(C'\fR does
25469 not.
25470 .RS 4
25471 .Sp
25472 .Vb 2
25473 \& void sv_setiv (SV * const sv, const IV num)
25474 \& void sv_setiv_mg(SV * const sv, const IV i)
25475 .Ve
25476 .RE
25477 .RS 4
25478 .RE
25479 .ie n .IP """SvSETMAGIC""" 4
25480 .el .IP \f(CWSvSETMAGIC\fR 4
25481 .IX Xref "SvSETMAGIC"
25482 .IX Item "SvSETMAGIC"
25483 Invokes \f(CW"mg_set"\fR on an SV if it has 'set' magic. This is necessary
25484 after modifying a scalar, in case it is a magical variable like \f(CW$|\fR
25485 or a tied variable (it calls \f(CW\*(C`STORE\*(C'\fR). This macro evaluates its
25486 argument more than once.
25487 .RS 4
25488 .Sp
25489 .Vb 1
25490 \& void SvSETMAGIC(SV* sv)
25491 .Ve
25492 .RE
25493 .RS 4
25494 .RE
25495 .ie n .IP """SvSetMagicSV""" 4
25496 .el .IP \f(CWSvSetMagicSV\fR 4
25497 .IX Item "SvSetMagicSV"
25498 .PD 0
25499 .ie n .IP """SvSetMagicSV_nosteal""" 4
25500 .el .IP \f(CWSvSetMagicSV_nosteal\fR 4
25501 .IX Item "SvSetMagicSV_nosteal"
25502 .ie n .IP """SvSetSV""" 4
25503 .el .IP \f(CWSvSetSV\fR 4
25504 .IX Item "SvSetSV"
25505 .ie n .IP """SvSetSV_nosteal""" 4
25506 .el .IP \f(CWSvSetSV_nosteal\fR 4
25507 .IX Xref "SvSetMagicSV SvSetMagicSV_nosteal SvSetSV SvSetSV_nosteal"
25508 .IX Item "SvSetSV_nosteal"
25509 .PD
25510 if \f(CW\*(C`dsv\*(C'\fR is the same as \f(CW\*(C`ssv\*(C'\fR, these do nothing. Otherwise they all call
25511 some form of \f(CW"sv_setsv"\fR. They may evaluate their arguments more than
25512 once.
25513 .Sp
25514 The only differences are:
25515 .Sp
25516 \&\f(CW\*(C`SvSetMagicSV\*(C'\fR and \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR perform any required 'set' magic
25517 afterwards on the destination SV; \f(CW\*(C`SvSetSV\*(C'\fR and \f(CW\*(C`SvSetSV_nosteal\*(C'\fR do not.
25518 .Sp
25519 \&\f(CW\*(C`SvSetSV_nosteal\*(C'\fR \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR call a non-destructive version of
25520 \&\f(CW\*(C`sv_setsv\*(C'\fR.
25521 .RS 4
25522 .Sp
25523 .Vb 1
25524 \& void SvSetMagicSV(SV* dsv, SV* ssv)
25525 .Ve
25526 .RE
25527 .RS 4
25528 .RE
25529 .ie n .IP """sv_setnv""" 4
25530 .el .IP \f(CWsv_setnv\fR 4
25531 .IX Item "sv_setnv"
25532 .PD 0
25533 .ie n .IP """sv_setnv_mg""" 4
25534 .el .IP \f(CWsv_setnv_mg\fR 4
25535 .IX Xref "sv_setnv sv_setnv_mg"
25536 .IX Item "sv_setnv_mg"
25537 .PD
25538 These copy a double into the given SV, upgrading first if necessary.
25539 .Sp
25540 They differ only in that \f(CW\*(C`sv_setnv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setnv\*(C'\fR does
25541 not.
25542 .RS 4
25543 .Sp
25544 .Vb 1
25545 \& void sv_setnv(SV * const sv, const NV num)
25546 .Ve
25547 .RE
25548 .RS 4
25549 .RE
25550 .ie n .IP """sv_setpv""" 4
25551 .el .IP \f(CWsv_setpv\fR 4
25552 .IX Item "sv_setpv"
25553 .PD 0
25554 .ie n .IP """sv_setpv_mg""" 4
25555 .el .IP \f(CWsv_setpv_mg\fR 4
25556 .IX Item "sv_setpv_mg"
25557 .ie n .IP """sv_setpvn""" 4
25558 .el .IP \f(CWsv_setpvn\fR 4
25559 .IX Item "sv_setpvn"
25560 .ie n .IP """sv_setpvn_fresh""" 4
25561 .el .IP \f(CWsv_setpvn_fresh\fR 4
25562 .IX Item "sv_setpvn_fresh"
25563 .ie n .IP """sv_setpvn_mg""" 4
25564 .el .IP \f(CWsv_setpvn_mg\fR 4
25565 .IX Item "sv_setpvn_mg"
25566 .ie n .IP """sv_setpvs""" 4
25567 .el .IP \f(CWsv_setpvs\fR 4
25568 .IX Item "sv_setpvs"
25569 .ie n .IP """sv_setpvs_mg""" 4
25570 .el .IP \f(CWsv_setpvs_mg\fR 4
25571 .IX Xref "sv_setpv sv_setpv_mg sv_setpvn sv_setpvn_fresh sv_setpvn_mg sv_setpvs sv_setpvs_mg"
25572 .IX Item "sv_setpvs_mg"
25573 .PD
25574 These copy a string into the SV \f(CW\*(C`sv\*(C'\fR, making sure it is \f(CW"SvPOK_only"\fR.
25575 .Sp
25576 In the \f(CW\*(C`pvs\*(C'\fR forms, the string must be a C literal string, enclosed in double
25577 quotes.
25578 .Sp
25579 In the \f(CW\*(C`pvn\*(C'\fR forms, the first byte of the string is pointed to by \f(CW\*(C`ptr\*(C'\fR, and
25580 \&\f(CW\*(C`len\*(C'\fR indicates the number of bytes to be copied, potentially including
25581 embedded \f(CW\*(C`NUL\*(C'\fR characters.
25582 .Sp
25583 In the plain \f(CW\*(C`pv\*(C'\fR forms, \f(CW\*(C`ptr\*(C'\fR points to a NUL-terminated C string. That is,
25584 it points to the first byte of the string, and the copy proceeds up through the
25585 first encountered \f(CW\*(C`NUL\*(C'\fR byte.
25586 .Sp
25587 In the forms that take a \f(CW\*(C`ptr\*(C'\fR argument, if it is NULL, the SV will become
25588 undefined.
25589 .Sp
25590 \&\fBThe UTF\-8 flag is not changed by these functions.\fR
25591 .Sp
25592 A terminating NUL byte is guaranteed in the result.
25593 .Sp
25594 The \f(CW\*(C`_mg\*(C'\fR forms handle 'set' magic; the other forms skip all magic.
25595 .Sp
25596 \&\f(CW\*(C`sv_setpvn_fresh\*(C'\fR is a cut-down alternative to \f(CW\*(C`sv_setpvn\*(C'\fR, intended ONLY
25597 to be used with a fresh sv that has been upgraded to a SVt_PV, SVt_PVIV,
25598 SVt_PVNV, or SVt_PVMG.
25599 .RS 4
25600 .Sp
25601 .Vb 10
25602 \& void sv_setpv (SV * const sv, const char * const ptr)
25603 \& void sv_setpv_mg (SV * const sv, const char * const ptr)
25604 \& void sv_setpvn (SV * const sv, const char * const ptr,
25605 \& const STRLEN len)
25606 \& void sv_setpvn_fresh(SV * const sv, const char * const ptr,
25607 \& const STRLEN len)
25608 \& void sv_setpvn_mg (SV * const sv, const char * const ptr,
25609 \& const STRLEN len)
25610 \& void sv_setpvs (SV* sv, "literal string")
25611 \& void sv_setpvs_mg (SV* sv, "literal string")
25612 .Ve
25613 .RE
25614 .RS 4
25615 .RE
25616 .ie n .IP """sv_setpv_bufsize""" 4
25617 .el .IP \f(CWsv_setpv_bufsize\fR 4
25618 .IX Xref "sv_setpv_bufsize"
25619 .IX Item "sv_setpv_bufsize"
25620 Sets the SV to be a string of \f(CW\*(C`cur\*(C'\fR bytes length, with at least
25621 \&\f(CW\*(C`len\*(C'\fR bytes available. Ensures that there is a null byte at \f(CW\*(C`SvEND\*(C'\fR.
25622 .Sp
25623 Returns a char * pointer to the SvPV buffer.
25624 .Sp
25625 The caller must set the first \f(CW\*(C`cur\*(C'\fR bytes of \f(CW\*(C`sv\*(C'\fR before the first use of its
25626 contents. This means that if \f(CW\*(C`cur\*(C'\fR is zero, the SV is immediately fully
25627 formed and ready to use, just like any other SV containing an empty string.
25628 .RS 4
25629 .Sp
25630 .Vb 2
25631 \& char * sv_setpv_bufsize(SV * const sv, const STRLEN cur,
25632 \& const STRLEN len)
25633 .Ve
25634 .RE
25635 .RS 4
25636 .RE
25637 .ie n .IP """sv_setpvf""" 4
25638 .el .IP \f(CWsv_setpvf\fR 4
25639 .IX Item "sv_setpvf"
25640 .PD 0
25641 .ie n .IP """sv_setpvf_mg""" 4
25642 .el .IP \f(CWsv_setpvf_mg\fR 4
25643 .IX Item "sv_setpvf_mg"
25644 .ie n .IP """sv_setpvf_mg_nocontext""" 4
25645 .el .IP \f(CWsv_setpvf_mg_nocontext\fR 4
25646 .IX Item "sv_setpvf_mg_nocontext"
25647 .ie n .IP """sv_setpvf_nocontext""" 4
25648 .el .IP \f(CWsv_setpvf_nocontext\fR 4
25649 .IX Xref "sv_setpvf sv_setpvf_mg sv_setpvf_mg_nocontext sv_setpvf_nocontext"
25650 .IX Item "sv_setpvf_nocontext"
25651 .PD
25652 These work like \f(CW"sv_catpvf"\fR but copy the text into the SV instead of
25653 appending it.
25654 .Sp
25655 The differences between these are:
25656 .Sp
25657 \&\f(CW\*(C`sv_setpvf_mg\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR perform 'set' magic; \f(CW\*(C`sv_setpvf\*(C'\fR
25658 and \f(CW\*(C`sv_setpvf_nocontext\*(C'\fR skip all magic.
25659 .Sp
25660 \&\f(CW\*(C`sv_setpvf_nocontext\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR do not take a thread
25661 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller
25662 doesn't already have the thread context.
25663 .Sp
25664 \&\fBThe UTF\-8 flag is not changed by these functions.\fR
25665 .Sp
25666 NOTE: \f(CW\*(C`sv_setpvf\*(C'\fR must be explicitly called as
25667 \&\f(CW\*(C`Perl_sv_setpvf\*(C'\fR
25668 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
25669 .Sp
25670 NOTE: \f(CW\*(C`sv_setpvf_mg\*(C'\fR must be explicitly called as
25671 \&\f(CW\*(C`Perl_sv_setpvf_mg\*(C'\fR
25672 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
25673 .RS 4
25674 .Sp
25675 .Vb 8
25676 \& void Perl_sv_setpvf (pTHX_ SV * const sv,
25677 \& const char * const pat, ...)
25678 \& void Perl_sv_setpvf_mg (pTHX_ SV * const sv,
25679 \& const char * const pat, ...)
25680 \& void sv_setpvf_mg_nocontext(SV * const sv,
25681 \& const char * const pat, ...)
25682 \& void sv_setpvf_nocontext (SV * const sv,
25683 \& const char * const pat, ...)
25684 .Ve
25685 .RE
25686 .RS 4
25687 .RE
25688 .ie n .IP """sv_setref_iv""" 4
25689 .el .IP \f(CWsv_setref_iv\fR 4
25690 .IX Xref "sv_setref_iv"
25691 .IX Item "sv_setref_iv"
25692 Copies an integer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
25693 argument will be upgraded to an RV. That RV will be modified to point to
25694 the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
25695 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
25696 will have a reference count of 1, and the RV will be returned.
25697 .RS 4
25698 .Sp
25699 .Vb 2
25700 \& SV * sv_setref_iv(SV * const rv, const char * const classname,
25701 \& const IV iv)
25702 .Ve
25703 .RE
25704 .RS 4
25705 .RE
25706 .ie n .IP """sv_setref_nv""" 4
25707 .el .IP \f(CWsv_setref_nv\fR 4
25708 .IX Xref "sv_setref_nv"
25709 .IX Item "sv_setref_nv"
25710 Copies a double into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
25711 argument will be upgraded to an RV. That RV will be modified to point to
25712 the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
25713 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
25714 will have a reference count of 1, and the RV will be returned.
25715 .RS 4
25716 .Sp
25717 .Vb 2
25718 \& SV * sv_setref_nv(SV * const rv, const char * const classname,
25719 \& const NV nv)
25720 .Ve
25721 .RE
25722 .RS 4
25723 .RE
25724 .ie n .IP """sv_setref_pv""" 4
25725 .el .IP \f(CWsv_setref_pv\fR 4
25726 .IX Xref "sv_setref_pv"
25727 .IX Item "sv_setref_pv"
25728 Copies a pointer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
25729 argument will be upgraded to an RV. That RV will be modified to point to
25730 the new SV. If the \f(CW\*(C`pv\*(C'\fR argument is \f(CW\*(C`NULL\*(C'\fR, then \f(CW\*(C`PL_sv_undef\*(C'\fR will be placed
25731 into the SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
25732 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
25733 will have a reference count of 1, and the RV will be returned.
25734 .Sp
25735 Do not use with other Perl types such as HV, AV, SV, CV, because those
25736 objects will become corrupted by the pointer copy process.
25737 .Sp
25738 Note that \f(CW\*(C`sv_setref_pvn\*(C'\fR copies the string while this copies the pointer.
25739 .RS 4
25740 .Sp
25741 .Vb 2
25742 \& SV * sv_setref_pv(SV * const rv, const char * const classname,
25743 \& void * const pv)
25744 .Ve
25745 .RE
25746 .RS 4
25747 .RE
25748 .ie n .IP """sv_setref_pvn""" 4
25749 .el .IP \f(CWsv_setref_pvn\fR 4
25750 .IX Xref "sv_setref_pvn"
25751 .IX Item "sv_setref_pvn"
25752 Copies a string into a new SV, optionally blessing the SV. The length of the
25753 string must be specified with \f(CW\*(C`n\*(C'\fR. The \f(CW\*(C`rv\*(C'\fR argument will be upgraded to
25754 an RV. That RV will be modified to point to the new SV. The \f(CW\*(C`classname\*(C'\fR
25755 argument indicates the package for the blessing. Set \f(CW\*(C`classname\*(C'\fR to
25756 \&\f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV will have a reference count
25757 of 1, and the RV will be returned.
25758 .Sp
25759 Note that \f(CW\*(C`sv_setref_pv\*(C'\fR copies the pointer while this copies the string.
25760 .RS 4
25761 .Sp
25762 .Vb 2
25763 \& SV * sv_setref_pvn(SV * const rv, const char * const classname,
25764 \& const char * const pv, const STRLEN n)
25765 .Ve
25766 .RE
25767 .RS 4
25768 .RE
25769 .ie n .IP """sv_setref_pvs""" 4
25770 .el .IP \f(CWsv_setref_pvs\fR 4
25771 .IX Xref "sv_setref_pvs"
25772 .IX Item "sv_setref_pvs"
25773 Like \f(CW\*(C`sv_setref_pvn\*(C'\fR, but takes a literal string instead of
25774 a string/length pair.
25775 .RS 4
25776 .Sp
25777 .Vb 2
25778 \& SV * sv_setref_pvs(SV *const rv, const char *const classname,
25779 \& "literal string")
25780 .Ve
25781 .RE
25782 .RS 4
25783 .RE
25784 .ie n .IP """sv_setref_uv""" 4
25785 .el .IP \f(CWsv_setref_uv\fR 4
25786 .IX Xref "sv_setref_uv"
25787 .IX Item "sv_setref_uv"
25788 Copies an unsigned integer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
25789 argument will be upgraded to an RV. That RV will be modified to point to
25790 the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
25791 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
25792 will have a reference count of 1, and the RV will be returned.
25793 .RS 4
25794 .Sp
25795 .Vb 2
25796 \& SV * sv_setref_uv(SV * const rv, const char * const classname,
25797 \& const UV uv)
25798 .Ve
25799 .RE
25800 .RS 4
25801 .RE
25802 .ie n .IP """sv_setrv_inc""" 4
25803 .el .IP \f(CWsv_setrv_inc\fR 4
25804 .IX Item "sv_setrv_inc"
25805 .PD 0
25806 .ie n .IP """sv_setrv_inc_mg""" 4
25807 .el .IP \f(CWsv_setrv_inc_mg\fR 4
25808 .IX Xref "sv_setrv_inc sv_setrv_inc_mg"
25809 .IX Item "sv_setrv_inc_mg"
25810 .PD
25811 As \f(CW\*(C`sv_setrv_noinc\*(C'\fR but increments the reference count of \fIref\fR.
25812 .Sp
25813 \&\f(CW\*(C`sv_setrv_inc_mg\*(C'\fR will invoke 'set' magic on the SV; \f(CW\*(C`sv_setrv_inc\*(C'\fR will
25814 not.
25815 .RS 4
25816 .Sp
25817 .Vb 1
25818 \& void sv_setrv_inc(SV * const sv, SV * const ref)
25819 .Ve
25820 .RE
25821 .RS 4
25822 .RE
25823 .ie n .IP """sv_setrv_noinc""" 4
25824 .el .IP \f(CWsv_setrv_noinc\fR 4
25825 .IX Item "sv_setrv_noinc"
25826 .PD 0
25827 .ie n .IP """sv_setrv_noinc_mg""" 4
25828 .el .IP \f(CWsv_setrv_noinc_mg\fR 4
25829 .IX Xref "sv_setrv_noinc sv_setrv_noinc_mg"
25830 .IX Item "sv_setrv_noinc_mg"
25831 .PD
25832 Copies an SV pointer into the given SV as an SV reference, upgrading it if
25833 necessary. After this, \f(CWSvRV(sv)\fR is equal to \fIref\fR. This does not adjust
25834 the reference count of \fIref\fR. The reference \fIref\fR must not be NULL.
25835 .Sp
25836 \&\f(CW\*(C`sv_setrv_noinc_mg\*(C'\fR will invoke 'set' magic on the SV; \f(CW\*(C`sv_setrv_noinc\*(C'\fR will
25837 not.
25838 .RS 4
25839 .Sp
25840 .Vb 1
25841 \& void sv_setrv_noinc(SV * const sv, SV * const ref)
25842 .Ve
25843 .RE
25844 .RS 4
25845 .RE
25846 .ie n .IP """sv_setsv""" 4
25847 .el .IP \f(CWsv_setsv\fR 4
25848 .IX Item "sv_setsv"
25849 .PD 0
25850 .ie n .IP """sv_setsv_flags""" 4
25851 .el .IP \f(CWsv_setsv_flags\fR 4
25852 .IX Item "sv_setsv_flags"
25853 .ie n .IP """sv_setsv_mg""" 4
25854 .el .IP \f(CWsv_setsv_mg\fR 4
25855 .IX Item "sv_setsv_mg"
25856 .ie n .IP """sv_setsv_nomg""" 4
25857 .el .IP \f(CWsv_setsv_nomg\fR 4
25858 .IX Xref "sv_setsv sv_setsv_flags sv_setsv_mg sv_setsv_nomg"
25859 .IX Item "sv_setsv_nomg"
25860 .PD
25861 These copy the contents of the source SV \f(CW\*(C`ssv\*(C'\fR into the destination SV \f(CW\*(C`dsv\*(C'\fR.
25862 \&\f(CW\*(C`ssv\*(C'\fR may be destroyed if it is mortal, so don't use these functions if
25863 the source SV needs to be reused.
25864 Loosely speaking, they perform a copy-by-value, obliterating any previous
25865 content of the destination.
25866 .Sp
25867 They differ only in that:
25868 .Sp
25869 \&\f(CW\*(C`sv_setsv\*(C'\fR calls 'get' magic on \f(CW\*(C`ssv\*(C'\fR, but skips 'set' magic on \f(CW\*(C`dsv\*(C'\fR.
25870 .Sp
25871 \&\f(CW\*(C`sv_setsv_mg\*(C'\fR calls both 'get' magic on \f(CW\*(C`ssv\*(C'\fR and 'set' magic on \f(CW\*(C`dsv\*(C'\fR.
25872 .Sp
25873 \&\f(CW\*(C`sv_setsv_nomg\*(C'\fR skips all magic.
25874 .Sp
25875 \&\f(CW\*(C`sv_setsv_flags\*(C'\fR has a \f(CW\*(C`flags\*(C'\fR parameter which you can use to specify any
25876 combination of magic handling, and also you can specify \f(CW\*(C`SV_NOSTEAL\*(C'\fR so that
25877 the buffers of temps will not be stolen.
25878 .Sp
25879 You probably want to instead use one of the assortment of wrappers, such as
25880 \&\f(CW"SvSetSV"\fR, \f(CW"SvSetSV_nosteal"\fR, \f(CW"SvSetMagicSV"\fR and
25881 \&\f(CW"SvSetMagicSV_nosteal"\fR.
25882 .Sp
25883 \&\f(CW\*(C`sv_setsv_flags\*(C'\fR is the primary function for copying scalars, and most other
25884 copy-ish functions and macros use it underneath.
25885 .RS 4
25886 .Sp
25887 .Vb 4
25888 \& void sv_setsv (SV *dsv, SV *ssv)
25889 \& void sv_setsv_flags(SV *dsv, SV *ssv, const I32 flags)
25890 \& void sv_setsv_mg (SV * const dsv, SV * const ssv)
25891 \& void sv_setsv_nomg (SV *dsv, SV *ssv)
25892 .Ve
25893 .RE
25894 .RS 4
25895 .RE
25896 .ie n .IP """sv_set_true""" 4
25897 .el .IP \f(CWsv_set_true\fR 4
25898 .IX Xref "sv_set_true"
25899 .IX Item "sv_set_true"
25900 Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_yes)\*(C'\fR, but may be made more
25901 efficient in the future. Doesn't handle set magic.
25902 .Sp
25903 The perl equivalent is \f(CW\*(C`$sv = !0;\*(C'\fR.
25904 .Sp
25905 Introduced in perl 5.35.11.
25906 .RS 4
25907 .Sp
25908 .Vb 1
25909 \& void sv_set_true(SV *sv)
25910 .Ve
25911 .RE
25912 .RS 4
25913 .RE
25914 .ie n .IP """sv_set_undef""" 4
25915 .el .IP \f(CWsv_set_undef\fR 4
25916 .IX Xref "sv_set_undef"
25917 .IX Item "sv_set_undef"
25918 Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_undef)\*(C'\fR, but more efficient.
25919 Doesn't handle set magic.
25920 .Sp
25921 The perl equivalent is \f(CW\*(C`$sv = undef;\*(C'\fR. Note that it doesn't free any string
25922 buffer, unlike \f(CW\*(C`undef $sv\*(C'\fR.
25923 .Sp
25924 Introduced in perl 5.25.12.
25925 .RS 4
25926 .Sp
25927 .Vb 1
25928 \& void sv_set_undef(SV *sv)
25929 .Ve
25930 .RE
25931 .RS 4
25932 .RE
25933 .ie n .IP """sv_setuv""" 4
25934 .el .IP \f(CWsv_setuv\fR 4
25935 .IX Item "sv_setuv"
25936 .PD 0
25937 .ie n .IP """sv_setuv_mg""" 4
25938 .el .IP \f(CWsv_setuv_mg\fR 4
25939 .IX Xref "sv_setuv sv_setuv_mg"
25940 .IX Item "sv_setuv_mg"
25941 .PD
25942 These copy an unsigned integer into the given SV, upgrading first if necessary.
25943 .Sp
25944 They differ only in that \f(CW\*(C`sv_setuv_mg\*(C'\fR handles 'set' magic; \f(CW\*(C`sv_setuv\*(C'\fR does
25945 not.
25946 .RS 4
25947 .Sp
25948 .Vb 2
25949 \& void sv_setuv (SV * const sv, const UV num)
25950 \& void sv_setuv_mg(SV * const sv, const UV u)
25951 .Ve
25952 .RE
25953 .RS 4
25954 .RE
25955 .ie n .IP """SvSHARE""" 4
25956 .el .IP \f(CWSvSHARE\fR 4
25957 .IX Xref "SvSHARE"
25958 .IX Item "SvSHARE"
25959 Arranges for \f(CW\*(C`sv\*(C'\fR to be shared between threads if a suitable module
25960 has been loaded.
25961 .RS 4
25962 .Sp
25963 .Vb 1
25964 \& void SvSHARE(SV* sv)
25965 .Ve
25966 .RE
25967 .RS 4
25968 .RE
25969 .ie n .IP """SvSHARED_HASH""" 4
25970 .el .IP \f(CWSvSHARED_HASH\fR 4
25971 .IX Xref "SvSHARED_HASH"
25972 .IX Item "SvSHARED_HASH"
25973 Returns the hash for \f(CW\*(C`sv\*(C'\fR created by \f(CW"newSVpvn_share"\fR.
25974 .RS 4
25975 .Sp
25976 .Vb 1
25977 \& struct hek* SvSHARED_HASH(SV * sv)
25978 .Ve
25979 .RE
25980 .RS 4
25981 .RE
25982 .ie n .IP """SvSTASH""" 4
25983 .el .IP \f(CWSvSTASH\fR 4
25984 .IX Xref "SvSTASH"
25985 .IX Item "SvSTASH"
25986 Returns the stash of the SV.
25987 .RS 4
25988 .Sp
25989 .Vb 1
25990 \& HV* SvSTASH(SV* sv)
25991 .Ve
25992 .RE
25993 .RS 4
25994 .RE
25995 .ie n .IP """SvSTASH_set""" 4
25996 .el .IP \f(CWSvSTASH_set\fR 4
25997 .IX Xref "SvSTASH_set"
25998 .IX Item "SvSTASH_set"
25999 Set the value of the STASH pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
26000 .RS 4
26001 .Sp
26002 .Vb 1
26003 \& void SvSTASH_set(SV* sv, HV* val)
26004 .Ve
26005 .RE
26006 .RS 4
26007 .RE
26008 .ie n .IP """sv_streq""" 4
26009 .el .IP \f(CWsv_streq\fR 4
26010 .IX Xref "sv_streq"
26011 .IX Item "sv_streq"
26012 A convenient shortcut for calling \f(CW\*(C`sv_streq_flags\*(C'\fR with the \f(CW\*(C`SV_GMAGIC\*(C'\fR
26013 flag. This function basically behaves like the Perl code \f(CW\*(C`$sv1 eq $sv2\*(C'\fR.
26014 .RS 4
26015 .Sp
26016 .Vb 1
26017 \& bool sv_streq(SV *sv1, SV *sv2)
26018 .Ve
26019 .RE
26020 .RS 4
26021 .RE
26022 .ie n .IP """sv_streq_flags""" 4
26023 .el .IP \f(CWsv_streq_flags\fR 4
26024 .IX Xref "sv_streq_flags"
26025 .IX Item "sv_streq_flags"
26026 Returns a boolean indicating whether the strings in the two SVs are
26027 identical. If the flags argument has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, it handles
26028 get-magic too. Will coerce its args to strings if necessary. Treats
26029 \&\f(CW\*(C`NULL\*(C'\fR as undef. Correctly handles the UTF8 flag.
26030 .Sp
26031 If flags does not have the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use
26032 \&\f(CW\*(C`eq\*(C'\fR overloading will be made. If such overloading does not exist or the
26033 flag is set, then regular string comparison will be used instead.
26034 .RS 4
26035 .Sp
26036 .Vb 1
26037 \& bool sv_streq_flags(SV *sv1, SV *sv2, const U32 flags)
26038 .Ve
26039 .RE
26040 .RS 4
26041 .RE
26042 .ie n .IP """SvTRUE""" 4
26043 .el .IP \f(CWSvTRUE\fR 4
26044 .IX Item "SvTRUE"
26045 .PD 0
26046 .ie n .IP """SvTRUE_NN""" 4
26047 .el .IP \f(CWSvTRUE_NN\fR 4
26048 .IX Item "SvTRUE_NN"
26049 .ie n .IP """SvTRUE_nomg""" 4
26050 .el .IP \f(CWSvTRUE_nomg\fR 4
26051 .IX Item "SvTRUE_nomg"
26052 .ie n .IP """SvTRUE_nomg_NN""" 4
26053 .el .IP \f(CWSvTRUE_nomg_NN\fR 4
26054 .IX Item "SvTRUE_nomg_NN"
26055 .ie n .IP """SvTRUEx""" 4
26056 .el .IP \f(CWSvTRUEx\fR 4
26057 .IX Xref "SvTRUE SvTRUE_NN SvTRUE_nomg SvTRUE_nomg_NN SvTRUEx"
26058 .IX Item "SvTRUEx"
26059 .PD
26060 These return a boolean indicating whether Perl would evaluate the SV as true or
26061 false. See \f(CW"SvOK"\fR for a defined/undefined test.
26062 .Sp
26063 As of Perl 5.32, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. Prior to that
26064 release, only \f(CW\*(C`SvTRUEx\*(C'\fR guaranteed single evaluation; now \f(CW\*(C`SvTRUEx\*(C'\fR is
26065 identical to \f(CW\*(C`SvTRUE\*(C'\fR.
26066 .Sp
26067 \&\f(CW\*(C`SvTRUE_nomg\*(C'\fR and \f(CW\*(C`TRUE_nomg_NN\*(C'\fR do not perform 'get' magic; the others do
26068 unless the scalar is already \f(CW\*(C`SvPOK\*(C'\fR, \f(CW\*(C`SvIOK\*(C'\fR, or \f(CW\*(C`SvNOK\*(C'\fR (the public, not
26069 the private flags).
26070 .Sp
26071 \&\f(CW\*(C`SvTRUE_NN\*(C'\fR is like \f(CW"SvTRUE"\fR, but \f(CW\*(C`sv\*(C'\fR is assumed to be
26072 non-null (NN). If there is a possibility that it is NULL, use plain
26073 \&\f(CW\*(C`SvTRUE\*(C'\fR.
26074 .Sp
26075 \&\f(CW\*(C`SvTRUE_nomg_NN\*(C'\fR is like \f(CW"SvTRUE_nomg"\fR, but \f(CW\*(C`sv\*(C'\fR is assumed to be
26076 non-null (NN). If there is a possibility that it is NULL, use plain
26077 \&\f(CW\*(C`SvTRUE_nomg\*(C'\fR.
26078 .RS 4
26079 .Sp
26080 .Vb 1
26081 \& bool SvTRUE(SV *sv)
26082 .Ve
26083 .RE
26084 .RS 4
26085 .RE
26086 .ie n .IP """SvTYPE""" 4
26087 .el .IP \f(CWSvTYPE\fR 4
26088 .IX Xref "SvTYPE"
26089 .IX Item "SvTYPE"
26090 Returns the type of the SV. See \f(CW"svtype"\fR.
26091 .RS 4
26092 .Sp
26093 .Vb 1
26094 \& svtype SvTYPE(SV* sv)
26095 .Ve
26096 .RE
26097 .RS 4
26098 .RE
26099 .ie n .IP """SvUNLOCK""" 4
26100 .el .IP \f(CWSvUNLOCK\fR 4
26101 .IX Xref "SvUNLOCK"
26102 .IX Item "SvUNLOCK"
26103 Releases a mutual exclusion lock on \f(CW\*(C`sv\*(C'\fR if a suitable module
26104 has been loaded.
26105 .RS 4
26106 .Sp
26107 .Vb 1
26108 \& void SvUNLOCK(SV* sv)
26109 .Ve
26110 .RE
26111 .RS 4
26112 .RE
26113 .ie n .IP """sv_unmagic""" 4
26114 .el .IP \f(CWsv_unmagic\fR 4
26115 .IX Xref "sv_unmagic"
26116 .IX Item "sv_unmagic"
26117 Removes all magic of type \f(CW\*(C`type\*(C'\fR from an SV.
26118 .RS 4
26119 .Sp
26120 .Vb 1
26121 \& int sv_unmagic(SV * const sv, const int type)
26122 .Ve
26123 .RE
26124 .RS 4
26125 .RE
26126 .ie n .IP """sv_unmagicext""" 4
26127 .el .IP \f(CWsv_unmagicext\fR 4
26128 .IX Xref "sv_unmagicext"
26129 .IX Item "sv_unmagicext"
26130 Removes all magic of type \f(CW\*(C`type\*(C'\fR with the specified \f(CW\*(C`vtbl\*(C'\fR from an SV.
26131 .RS 4
26132 .Sp
26133 .Vb 2
26134 \& int sv_unmagicext(SV * const sv, const int type,
26135 \& const MGVTBL *vtbl)
26136 .Ve
26137 .RE
26138 .RS 4
26139 .RE
26140 .ie n .IP """sv_unref""" 4
26141 .el .IP \f(CWsv_unref\fR 4
26142 .IX Xref "sv_unref"
26143 .IX Item "sv_unref"
26144 Unsets the RV status of the SV, and decrements the reference count of
26145 whatever was being referenced by the RV. This can almost be thought of
26146 as a reversal of \f(CW\*(C`newSVrv\*(C'\fR. This is \f(CW\*(C`sv_unref_flags\*(C'\fR with the \f(CW\*(C`flag\*(C'\fR
26147 being zero. See \f(CW"SvROK_off"\fR.
26148 .RS 4
26149 .Sp
26150 .Vb 1
26151 \& void sv_unref(SV *sv)
26152 .Ve
26153 .RE
26154 .RS 4
26155 .RE
26156 .ie n .IP """sv_unref_flags""" 4
26157 .el .IP \f(CWsv_unref_flags\fR 4
26158 .IX Xref "sv_unref_flags"
26159 .IX Item "sv_unref_flags"
26160 Unsets the RV status of the SV, and decrements the reference count of
26161 whatever was being referenced by the RV. This can almost be thought of
26162 as a reversal of \f(CW\*(C`newSVrv\*(C'\fR. The \f(CW\*(C`cflags\*(C'\fR argument can contain
26163 \&\f(CW\*(C`SV_IMMEDIATE_UNREF\*(C'\fR to force the reference count to be decremented
26164 (otherwise the decrementing is conditional on the reference count being
26165 different from one or the reference being a readonly SV).
26166 See \f(CW"SvROK_off"\fR.
26167 .RS 4
26168 .Sp
26169 .Vb 1
26170 \& void sv_unref_flags(SV * const ref, const U32 flags)
26171 .Ve
26172 .RE
26173 .RS 4
26174 .RE
26175 .ie n .IP """SvUOK""" 4
26176 .el .IP \f(CWSvUOK\fR 4
26177 .IX Xref "SvUOK"
26178 .IX Item "SvUOK"
26179 Returns a boolean indicating whether the SV contains an integer that must be
26180 interpreted as unsigned. A non-negative integer whose value is within the
26181 range of both an IV and a UV may be flagged as either \f(CW\*(C`SvUOK\*(C'\fR or \f(CW\*(C`SvIOK\*(C'\fR.
26182 .RS 4
26183 .Sp
26184 .Vb 1
26185 \& bool SvUOK(SV* sv)
26186 .Ve
26187 .RE
26188 .RS 4
26189 .RE
26190 .ie n .IP """SvUPGRADE""" 4
26191 .el .IP \f(CWSvUPGRADE\fR 4
26192 .IX Xref "SvUPGRADE"
26193 .IX Item "SvUPGRADE"
26194 Used to upgrade an SV to a more complex form. Uses \f(CW\*(C`sv_upgrade\*(C'\fR to
26195 perform the upgrade if necessary. See \f(CW"svtype"\fR.
26196 .RS 4
26197 .Sp
26198 .Vb 1
26199 \& void SvUPGRADE(SV* sv, svtype type)
26200 .Ve
26201 .RE
26202 .RS 4
26203 .RE
26204 .ie n .IP """sv_upgrade""" 4
26205 .el .IP \f(CWsv_upgrade\fR 4
26206 .IX Xref "sv_upgrade"
26207 .IX Item "sv_upgrade"
26208 Upgrade an SV to a more complex form. Generally adds a new body type to the
26209 SV, then copies across as much information as possible from the old body.
26210 It croaks if the SV is already in a more complex form than requested. You
26211 generally want to use the \f(CW\*(C`SvUPGRADE\*(C'\fR macro wrapper, which checks the type
26212 before calling \f(CW\*(C`sv_upgrade\*(C'\fR, and hence does not croak. See also
26213 \&\f(CW"svtype"\fR.
26214 .RS 4
26215 .Sp
26216 .Vb 1
26217 \& void sv_upgrade(SV * const sv, svtype new_type)
26218 .Ve
26219 .RE
26220 .RS 4
26221 .RE
26222 .ie n .IP """sv_usepvn""" 4
26223 .el .IP \f(CWsv_usepvn\fR 4
26224 .IX Item "sv_usepvn"
26225 .PD 0
26226 .ie n .IP """sv_usepvn_flags""" 4
26227 .el .IP \f(CWsv_usepvn_flags\fR 4
26228 .IX Item "sv_usepvn_flags"
26229 .ie n .IP """sv_usepvn_mg""" 4
26230 .el .IP \f(CWsv_usepvn_mg\fR 4
26231 .IX Xref "sv_usepvn sv_usepvn_flags sv_usepvn_mg"
26232 .IX Item "sv_usepvn_mg"
26233 .PD
26234 These tell an SV to use \f(CW\*(C`ptr\*(C'\fR for its string value. Normally SVs have
26235 their string stored inside the SV, but these tell the SV to use an
26236 external string instead.
26237 .Sp
26238 \&\f(CW\*(C`ptr\*(C'\fR should point to memory that was allocated
26239 by "\f(CW\*(C`Newx\*(C'\fR". It must be
26240 the start of a \f(CW\*(C`Newx\*(C'\fR\-ed block of memory, and not a pointer to the
26241 middle of it (beware of \f(CW\*(C`OOK\*(C'\fR and copy-on-write),
26242 and not be from a non\-\f(CW\*(C`Newx\*(C'\fR memory allocator like \f(CW\*(C`malloc\*(C'\fR. The
26243 string length, \f(CW\*(C`len\*(C'\fR, must be supplied. By default this function
26244 will "\f(CW\*(C`Renew\*(C'\fR" (i.e. realloc, move) the memory pointed to by \f(CW\*(C`ptr\*(C'\fR,
26245 so that the pointer should not be freed or used by the programmer after giving
26246 it to \f(CW\*(C`sv_usepvn\*(C'\fR, and neither should any pointers from "behind" that pointer
26247 (\fIe.g.\fR, \f(CW\*(C`ptr\*(C'\fR\ +\ 1) be used.
26248 .Sp
26249 In the \f(CW\*(C`sv_usepvn_flags\*(C'\fR form, if \f(CW\*(C`flags\ &\ SV_SMAGIC\*(C'\fR is true,
26250 \&\f(CW\*(C`SvSETMAGIC\*(C'\fR is called before returning.
26251 And if \f(CW\*(C`flags\ &\ SV_HAS_TRAILING_NUL\*(C'\fR is true, then \f(CW\*(C`ptr[len]\*(C'\fR must be
26252 \&\f(CW\*(C`NUL\*(C'\fR, and the realloc will be skipped (\fIi.e.\fR, the buffer is actually at
26253 least 1 byte longer than \f(CW\*(C`len\*(C'\fR, and already meets the requirements for storing
26254 in \f(CW\*(C`SvPVX\*(C'\fR).
26255 .Sp
26256 \&\f(CW\*(C`sv_usepvn\*(C'\fR is merely \f(CW\*(C`sv_usepvn_flags\*(C'\fR with \f(CW\*(C`flags\*(C'\fR set to 0, so 'set'
26257 magic is skipped.
26258 .Sp
26259 \&\f(CW\*(C`sv_usepvn_mg\*(C'\fR is merely \f(CW\*(C`sv_usepvn_flags\*(C'\fR with \f(CW\*(C`flags\*(C'\fR set to \f(CW\*(C`SV_SMAGIC\*(C'\fR,
26260 so 'set' magic is performed.
26261 .RS 4
26262 .Sp
26263 .Vb 4
26264 \& void sv_usepvn (SV *sv, char *ptr, STRLEN len)
26265 \& void sv_usepvn_flags(SV * const sv, char *ptr, const STRLEN len,
26266 \& const U32 flags)
26267 \& void sv_usepvn_mg (SV *sv, char *ptr, STRLEN len)
26268 .Ve
26269 .RE
26270 .RS 4
26271 .RE
26272 .ie n .IP """sv_utf8_decode""" 4
26273 .el .IP \f(CWsv_utf8_decode\fR 4
26274 .IX Xref "sv_utf8_decode"
26275 .IX Item "sv_utf8_decode"
26276 If the PV of the SV is an octet sequence in Perl's extended UTF\-8
26277 and contains a multiple-byte character, the \f(CW\*(C`SvUTF8\*(C'\fR flag is turned on
26278 so that it looks like a character. If the PV contains only single-byte
26279 characters, the \f(CW\*(C`SvUTF8\*(C'\fR flag stays off.
26280 Scans PV for validity and returns FALSE if the PV is invalid UTF\-8.
26281 .RS 4
26282 .Sp
26283 .Vb 1
26284 \& bool sv_utf8_decode(SV * const sv)
26285 .Ve
26286 .RE
26287 .RS 4
26288 .RE
26289 .ie n .IP """sv_utf8_downgrade""" 4
26290 .el .IP \f(CWsv_utf8_downgrade\fR 4
26291 .IX Item "sv_utf8_downgrade"
26292 .PD 0
26293 .ie n .IP """sv_utf8_downgrade_flags""" 4
26294 .el .IP \f(CWsv_utf8_downgrade_flags\fR 4
26295 .IX Item "sv_utf8_downgrade_flags"
26296 .ie n .IP """sv_utf8_downgrade_nomg""" 4
26297 .el .IP \f(CWsv_utf8_downgrade_nomg\fR 4
26298 .IX Xref "sv_utf8_downgrade sv_utf8_downgrade_flags sv_utf8_downgrade_nomg"
26299 .IX Item "sv_utf8_downgrade_nomg"
26300 .PD
26301 These attempt to convert the PV of an SV from characters to bytes. If the PV
26302 contains a character that cannot fit in a byte, this conversion will fail; in
26303 this case, \f(CW\*(C`FALSE\*(C'\fR is returned if \f(CW\*(C`fail_ok\*(C'\fR is true; otherwise they croak.
26304 .Sp
26305 They are not a general purpose Unicode to byte encoding interface:
26306 use the \f(CW\*(C`Encode\*(C'\fR extension for that.
26307 .Sp
26308 They differ only in that:
26309 .Sp
26310 \&\f(CW\*(C`sv_utf8_downgrade\*(C'\fR processes 'get' magic on \f(CW\*(C`sv\*(C'\fR.
26311 .Sp
26312 \&\f(CW\*(C`sv_utf8_downgrade_nomg\*(C'\fR does not.
26313 .Sp
26314 \&\f(CW\*(C`sv_utf8_downgrade_flags\*(C'\fR has an additional \f(CW\*(C`flags\*(C'\fR parameter in which you can specify
26315 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR to process 'get' magic, or leave it cleared to not process 'get' magic.
26316 .RS 4
26317 .Sp
26318 .Vb 4
26319 \& bool sv_utf8_downgrade (SV * const sv, const bool fail_ok)
26320 \& bool sv_utf8_downgrade_flags(SV * const sv, const bool fail_ok,
26321 \& const U32 flags)
26322 \& bool sv_utf8_downgrade_nomg (SV * const sv, const bool fail_ok)
26323 .Ve
26324 .RE
26325 .RS 4
26326 .RE
26327 .ie n .IP """sv_utf8_encode""" 4
26328 .el .IP \f(CWsv_utf8_encode\fR 4
26329 .IX Xref "sv_utf8_encode"
26330 .IX Item "sv_utf8_encode"
26331 Converts the PV of an SV to UTF\-8, but then turns the \f(CW\*(C`SvUTF8\*(C'\fR
26332 flag off so that it looks like octets again.
26333 .RS 4
26334 .Sp
26335 .Vb 1
26336 \& void sv_utf8_encode(SV * const sv)
26337 .Ve
26338 .RE
26339 .RS 4
26340 .RE
26341 .ie n .IP """SvUTF8_off""" 4
26342 .el .IP \f(CWSvUTF8_off\fR 4
26343 .IX Xref "SvUTF8_off"
26344 .IX Item "SvUTF8_off"
26345 Unsets the UTF\-8 status of an SV (the data is not changed, just the flag).
26346 Do not use frivolously.
26347 .RS 4
26348 .Sp
26349 .Vb 1
26350 \& void SvUTF8_off(SV *sv)
26351 .Ve
26352 .RE
26353 .RS 4
26354 .RE
26355 .ie n .IP """SvUTF8_on""" 4
26356 .el .IP \f(CWSvUTF8_on\fR 4
26357 .IX Xref "SvUTF8_on"
26358 .IX Item "SvUTF8_on"
26359 Turn on the UTF\-8 status of an SV (the data is not changed, just the flag).
26360 Do not use frivolously.
26361 .RS 4
26362 .Sp
26363 .Vb 1
26364 \& void SvUTF8_on(SV *sv)
26365 .Ve
26366 .RE
26367 .RS 4
26368 .RE
26369 .ie n .IP """sv_utf8_upgrade""" 4
26370 .el .IP \f(CWsv_utf8_upgrade\fR 4
26371 .IX Item "sv_utf8_upgrade"
26372 .PD 0
26373 .ie n .IP """sv_utf8_upgrade_flags""" 4
26374 .el .IP \f(CWsv_utf8_upgrade_flags\fR 4
26375 .IX Item "sv_utf8_upgrade_flags"
26376 .ie n .IP """sv_utf8_upgrade_flags_grow""" 4
26377 .el .IP \f(CWsv_utf8_upgrade_flags_grow\fR 4
26378 .IX Item "sv_utf8_upgrade_flags_grow"
26379 .ie n .IP """sv_utf8_upgrade_nomg""" 4
26380 .el .IP \f(CWsv_utf8_upgrade_nomg\fR 4
26381 .IX Xref "sv_utf8_upgrade sv_utf8_upgrade_flags sv_utf8_upgrade_flags_grow sv_utf8_upgrade_nomg"
26382 .IX Item "sv_utf8_upgrade_nomg"
26383 .PD
26384 These convert the PV of an SV to its UTF\-8\-encoded form.
26385 The SV is forced to string form if it is not already.
26386 They always set the \f(CW\*(C`SvUTF8\*(C'\fR flag to avoid future validity checks even if the
26387 whole string is the same in UTF\-8 as not.
26388 They return the number of bytes in the converted string
26389 .Sp
26390 The forms differ in just two ways. The main difference is whether or not they
26391 perform 'get magic' on \f(CW\*(C`sv\*(C'\fR. \f(CW\*(C`sv_utf8_upgrade_nomg\*(C'\fR skips 'get magic';
26392 \&\f(CW\*(C`sv_utf8_upgrade\*(C'\fR performs it; and \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR and
26393 \&\f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR either perform it (if the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit is set
26394 in \f(CW\*(C`flags\*(C'\fR) or don't (if that bit is cleared).
26395 .Sp
26396 The other difference is that \f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR has an additional
26397 parameter, \f(CW\*(C`extra\*(C'\fR, which allows the caller to specify an amount of space to
26398 be reserved as spare beyond what is needed for the actual conversion. This is
26399 used when the caller knows it will soon be needing yet more space, and it is
26400 more efficient to request space from the system in a single call.
26401 This form is otherwise identical to \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR.
26402 .Sp
26403 These are not a general purpose byte encoding to Unicode interface: use the
26404 Encode extension for that.
26405 .Sp
26406 The \f(CW\*(C`SV_FORCE_UTF8_UPGRADE\*(C'\fR flag is now ignored.
26407 .RS 4
26408 .Sp
26409 .Vb 5
26410 \& STRLEN sv_utf8_upgrade (SV *sv)
26411 \& STRLEN sv_utf8_upgrade_flags (SV * const sv, const I32 flags)
26412 \& STRLEN sv_utf8_upgrade_flags_grow(SV * const sv, const I32 flags,
26413 \& STRLEN extra)
26414 \& STRLEN sv_utf8_upgrade_nomg (SV *sv)
26415 .Ve
26416 .RE
26417 .RS 4
26418 .RE
26419 .ie n .IP """SvUTF8""" 4
26420 .el .IP \f(CWSvUTF8\fR 4
26421 .IX Xref "SvUTF8"
26422 .IX Item "SvUTF8"
26423 Returns a U32 value indicating the UTF\-8 status of an SV. If things are set-up
26424 properly, this indicates whether or not the SV contains UTF\-8 encoded data.
26425 You should use this \fIafter\fR a call to \f(CW"SvPV"\fR or one of its variants, in
26426 case any call to string overloading updates the internal flag.
26427 .Sp
26428 If you want to take into account the bytes pragma, use \f(CW"DO_UTF8"\fR
26429 instead.
26430 .RS 4
26431 .Sp
26432 .Vb 1
26433 \& U32 SvUTF8(SV* sv)
26434 .Ve
26435 .RE
26436 .RS 4
26437 .RE
26438 .ie n .IP """SvUV""" 4
26439 .el .IP \f(CWSvUV\fR 4
26440 .IX Item "SvUV"
26441 .PD 0
26442 .ie n .IP """SvUV_nomg""" 4
26443 .el .IP \f(CWSvUV_nomg\fR 4
26444 .IX Item "SvUV_nomg"
26445 .ie n .IP """SvUVx""" 4
26446 .el .IP \f(CWSvUVx\fR 4
26447 .IX Xref "SvUV SvUV_nomg SvUVx"
26448 .IX Item "SvUVx"
26449 .PD
26450 These each coerce the given SV to UV and return it. The returned value in many
26451 circumstances will get stored in \f(CW\*(C`sv\*(C'\fR's UV slot, but not in all cases. (Use
26452 \&\f(CW"sv_setuv"\fR to make sure it does).
26453 .Sp
26454 As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
26455 .Sp
26456 \&\f(CW\*(C`SvUVx\*(C'\fR is now identical to \f(CW\*(C`SvUV\*(C'\fR, but prior to 5.37.1, it was the only form
26457 guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
26458 .RS 4
26459 .Sp
26460 .Vb 1
26461 \& UV SvUV(SV *sv)
26462 .Ve
26463 .RE
26464 .RS 4
26465 .RE
26466 .ie n .IP """sv_2uv_flags""" 4
26467 .el .IP \f(CWsv_2uv_flags\fR 4
26468 .IX Xref "sv_2uv_flags"
26469 .IX Item "sv_2uv_flags"
26470 Return the unsigned integer value of an SV, doing any necessary string
26471 conversion. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, does an \f(CWmg_get()\fR first.
26472 Normally used via the \f(CWSvUV(sv)\fR and \f(CWSvUVx(sv)\fR macros.
26473 .RS 4
26474 .Sp
26475 .Vb 1
26476 \& UV sv_2uv_flags(SV * const sv, const I32 flags)
26477 .Ve
26478 .RE
26479 .RS 4
26480 .RE
26481 .ie n .IP """SvUV_set""" 4
26482 .el .IP \f(CWSvUV_set\fR 4
26483 .IX Xref "SvUV_set"
26484 .IX Item "SvUV_set"
26485 Set the value of the UV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
26486 .RS 4
26487 .Sp
26488 .Vb 1
26489 \& void SvUV_set(SV* sv, UV val)
26490 .Ve
26491 .RE
26492 .RS 4
26493 .RE
26494 .ie n .IP """SvUVX""" 4
26495 .el .IP \f(CWSvUVX\fR 4
26496 .IX Xref "SvUVX"
26497 .IX Item "SvUVX"
26498 Returns the raw value in the SV's UV slot, without checks or conversions.
26499 Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true. See also \f(CW"SvUV"\fR.
26500 .RS 4
26501 .Sp
26502 .Vb 1
26503 \& UV SvUVX(SV* sv)
26504 .Ve
26505 .RE
26506 .RS 4
26507 .RE
26508 .ie n .IP """SvUVXx""" 4
26509 .el .IP \f(CWSvUVXx\fR 4
26510 .IX Xref "SvUVXx"
26511 .IX Item "SvUVXx"
26512 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`SvUVXx\*(C'\fR
26513 from a future release of Perl. Do not use it for
26514 new code; remove it from existing code.
26515 .Sp
26516 This is an unnecessary synonym for "SvUVX"
26517 .RS 4
26518 .Sp
26519 .Vb 1
26520 \& UV SvUVXx(SV* sv)
26521 .Ve
26522 .RE
26523 .RS 4
26524 .RE
26525 .ie n .IP """sv_vcatpvf""" 4
26526 .el .IP \f(CWsv_vcatpvf\fR 4
26527 .IX Item "sv_vcatpvf"
26528 .PD 0
26529 .ie n .IP """sv_vcatpvf_mg""" 4
26530 .el .IP \f(CWsv_vcatpvf_mg\fR 4
26531 .IX Xref "sv_vcatpvf sv_vcatpvf_mg"
26532 .IX Item "sv_vcatpvf_mg"
26533 .PD
26534 These process their arguments like \f(CW\*(C`sv_vcatpvfn\*(C'\fR called with a non-null
26535 C\-style variable argument list, and append the formatted output to \f(CW\*(C`sv\*(C'\fR.
26536 .Sp
26537 They differ only in that \f(CW\*(C`sv_vcatpvf_mg\*(C'\fR performs 'set' magic;
26538 \&\f(CW\*(C`sv_vcatpvf\*(C'\fR skips 'set' magic.
26539 .Sp
26540 Both perform 'get' magic.
26541 .Sp
26542 They are usually accessed via their frontends \f(CW"sv_catpvf"\fR and
26543 \&\f(CW"sv_catpvf_mg"\fR.
26544 .RS 4
26545 .Sp
26546 .Vb 2
26547 \& void sv_vcatpvf(SV * const sv, const char * const pat,
26548 \& va_list * const args)
26549 .Ve
26550 .RE
26551 .RS 4
26552 .RE
26553 .ie n .IP """sv_vcatpvfn""" 4
26554 .el .IP \f(CWsv_vcatpvfn\fR 4
26555 .IX Item "sv_vcatpvfn"
26556 .PD 0
26557 .ie n .IP """sv_vcatpvfn_flags""" 4
26558 .el .IP \f(CWsv_vcatpvfn_flags\fR 4
26559 .IX Xref "sv_vcatpvfn sv_vcatpvfn_flags"
26560 .IX Item "sv_vcatpvfn_flags"
26561 .PD
26562 These process their arguments like \f(CWvsprintf(3)\fR and append the formatted output
26563 to an SV. They use an array of SVs if the C\-style variable argument list is
26564 missing (\f(CW\*(C`NULL\*(C'\fR). Argument reordering (using format specifiers like \f(CW\*(C`%2$d\*(C'\fR or
26565 \&\f(CW\*(C`%*2$d\*(C'\fR) is supported only when using an array of SVs; using a C\-style
26566 \&\f(CW\*(C`va_list\*(C'\fR argument list with a format string that uses argument reordering
26567 will yield an exception.
26568 .Sp
26569 When running with taint checks enabled, they indicate via \f(CW\*(C`maybe_tainted\*(C'\fR if
26570 results are untrustworthy (often due to the use of locales).
26571 .Sp
26572 They assume that \f(CW\*(C`pat\*(C'\fR has the same utf8\-ness as \f(CW\*(C`sv\*(C'\fR. It's the caller's
26573 responsibility to ensure that this is so.
26574 .Sp
26575 They differ in that \f(CW\*(C`sv_vcatpvfn_flags\*(C'\fR has a \f(CW\*(C`flags\*(C'\fR parameter in which you
26576 can set or clear the \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or SV_SMAGIC flags, to specify which
26577 magic to handle or not handle; whereas plain \f(CW\*(C`sv_vcatpvfn\*(C'\fR always specifies
26578 both 'get' and 'set' magic.
26579 .Sp
26580 They are usually used via one of the frontends "\f(CW\*(C`sv_vcatpvf\*(C'\fR" and
26581 "\f(CW\*(C`sv_vcatpvf_mg\*(C'\fR".
26582 .RS 4
26583 .Sp
26584 .Vb 9
26585 \& void sv_vcatpvfn (SV * const sv, const char * const pat,
26586 \& const STRLEN patlen, va_list * const args,
26587 \& SV ** const svargs, const Size_t sv_count,
26588 \& bool * const maybe_tainted)
26589 \& void sv_vcatpvfn_flags(SV * const sv, const char * const pat,
26590 \& const STRLEN patlen, va_list * const args,
26591 \& SV ** const svargs, const Size_t sv_count,
26592 \& bool * const maybe_tainted,
26593 \& const U32 flags)
26594 .Ve
26595 .RE
26596 .RS 4
26597 .RE
26598 .ie n .IP """SvVOK""" 4
26599 .el .IP \f(CWSvVOK\fR 4
26600 .IX Xref "SvVOK"
26601 .IX Item "SvVOK"
26602 Returns a boolean indicating whether the SV contains a v\-string.
26603 .RS 4
26604 .Sp
26605 .Vb 1
26606 \& bool SvVOK(SV* sv)
26607 .Ve
26608 .RE
26609 .RS 4
26610 .RE
26611 .ie n .IP """sv_vsetpvf""" 4
26612 .el .IP \f(CWsv_vsetpvf\fR 4
26613 .IX Item "sv_vsetpvf"
26614 .PD 0
26615 .ie n .IP """sv_vsetpvf_mg""" 4
26616 .el .IP \f(CWsv_vsetpvf_mg\fR 4
26617 .IX Xref "sv_vsetpvf sv_vsetpvf_mg"
26618 .IX Item "sv_vsetpvf_mg"
26619 .PD
26620 These work like \f(CW"sv_vcatpvf"\fR but copy the text into the SV instead of
26621 appending it.
26622 .Sp
26623 They differ only in that \f(CW\*(C`sv_vsetpvf_mg\*(C'\fR performs 'set' magic;
26624 \&\f(CW\*(C`sv_vsetpvf\*(C'\fR skips all magic.
26625 .Sp
26626 They are usually used via their frontends, \f(CW"sv_setpvf"\fR and
26627 \&\f(CW"sv_setpvf_mg"\fR.
26628 .Sp
26629 \&\fBThe UTF\-8 flag is not changed by these functions.\fR
26630 .RS 4
26631 .Sp
26632 .Vb 2
26633 \& void sv_vsetpvf(SV * const sv, const char * const pat,
26634 \& va_list * const args)
26635 .Ve
26636 .RE
26637 .RS 4
26638 .RE
26639 .ie n .IP """sv_vsetpvfn""" 4
26640 .el .IP \f(CWsv_vsetpvfn\fR 4
26641 .IX Xref "sv_vsetpvfn"
26642 .IX Item "sv_vsetpvfn"
26643 Works like \f(CW\*(C`sv_vcatpvfn\*(C'\fR but copies the text into the SV instead of
26644 appending it.
26645 .Sp
26646 \&\fBThe UTF\-8 flag is not changed by this function.\fR
26647 .Sp
26648 Usually used via one of its frontends "\f(CW\*(C`sv_vsetpvf\*(C'\fR" and
26649 "\f(CW\*(C`sv_vsetpvf_mg\*(C'\fR".
26650 .RS 4
26651 .Sp
26652 .Vb 4
26653 \& void sv_vsetpvfn(SV * const sv, const char * const pat,
26654 \& const STRLEN patlen, va_list * const args,
26655 \& SV ** const svargs, const Size_t sv_count,
26656 \& bool * const maybe_tainted)
26657 .Ve
26658 .RE
26659 .RS 4
26660 .RE
26661 .ie n .IP """SvVSTRING_mg""" 4
26662 .el .IP \f(CWSvVSTRING_mg\fR 4
26663 .IX Xref "SvVSTRING_mg"
26664 .IX Item "SvVSTRING_mg"
26665 Returns the vstring magic, or NULL if none
26666 .RS 4
26667 .Sp
26668 .Vb 1
26669 \& MAGIC* SvVSTRING_mg(SV * sv)
26670 .Ve
26671 .RE
26672 .RS 4
26673 .RE
26674 .ie n .IP """vnewSVpvf""" 4
26675 .el .IP \f(CWvnewSVpvf\fR 4
26676 .IX Xref "vnewSVpvf"
26677 .IX Item "vnewSVpvf"
26678 Like \f(CW"newSVpvf"\fR but the arguments are an encapsulated argument list.
26679 .RS 4
26680 .Sp
26681 .Vb 1
26682 \& SV * vnewSVpvf(const char * const pat, va_list * const args)
26683 .Ve
26684 .RE
26685 .RS 4
26686 .RE
26687 .SH Tainting
26688 .IX Header "Tainting"
26689 .ie n .IP """SvTAINT""" 4
26690 .el .IP \f(CWSvTAINT\fR 4
26691 .IX Xref "SvTAINT"
26692 .IX Item "SvTAINT"
26693 Taints an SV if tainting is enabled, and if some input to the current
26694 expression is tainted\-\-usually a variable, but possibly also implicit
26695 inputs such as locale settings. \f(CW\*(C`SvTAINT\*(C'\fR propagates that taintedness to
26696 the outputs of an expression in a pessimistic fashion; i.e., without paying
26697 attention to precisely which outputs are influenced by which inputs.
26698 .RS 4
26699 .Sp
26700 .Vb 1
26701 \& void SvTAINT(SV* sv)
26702 .Ve
26703 .RE
26704 .RS 4
26705 .RE
26706 .ie n .IP """SvTAINTED""" 4
26707 .el .IP \f(CWSvTAINTED\fR 4
26708 .IX Xref "SvTAINTED"
26709 .IX Item "SvTAINTED"
26710 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
26711 not.
26712 .RS 4
26713 .Sp
26714 .Vb 1
26715 \& bool SvTAINTED(SV* sv)
26716 .Ve
26717 .RE
26718 .RS 4
26719 .RE
26720 .ie n .IP """SvTAINTED_off""" 4
26721 .el .IP \f(CWSvTAINTED_off\fR 4
26722 .IX Xref "SvTAINTED_off"
26723 .IX Item "SvTAINTED_off"
26724 Untaints an SV. Be \fIvery\fR careful with this routine, as it short-circuits
26725 some of Perl's fundamental security features. XS module authors should not
26726 use this function unless they fully understand all the implications of
26727 unconditionally untainting the value. Untainting should be done in the
26728 standard perl fashion, via a carefully crafted regexp, rather than directly
26729 untainting variables.
26730 .RS 4
26731 .Sp
26732 .Vb 1
26733 \& void SvTAINTED_off(SV* sv)
26734 .Ve
26735 .RE
26736 .RS 4
26737 .RE
26738 .ie n .IP """SvTAINTED_on""" 4
26739 .el .IP \f(CWSvTAINTED_on\fR 4
26740 .IX Xref "SvTAINTED_on"
26741 .IX Item "SvTAINTED_on"
26742 Marks an SV as tainted if tainting is enabled.
26743 .RS 4
26744 .Sp
26745 .Vb 1
26746 \& void SvTAINTED_on(SV* sv)
26747 .Ve
26748 .RE
26749 .RS 4
26750 .RE
26751 .SH Time
26752 .IX Header "Time"
26753 .ie n .IP """ASCTIME_R_PROTO""" 4
26754 .el .IP \f(CWASCTIME_R_PROTO\fR 4
26755 .IX Xref "ASCTIME_R_PROTO"
26756 .IX Item "ASCTIME_R_PROTO"
26757 This symbol encodes the prototype of \f(CW\*(C`asctime_r\*(C'\fR.
26758 It is zero if \f(CW\*(C`d_asctime_r\*(C'\fR is undef, and one of the
26759 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_asctime_r\*(C'\fR
26760 is defined.
26761 .ie n .IP """CTIME_R_PROTO""" 4
26762 .el .IP \f(CWCTIME_R_PROTO\fR 4
26763 .IX Xref "CTIME_R_PROTO"
26764 .IX Item "CTIME_R_PROTO"
26765 This symbol encodes the prototype of \f(CW\*(C`ctime_r\*(C'\fR.
26766 It is zero if \f(CW\*(C`d_ctime_r\*(C'\fR is undef, and one of the
26767 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctime_r\*(C'\fR
26768 is defined.
26769 .ie n .IP """GMTIME_MAX""" 4
26770 .el .IP \f(CWGMTIME_MAX\fR 4
26771 .IX Xref "GMTIME_MAX"
26772 .IX Item "GMTIME_MAX"
26773 This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that
26774 the system function gmtime () accepts, and defaults to 0
26775 .ie n .IP """GMTIME_MIN""" 4
26776 .el .IP \f(CWGMTIME_MIN\fR 4
26777 .IX Xref "GMTIME_MIN"
26778 .IX Item "GMTIME_MIN"
26779 This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that
26780 the system function gmtime () accepts, and defaults to 0
26781 .ie n .IP """GMTIME_R_PROTO""" 4
26782 .el .IP \f(CWGMTIME_R_PROTO\fR 4
26783 .IX Xref "GMTIME_R_PROTO"
26784 .IX Item "GMTIME_R_PROTO"
26785 This symbol encodes the prototype of \f(CW\*(C`gmtime_r\*(C'\fR.
26786 It is zero if \f(CW\*(C`d_gmtime_r\*(C'\fR is undef, and one of the
26787 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gmtime_r\*(C'\fR
26788 is defined.
26789 .ie n .IP """HAS_ASCTIME_R""" 4
26790 .el .IP \f(CWHAS_ASCTIME_R\fR 4
26791 .IX Xref "HAS_ASCTIME_R"
26792 .IX Item "HAS_ASCTIME_R"
26793 This symbol, if defined, indicates that the \f(CW\*(C`asctime_r\*(C'\fR routine
26794 is available to asctime re-entrantly.
26795 .ie n .IP """HAS_ASCTIME64""" 4
26796 .el .IP \f(CWHAS_ASCTIME64\fR 4
26797 .IX Xref "HAS_ASCTIME64"
26798 .IX Item "HAS_ASCTIME64"
26799 This symbol, if defined, indicates that the \f(CW\*(C`asctime64\*(C'\fR () routine is
26800 available to do the 64bit variant of asctime ()
26801 .ie n .IP """HAS_CTIME_R""" 4
26802 .el .IP \f(CWHAS_CTIME_R\fR 4
26803 .IX Xref "HAS_CTIME_R"
26804 .IX Item "HAS_CTIME_R"
26805 This symbol, if defined, indicates that the \f(CW\*(C`ctime_r\*(C'\fR routine
26806 is available to ctime re-entrantly.
26807 .ie n .IP """HAS_CTIME64""" 4
26808 .el .IP \f(CWHAS_CTIME64\fR 4
26809 .IX Xref "HAS_CTIME64"
26810 .IX Item "HAS_CTIME64"
26811 This symbol, if defined, indicates that the \f(CW\*(C`ctime64\*(C'\fR () routine is
26812 available to do the 64bit variant of ctime ()
26813 .ie n .IP """HAS_DIFFTIME""" 4
26814 .el .IP \f(CWHAS_DIFFTIME\fR 4
26815 .IX Xref "HAS_DIFFTIME"
26816 .IX Item "HAS_DIFFTIME"
26817 This symbol, if defined, indicates that the \f(CW\*(C`difftime\*(C'\fR routine is
26818 available.
26819 .ie n .IP """HAS_DIFFTIME64""" 4
26820 .el .IP \f(CWHAS_DIFFTIME64\fR 4
26821 .IX Xref "HAS_DIFFTIME64"
26822 .IX Item "HAS_DIFFTIME64"
26823 This symbol, if defined, indicates that the \f(CW\*(C`difftime64\*(C'\fR () routine is
26824 available to do the 64bit variant of difftime ()
26825 .ie n .IP """HAS_FUTIMES""" 4
26826 .el .IP \f(CWHAS_FUTIMES\fR 4
26827 .IX Xref "HAS_FUTIMES"
26828 .IX Item "HAS_FUTIMES"
26829 This symbol, if defined, indicates that the \f(CW\*(C`futimes\*(C'\fR routine is
26830 available to change file descriptor time stamps with \f(CW\*(C`struct timevals\*(C'\fR.
26831 .ie n .IP """HAS_GETITIMER""" 4
26832 .el .IP \f(CWHAS_GETITIMER\fR 4
26833 .IX Xref "HAS_GETITIMER"
26834 .IX Item "HAS_GETITIMER"
26835 This symbol, if defined, indicates that the \f(CW\*(C`getitimer\*(C'\fR routine is
26836 available to return interval timers.
26837 .ie n .IP """HAS_GETTIMEOFDAY""" 4
26838 .el .IP \f(CWHAS_GETTIMEOFDAY\fR 4
26839 .IX Xref "HAS_GETTIMEOFDAY"
26840 .IX Item "HAS_GETTIMEOFDAY"
26841 This symbol, if defined, indicates that the \f(CWgettimeofday()\fR system
26842 call is available for a sub-second accuracy clock. Usually, the file
26843 \&\fIsys/resource.h\fR needs to be included (see \f(CW"I_SYS_RESOURCE"\fR).
26844 The type "Timeval" should be used to refer to "\f(CW\*(C`struct timeval\*(C'\fR".
26845 .ie n .IP """HAS_GMTIME_R""" 4
26846 .el .IP \f(CWHAS_GMTIME_R\fR 4
26847 .IX Xref "HAS_GMTIME_R"
26848 .IX Item "HAS_GMTIME_R"
26849 This symbol, if defined, indicates that the \f(CW\*(C`gmtime_r\*(C'\fR routine
26850 is available to gmtime re-entrantly.
26851 .ie n .IP """HAS_GMTIME64""" 4
26852 .el .IP \f(CWHAS_GMTIME64\fR 4
26853 .IX Xref "HAS_GMTIME64"
26854 .IX Item "HAS_GMTIME64"
26855 This symbol, if defined, indicates that the \f(CW\*(C`gmtime64\*(C'\fR () routine is
26856 available to do the 64bit variant of gmtime ()
26857 .ie n .IP """HAS_LOCALTIME_R""" 4
26858 .el .IP \f(CWHAS_LOCALTIME_R\fR 4
26859 .IX Xref "HAS_LOCALTIME_R"
26860 .IX Item "HAS_LOCALTIME_R"
26861 This symbol, if defined, indicates that the \f(CW\*(C`localtime_r\*(C'\fR routine
26862 is available to localtime re-entrantly.
26863 .ie n .IP """HAS_LOCALTIME64""" 4
26864 .el .IP \f(CWHAS_LOCALTIME64\fR 4
26865 .IX Xref "HAS_LOCALTIME64"
26866 .IX Item "HAS_LOCALTIME64"
26867 This symbol, if defined, indicates that the \f(CW\*(C`localtime64\*(C'\fR () routine is
26868 available to do the 64bit variant of localtime ()
26869 .ie n .IP """HAS_MKTIME""" 4
26870 .el .IP \f(CWHAS_MKTIME\fR 4
26871 .IX Xref "HAS_MKTIME"
26872 .IX Item "HAS_MKTIME"
26873 This symbol, if defined, indicates that the \f(CW\*(C`mktime\*(C'\fR routine is
26874 available.
26875 .ie n .IP """HAS_MKTIME64""" 4
26876 .el .IP \f(CWHAS_MKTIME64\fR 4
26877 .IX Xref "HAS_MKTIME64"
26878 .IX Item "HAS_MKTIME64"
26879 This symbol, if defined, indicates that the \f(CW\*(C`mktime64\*(C'\fR () routine is
26880 available to do the 64bit variant of mktime ()
26881 .ie n .IP """HAS_NANOSLEEP""" 4
26882 .el .IP \f(CWHAS_NANOSLEEP\fR 4
26883 .IX Xref "HAS_NANOSLEEP"
26884 .IX Item "HAS_NANOSLEEP"
26885 This symbol, if defined, indicates that the \f(CW\*(C`nanosleep\*(C'\fR
26886 system call is available to sleep with 1E\-9 sec accuracy.
26887 .ie n .IP """HAS_SETITIMER""" 4
26888 .el .IP \f(CWHAS_SETITIMER\fR 4
26889 .IX Xref "HAS_SETITIMER"
26890 .IX Item "HAS_SETITIMER"
26891 This symbol, if defined, indicates that the \f(CW\*(C`setitimer\*(C'\fR routine is
26892 available to set interval timers.
26893 .ie n .IP """HAS_STRFTIME""" 4
26894 .el .IP \f(CWHAS_STRFTIME\fR 4
26895 .IX Xref "HAS_STRFTIME"
26896 .IX Item "HAS_STRFTIME"
26897 This symbol, if defined, indicates that the \f(CW\*(C`strftime\*(C'\fR routine is
26898 available to do time formatting.
26899 .ie n .IP """HAS_TIME""" 4
26900 .el .IP \f(CWHAS_TIME\fR 4
26901 .IX Xref "HAS_TIME"
26902 .IX Item "HAS_TIME"
26903 This symbol, if defined, indicates that the \f(CWtime()\fR routine exists.
26904 .ie n .IP """HAS_TIMEGM""" 4
26905 .el .IP \f(CWHAS_TIMEGM\fR 4
26906 .IX Xref "HAS_TIMEGM"
26907 .IX Item "HAS_TIMEGM"
26908 This symbol, if defined, indicates that the \f(CW\*(C`timegm\*(C'\fR routine is
26909 available to do the opposite of gmtime ()
26910 .ie n .IP """HAS_TIMES""" 4
26911 .el .IP \f(CWHAS_TIMES\fR 4
26912 .IX Xref "HAS_TIMES"
26913 .IX Item "HAS_TIMES"
26914 This symbol, if defined, indicates that the \f(CWtimes()\fR routine exists.
26915 Note that this became obsolete on some systems (\f(CW\*(C`SUNOS\*(C'\fR), which now
26916 use \f(CWgetrusage()\fR. It may be necessary to include \fIsys/times.h\fR.
26917 .ie n .IP """HAS_TM_TM_GMTOFF""" 4
26918 .el .IP \f(CWHAS_TM_TM_GMTOFF\fR 4
26919 .IX Xref "HAS_TM_TM_GMTOFF"
26920 .IX Item "HAS_TM_TM_GMTOFF"
26921 This symbol, if defined, indicates to the C program that
26922 the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_gmtoff\*(C'\fR field.
26923 .ie n .IP """HAS_TM_TM_ZONE""" 4
26924 .el .IP \f(CWHAS_TM_TM_ZONE\fR 4
26925 .IX Xref "HAS_TM_TM_ZONE"
26926 .IX Item "HAS_TM_TM_ZONE"
26927 This symbol, if defined, indicates to the C program that
26928 the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_zone\*(C'\fR field.
26929 .ie n .IP """HAS_TZNAME""" 4
26930 .el .IP \f(CWHAS_TZNAME\fR 4
26931 .IX Xref "HAS_TZNAME"
26932 .IX Item "HAS_TZNAME"
26933 This symbol, if defined, indicates that the \f(CW\*(C`tzname[]\*(C'\fR array is
26934 available to access timezone names.
26935 .ie n .IP """HAS_USLEEP""" 4
26936 .el .IP \f(CWHAS_USLEEP\fR 4
26937 .IX Xref "HAS_USLEEP"
26938 .IX Item "HAS_USLEEP"
26939 This symbol, if defined, indicates that the \f(CW\*(C`usleep\*(C'\fR routine is
26940 available to let the process sleep on a sub-second accuracy.
26941 .ie n .IP """HAS_USLEEP_PROTO""" 4
26942 .el .IP \f(CWHAS_USLEEP_PROTO\fR 4
26943 .IX Xref "HAS_USLEEP_PROTO"
26944 .IX Item "HAS_USLEEP_PROTO"
26945 This symbol, if defined, indicates that the system provides
26946 a prototype for the \f(CWusleep()\fR function. Otherwise, it is up
26947 to the program to supply one. A good guess is
26948 .Sp
26949 .Vb 1
26950 \& extern int usleep(useconds_t);
26951 .Ve
26952 .ie n .IP """I_TIME""" 4
26953 .el .IP \f(CWI_TIME\fR 4
26954 .IX Xref "I_TIME"
26955 .IX Item "I_TIME"
26956 This symbol is always defined, and indicates to the C program that
26957 it should include \fItime.h\fR.
26958 .RS 4
26959 .Sp
26960 .Vb 3
26961 \& #ifdef I_TIME
26962 \& #include <time.h>
26963 \& #endif
26964 .Ve
26965 .RE
26966 .RS 4
26967 .RE
26968 .ie n .IP """I_UTIME""" 4
26969 .el .IP \f(CWI_UTIME\fR 4
26970 .IX Xref "I_UTIME"
26971 .IX Item "I_UTIME"
26972 This symbol, if defined, indicates to the C program that it should
26973 include \fIutime.h\fR.
26974 .RS 4
26975 .Sp
26976 .Vb 3
26977 \& #ifdef I_UTIME
26978 \& #include <utime.h>
26979 \& #endif
26980 .Ve
26981 .RE
26982 .RS 4
26983 .RE
26984 .ie n .IP """LOCALTIME_MAX""" 4
26985 .el .IP \f(CWLOCALTIME_MAX\fR 4
26986 .IX Xref "LOCALTIME_MAX"
26987 .IX Item "LOCALTIME_MAX"
26988 This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that
26989 the system function localtime () accepts, and defaults to 0
26990 .ie n .IP """LOCALTIME_MIN""" 4
26991 .el .IP \f(CWLOCALTIME_MIN\fR 4
26992 .IX Xref "LOCALTIME_MIN"
26993 .IX Item "LOCALTIME_MIN"
26994 This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that
26995 the system function localtime () accepts, and defaults to 0
26996 .ie n .IP """LOCALTIME_R_NEEDS_TZSET""" 4
26997 .el .IP \f(CWLOCALTIME_R_NEEDS_TZSET\fR 4
26998 .IX Xref "LOCALTIME_R_NEEDS_TZSET"
26999 .IX Item "LOCALTIME_R_NEEDS_TZSET"
27000 Many libc's \f(CW\*(C`localtime_r\*(C'\fR implementations do not call tzset,
27001 making them differ from \f(CWlocaltime()\fR, and making timezone
27002 changes using $\f(CW\*(C`ENV\*(C'\fR{TZ} without explicitly calling tzset
27003 impossible. This symbol makes us call tzset before \f(CW\*(C`localtime_r\*(C'\fR
27004 .ie n .IP """LOCALTIME_R_PROTO""" 4
27005 .el .IP \f(CWLOCALTIME_R_PROTO\fR 4
27006 .IX Xref "LOCALTIME_R_PROTO"
27007 .IX Item "LOCALTIME_R_PROTO"
27008 This symbol encodes the prototype of \f(CW\*(C`localtime_r\*(C'\fR.
27009 It is zero if \f(CW\*(C`d_localtime_r\*(C'\fR is undef, and one of the
27010 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_localtime_r\*(C'\fR
27011 is defined.
27012 .ie n .IP """L_R_TZSET""" 4
27013 .el .IP \f(CWL_R_TZSET\fR 4
27014 .IX Xref "L_R_TZSET"
27015 .IX Item "L_R_TZSET"
27016 If \f(CWlocaltime_r()\fR needs tzset, it is defined in this define
27017 .ie n .IP """mini_mktime""" 4
27018 .el .IP \f(CWmini_mktime\fR 4
27019 .IX Xref "mini_mktime"
27020 .IX Item "mini_mktime"
27021 normalise \f(CW\*(C`struct\ tm\*(C'\fR values without the \fBlocaltime()\fR semantics (and
27022 overhead) of \fBmktime()\fR.
27023 .RS 4
27024 .Sp
27025 .Vb 1
27026 \& void mini_mktime(struct tm *ptm)
27027 .Ve
27028 .RE
27029 .RS 4
27030 .RE
27031 .ie n .IP """sv_strftime_tm""" 4
27032 .el .IP \f(CWsv_strftime_tm\fR 4
27033 .IX Item "sv_strftime_tm"
27034 .PD 0
27035 .ie n .IP """my_strftime""" 4
27036 .el .IP \f(CWmy_strftime\fR 4
27037 .IX Xref "sv_strftime_tm my_strftime"
27038 .IX Item "my_strftime"
27039 .PD
27040 These implement the libc \fBstrftime()\fR.
27041 .Sp
27042 On failure, they return NULL, and set \f(CW\*(C`errno\*(C'\fR to \f(CW\*(C`EINVAL\*(C'\fR.
27043 .Sp
27044 \&\f(CW\*(C`sv_strftime_tm\*(C'\fR is preferred, as it transparently handles the UTF\-8ness of
27045 the current locale, the input \f(CW\*(C`fmt\*(C'\fR, and the returned result. Only if the
27046 current \f(CW\*(C`LC_TIME\*(C'\fR locale is a UTF\-8 one (and \f(CW\*(C`use\ bytes\*(C'\fR is not in effect)
27047 will the result be marked as UTF\-8.
27048 .Sp
27049 \&\f(CW\*(C`sv_strftime_tm\*(C'\fR takes a pointer to a filled-in \f(CW\*(C`struct\ tm\*(C'\fR parameter. It
27050 ignores the values of the \f(CW\*(C`wday\*(C'\fR and \f(CW\*(C`yday\*(C'\fR fields in it. The other fields
27051 give enough information to accurately calculate these values, and are used for
27052 that purpose.
27053 .Sp
27054 The caller assumes ownership of the returned SV with a reference count of 1.
27055 .Sp
27056 \&\f(CW\*(C`my_strftime\*(C'\fR is kept for backwards compatibility. Knowing if its result
27057 should be considered UTF\-8 or not requires significant extra logic.
27058 .Sp
27059 The return value is a pointer to the formatted result (which MUST be arranged
27060 to be FREED BY THE CALLER). This allows this function to increase the buffer
27061 size as needed, so that the caller doesn't have to worry about that, unlike
27062 libc \f(CWstrftime()\fR.
27063 .Sp
27064 The \f(CW\*(C`wday\*(C'\fR, \f(CW\*(C`yday\*(C'\fR, and \f(CW\*(C`isdst\*(C'\fR parameters are ignored by \f(CW\*(C`my_strftime\*(C'\fR.
27065 Daylight savings time is never considered to exist, and the values returned for
27066 the other two fields (if \f(CW\*(C`fmt\*(C'\fR even calls for them) are calculated from the
27067 other parameters, without need for referencing these.
27068 .Sp
27069 Note that both functions are always executed in the underlying
27070 \&\f(CW\*(C`LC_TIME\*(C'\fR locale of the program, giving results based on that locale.
27071 .RS 4
27072 .Sp
27073 .Vb 4
27074 \& SV * sv_strftime_tm(SV *fmt, const struct tm *mytm)
27075 \& char * my_strftime (const char *fmt, int sec, int min,
27076 \& int hour, int mday, int mon, int year,
27077 \& int wday, int yday, int isdst)
27078 .Ve
27079 .RE
27080 .RS 4
27081 .RE
27082 .SH "Typedef names"
27083 .IX Header "Typedef names"
27084 .ie n .IP """DB_Hash_t""" 4
27085 .el .IP \f(CWDB_Hash_t\fR 4
27086 .IX Xref "DB_Hash_t"
27087 .IX Item "DB_Hash_t"
27088 This symbol contains the type of the prefix structure element
27089 in the \fIdb.h\fR header file. In older versions of DB, it was
27090 int, while in newer ones it is \f(CW\*(C`size_t\*(C'\fR.
27091 .ie n .IP """DB_Prefix_t""" 4
27092 .el .IP \f(CWDB_Prefix_t\fR 4
27093 .IX Xref "DB_Prefix_t"
27094 .IX Item "DB_Prefix_t"
27095 This symbol contains the type of the prefix structure element
27096 in the \fIdb.h\fR header file. In older versions of DB, it was
27097 int, while in newer ones it is \f(CW\*(C`u_int32_t\*(C'\fR.
27098 .ie n .IP """Direntry_t""" 4
27099 .el .IP \f(CWDirentry_t\fR 4
27100 .IX Xref "Direntry_t"
27101 .IX Item "Direntry_t"
27102 This symbol is set to '\f(CW\*(C`struct direct\*(C'\fR' or '\f(CW\*(C`struct dirent\*(C'\fR' depending on
27103 whether dirent is available or not. You should use this pseudo type to
27104 portably declare your directory entries.
27105 .ie n .IP """Fpos_t""" 4
27106 .el .IP \f(CWFpos_t\fR 4
27107 .IX Xref "Fpos_t"
27108 .IX Item "Fpos_t"
27109 This symbol holds the type used to declare file positions in libc.
27110 It can be \f(CW\*(C`fpos_t\*(C'\fR, long, uint, etc... It may be necessary to include
27111 \&\fIsys/types.h\fR to get any typedef'ed information.
27112 .ie n .IP """Free_t""" 4
27113 .el .IP \f(CWFree_t\fR 4
27114 .IX Xref "Free_t"
27115 .IX Item "Free_t"
27116 This variable contains the return type of \f(CWfree()\fR. It is usually
27117 void, but occasionally int.
27118 .ie n .IP """Gid_t""" 4
27119 .el .IP \f(CWGid_t\fR 4
27120 .IX Xref "Gid_t"
27121 .IX Item "Gid_t"
27122 This symbol holds the return type of \f(CWgetgid()\fR and the type of
27123 argument to \f(CWsetrgid()\fR and related functions. Typically,
27124 it is the type of group ids in the kernel. It can be int, ushort,
27125 \&\f(CW\*(C`gid_t\*(C'\fR, etc... It may be necessary to include \fIsys/types.h\fR to get
27126 any typedef'ed information.
27127 .ie n .IP """Gid_t_f""" 4
27128 .el .IP \f(CWGid_t_f\fR 4
27129 .IX Xref "Gid_t_f"
27130 .IX Item "Gid_t_f"
27131 This symbol defines the format string used for printing a \f(CW\*(C`Gid_t\*(C'\fR.
27132 .ie n .IP """Gid_t_sign""" 4
27133 .el .IP \f(CWGid_t_sign\fR 4
27134 .IX Xref "Gid_t_sign"
27135 .IX Item "Gid_t_sign"
27136 This symbol holds the signedness of a \f(CW\*(C`Gid_t\*(C'\fR.
27137 1 for unsigned, \-1 for signed.
27138 .ie n .IP """Gid_t_size""" 4
27139 .el .IP \f(CWGid_t_size\fR 4
27140 .IX Xref "Gid_t_size"
27141 .IX Item "Gid_t_size"
27142 This symbol holds the size of a \f(CW\*(C`Gid_t\*(C'\fR in bytes.
27143 .ie n .IP """Groups_t""" 4
27144 .el .IP \f(CWGroups_t\fR 4
27145 .IX Xref "Groups_t"
27146 .IX Item "Groups_t"
27147 This symbol holds the type used for the second argument to
27148 \&\f(CWgetgroups()\fR and \f(CWsetgroups()\fR. Usually, this is the same as
27149 gidtype (\f(CW\*(C`gid_t\*(C'\fR) , but sometimes it isn't.
27150 It can be int, ushort, \f(CW\*(C`gid_t\*(C'\fR, etc...
27151 It may be necessary to include \fIsys/types.h\fR to get any
27152 typedef'ed information. This is only required if you have
27153 \&\f(CWgetgroups()\fR or \f(CWsetgroups()\fR..
27154 .ie n .IP """Malloc_t""" 4
27155 .el .IP \f(CWMalloc_t\fR 4
27156 .IX Xref "Malloc_t"
27157 .IX Item "Malloc_t"
27158 This symbol is the type of pointer returned by malloc and realloc.
27159 .ie n .IP """Mmap_t""" 4
27160 .el .IP \f(CWMmap_t\fR 4
27161 .IX Xref "Mmap_t"
27162 .IX Item "Mmap_t"
27163 This symbol holds the return type of the \f(CWmmap()\fR system call
27164 (and simultaneously the type of the first argument).
27165 Usually set to 'void *' or '\f(CW\*(C`caddr_t\*(C'\fR'.
27166 .ie n .IP """Mode_t""" 4
27167 .el .IP \f(CWMode_t\fR 4
27168 .IX Xref "Mode_t"
27169 .IX Item "Mode_t"
27170 This symbol holds the type used to declare file modes
27171 for systems calls. It is usually \f(CW\*(C`mode_t\*(C'\fR, but may be
27172 int or unsigned short. It may be necessary to include \fIsys/types.h\fR
27173 to get any typedef'ed information.
27174 .ie n .IP """Netdb_hlen_t""" 4
27175 .el .IP \f(CWNetdb_hlen_t\fR 4
27176 .IX Xref "Netdb_hlen_t"
27177 .IX Item "Netdb_hlen_t"
27178 This symbol holds the type used for the 2nd argument
27179 to \f(CWgethostbyaddr()\fR.
27180 .ie n .IP """Netdb_host_t""" 4
27181 .el .IP \f(CWNetdb_host_t\fR 4
27182 .IX Xref "Netdb_host_t"
27183 .IX Item "Netdb_host_t"
27184 This symbol holds the type used for the 1st argument
27185 to \f(CWgethostbyaddr()\fR.
27186 .ie n .IP """Netdb_name_t""" 4
27187 .el .IP \f(CWNetdb_name_t\fR 4
27188 .IX Xref "Netdb_name_t"
27189 .IX Item "Netdb_name_t"
27190 This symbol holds the type used for the argument to
27191 \&\f(CWgethostbyname()\fR.
27192 .ie n .IP """Netdb_net_t""" 4
27193 .el .IP \f(CWNetdb_net_t\fR 4
27194 .IX Xref "Netdb_net_t"
27195 .IX Item "Netdb_net_t"
27196 This symbol holds the type used for the 1st argument to
27197 \&\f(CWgetnetbyaddr()\fR.
27198 .ie n .IP """Off_t""" 4
27199 .el .IP \f(CWOff_t\fR 4
27200 .IX Xref "Off_t"
27201 .IX Item "Off_t"
27202 This symbol holds the type used to declare offsets in the kernel.
27203 It can be int, long, \f(CW\*(C`off_t\*(C'\fR, etc... It may be necessary to include
27204 \&\fIsys/types.h\fR to get any typedef'ed information.
27205 .ie n .IP """Off_t_size""" 4
27206 .el .IP \f(CWOff_t_size\fR 4
27207 .IX Xref "Off_t_size"
27208 .IX Item "Off_t_size"
27209 This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR.
27210 .ie n .IP """Pid_t""" 4
27211 .el .IP \f(CWPid_t\fR 4
27212 .IX Xref "Pid_t"
27213 .IX Item "Pid_t"
27214 This symbol holds the type used to declare process ids in the kernel.
27215 It can be int, uint, \f(CW\*(C`pid_t\*(C'\fR, etc... It may be necessary to include
27216 \&\fIsys/types.h\fR to get any typedef'ed information.
27217 .ie n .IP """Rand_seed_t""" 4
27218 .el .IP \f(CWRand_seed_t\fR 4
27219 .IX Xref "Rand_seed_t"
27220 .IX Item "Rand_seed_t"
27221 This symbol defines the type of the argument of the
27222 random seed function.
27223 .ie n .IP """Select_fd_set_t""" 4
27224 .el .IP \f(CWSelect_fd_set_t\fR 4
27225 .IX Xref "Select_fd_set_t"
27226 .IX Item "Select_fd_set_t"
27227 This symbol holds the type used for the 2nd, 3rd, and 4th
27228 arguments to select. Usually, this is '\f(CW\*(C`fd_set\*(C'\fR *', if \f(CW\*(C`HAS_FD_SET\*(C'\fR
27229 is defined, and 'int *' otherwise. This is only useful if you
27230 have \f(CWselect()\fR, of course.
27231 .ie n .IP """Shmat_t""" 4
27232 .el .IP \f(CWShmat_t\fR 4
27233 .IX Xref "Shmat_t"
27234 .IX Item "Shmat_t"
27235 This symbol holds the return type of the \f(CWshmat()\fR system call.
27236 Usually set to 'void *' or 'char *'.
27237 .ie n .IP """Signal_t""" 4
27238 .el .IP \f(CWSignal_t\fR 4
27239 .IX Xref "Signal_t"
27240 .IX Item "Signal_t"
27241 This symbol's value is either "void" or "int", corresponding to the
27242 appropriate return type of a signal handler. Thus, you can declare
27243 a signal handler using "\f(CW\*(C`Signal_t\*(C'\fR (*handler)()", and define the
27244 handler using "\f(CW\*(C`Signal_t\*(C'\fR \f(CWhandler(sig)\fR".
27245 .ie n .IP """Size_t""" 4
27246 .el .IP \f(CWSize_t\fR 4
27247 .IX Xref "Size_t"
27248 .IX Item "Size_t"
27249 This symbol holds the type used to declare length parameters
27250 for string functions. It is usually \f(CW\*(C`size_t\*(C'\fR, but may be
27251 unsigned long, int, etc. It may be necessary to include
27252 \&\fIsys/types.h\fR to get any typedef'ed information.
27253 .ie n .IP """Size_t_size""" 4
27254 .el .IP \f(CWSize_t_size\fR 4
27255 .IX Xref "Size_t_size"
27256 .IX Item "Size_t_size"
27257 This symbol holds the size of a \f(CW\*(C`Size_t\*(C'\fR in bytes.
27258 .ie n .IP """Sock_size_t""" 4
27259 .el .IP \f(CWSock_size_t\fR 4
27260 .IX Xref "Sock_size_t"
27261 .IX Item "Sock_size_t"
27262 This symbol holds the type used for the size argument of
27263 various socket calls (just the base type, not the pointer-to).
27264 .ie n .IP """SSize_t""" 4
27265 .el .IP \f(CWSSize_t\fR 4
27266 .IX Xref "SSize_t"
27267 .IX Item "SSize_t"
27268 This symbol holds the type used by functions that return
27269 a count of bytes or an error condition. It must be a signed type.
27270 It is usually \f(CW\*(C`ssize_t\*(C'\fR, but may be long or int, etc.
27271 It may be necessary to include \fIsys/types.h\fR or \fIunistd.h\fR
27272 to get any typedef'ed information.
27273 We will pick a type such that \f(CWsizeof(SSize_t)\fR == \f(CWsizeof(Size_t)\fR.
27274 .ie n .IP """Time_t""" 4
27275 .el .IP \f(CWTime_t\fR 4
27276 .IX Xref "Time_t"
27277 .IX Item "Time_t"
27278 This symbol holds the type returned by \f(CWtime()\fR. It can be long,
27279 or \f(CW\*(C`time_t\*(C'\fR on \f(CW\*(C`BSD\*(C'\fR sites (in which case \fIsys/types.h\fR should be
27280 included).
27281 .ie n .IP """Uid_t""" 4
27282 .el .IP \f(CWUid_t\fR 4
27283 .IX Xref "Uid_t"
27284 .IX Item "Uid_t"
27285 This symbol holds the type used to declare user ids in the kernel.
27286 It can be int, ushort, \f(CW\*(C`uid_t\*(C'\fR, etc... It may be necessary to include
27287 \&\fIsys/types.h\fR to get any typedef'ed information.
27288 .ie n .IP """Uid_t_f""" 4
27289 .el .IP \f(CWUid_t_f\fR 4
27290 .IX Xref "Uid_t_f"
27291 .IX Item "Uid_t_f"
27292 This symbol defines the format string used for printing a \f(CW\*(C`Uid_t\*(C'\fR.
27293 .ie n .IP """Uid_t_sign""" 4
27294 .el .IP \f(CWUid_t_sign\fR 4
27295 .IX Xref "Uid_t_sign"
27296 .IX Item "Uid_t_sign"
27297 This symbol holds the signedness of a \f(CW\*(C`Uid_t\*(C'\fR.
27298 1 for unsigned, \-1 for signed.
27299 .ie n .IP """Uid_t_size""" 4
27300 .el .IP \f(CWUid_t_size\fR 4
27301 .IX Xref "Uid_t_size"
27302 .IX Item "Uid_t_size"
27303 This symbol holds the size of a \f(CW\*(C`Uid_t\*(C'\fR in bytes.
27304 .SH "Unicode Support"
27305 .IX Xref "UNICODE_DISALLOW_ABOVE_31_BIT UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE UNICODE_DISALLOW_ILLEGAL_INTERCHANGE UNICODE_DISALLOW_NONCHAR UNICODE_DISALLOW_PERL_EXTENDED UNICODE_DISALLOW_SUPER UNICODE_DISALLOW_SURROGATE UNICODE_WARN_ABOVE_31_BIT UNICODE_WARN_ILLEGAL_C9_INTERCHANGE UNICODE_WARN_ILLEGAL_INTERCHANGE UNICODE_WARN_NONCHAR UNICODE_WARN_PERL_EXTENDED UNICODE_WARN_SUPER UNICODE_WARN_SURROGATE UNI_DISPLAY_BACKSLASH UNI_DISPLAY_BACKSPACE UNI_DISPLAY_ISPRINT UNI_DISPLAY_QQ UNI_DISPLAY_REGEX UTF8_CHECK_ONLY UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE UTF8_DISALLOW_ILLEGAL_INTERCHANGE UTF8_DISALLOW_NONCHAR UTF8_DISALLOW_PERL_EXTENDED UTF8_DISALLOW_SUPER UTF8_DISALLOW_SURROGATE UTF8_GOT_CONTINUATION UTF8_GOT_EMPTY UTF8_GOT_LONG UTF8_GOT_NONCHAR UTF8_GOT_NON_CONTINUATION UTF8_GOT_OVERFLOW UTF8_GOT_PERL_EXTENDED UTF8_GOT_SHORT UTF8_GOT_SUPER UTF8_GOT_SURROGATE UTF8_WARN_ILLEGAL_C9_INTERCHANGE UTF8_WARN_ILLEGAL_INTERCHANGE UTF8_WARN_NONCHAR UTF8_WARN_PERL_EXTENDED UTF8_WARN_SUPER UTF8_WARN_SURROGATE"
27306 .IX Header "Unicode Support"
27307 "Unicode Support" in perlguts has an introduction to this API.
27308 .PP
27309 See also \f(CW"Character classification"\fR,
27310 \&\f(CW"Character case changing"\fR,
27311 and \f(CW"String Handling"\fR.
27312 Various functions outside this section also work specially with
27313 Unicode. Search for the string "utf8" in this document.
27314 .ie n .IP """BOM_UTF8""" 4
27315 .el .IP \f(CWBOM_UTF8\fR 4
27316 .IX Xref "BOM_UTF8"
27317 .IX Item "BOM_UTF8"
27318 This is a macro that evaluates to a string constant of the UTF\-8 bytes that
27319 define the Unicode BYTE ORDER MARK (U+FEFF) for the platform that perl
27320 is compiled on. This allows code to use a mnemonic for this character that
27321 works on both ASCII and EBCDIC platforms.
27322 \&\f(CW\*(C`sizeof(BOM_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in
27323 bytes.
27324 .ie n .IP """bytes_cmp_utf8""" 4
27325 .el .IP \f(CWbytes_cmp_utf8\fR 4
27326 .IX Xref "bytes_cmp_utf8"
27327 .IX Item "bytes_cmp_utf8"
27328 Compares the sequence of characters (stored as octets) in \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`blen\*(C'\fR with the
27329 sequence of characters (stored as UTF\-8)
27330 in \f(CW\*(C`u\*(C'\fR, \f(CW\*(C`ulen\*(C'\fR. Returns 0 if they are
27331 equal, \-1 or \-2 if the first string is less than the second string, +1 or +2
27332 if the first string is greater than the second string.
27333 .Sp
27334 \&\-1 or +1 is returned if the shorter string was identical to the start of the
27335 longer string. \-2 or +2 is returned if
27336 there was a difference between characters
27337 within the strings.
27338 .RS 4
27339 .Sp
27340 .Vb 2
27341 \& int bytes_cmp_utf8(const U8 *b, STRLEN blen, const U8 *u,
27342 \& STRLEN ulen)
27343 .Ve
27344 .RE
27345 .RS 4
27346 .RE
27347 .ie n .IP """bytes_from_utf8""" 4
27348 .el .IP \f(CWbytes_from_utf8\fR 4
27349 .IX Xref "bytes_from_utf8"
27350 .IX Item "bytes_from_utf8"
27351 NOTE: \f(CW\*(C`bytes_from_utf8\*(C'\fR is \fBexperimental\fR and may change or be
27352 removed without notice.
27353 .Sp
27354 Converts a potentially UTF\-8 encoded string \f(CW\*(C`s\*(C'\fR of length \f(CW*lenp\fR into native
27355 byte encoding. On input, the boolean \f(CW*is_utf8p\fR gives whether or not \f(CW\*(C`s\*(C'\fR is
27356 actually encoded in UTF\-8.
27357 .Sp
27358 Unlike "utf8_to_bytes" but like "bytes_to_utf8", this is non-destructive of
27359 the input string.
27360 .Sp
27361 Do nothing if \f(CW*is_utf8p\fR is 0, or if there are code points in the string
27362 not expressible in native byte encoding. In these cases, \f(CW*is_utf8p\fR and
27363 \&\f(CW*lenp\fR are unchanged, and the return value is the original \f(CW\*(C`s\*(C'\fR.
27364 .Sp
27365 Otherwise, \f(CW*is_utf8p\fR is set to 0, and the return value is a pointer to a
27366 newly created string containing a downgraded copy of \f(CW\*(C`s\*(C'\fR, and whose length is
27367 returned in \f(CW*lenp\fR, updated. The new string is \f(CW\*(C`NUL\*(C'\fR\-terminated. The
27368 caller is responsible for arranging for the memory used by this string to get
27369 freed.
27370 .Sp
27371 Upon successful return, the number of variants in the string can be computed by
27372 having saved the value of \f(CW*lenp\fR before the call, and subtracting the
27373 after-call value of \f(CW*lenp\fR from it.
27374 .RS 4
27375 .Sp
27376 .Vb 1
27377 \& U8 * bytes_from_utf8(const U8 *s, STRLEN *lenp, bool *is_utf8p)
27378 .Ve
27379 .RE
27380 .RS 4
27381 .RE
27382 .ie n .IP """bytes_to_utf8""" 4
27383 .el .IP \f(CWbytes_to_utf8\fR 4
27384 .IX Xref "bytes_to_utf8"
27385 .IX Item "bytes_to_utf8"
27386 NOTE: \f(CW\*(C`bytes_to_utf8\*(C'\fR is \fBexperimental\fR and may change or be
27387 removed without notice.
27388 .Sp
27389 Converts a string \f(CW\*(C`s\*(C'\fR of length \f(CW*lenp\fR bytes from the native encoding into
27390 UTF\-8.
27391 Returns a pointer to the newly-created string, and sets \f(CW*lenp\fR to
27392 reflect the new length in bytes. The caller is responsible for arranging for
27393 the memory used by this string to get freed.
27394 .Sp
27395 Upon successful return, the number of variants in the string can be computed by
27396 having saved the value of \f(CW*lenp\fR before the call, and subtracting it from the
27397 after-call value of \f(CW*lenp\fR.
27398 .Sp
27399 A \f(CW\*(C`NUL\*(C'\fR character will be written after the end of the string.
27400 .Sp
27401 If you want to convert to UTF\-8 from encodings other than
27402 the native (Latin1 or EBCDIC),
27403 see "sv_recode_to_utf8"().
27404 .RS 4
27405 .Sp
27406 .Vb 1
27407 \& U8 * bytes_to_utf8(const U8 *s, STRLEN *lenp)
27408 .Ve
27409 .RE
27410 .RS 4
27411 .RE
27412 .ie n .IP """DO_UTF8""" 4
27413 .el .IP \f(CWDO_UTF8\fR 4
27414 .IX Xref "DO_UTF8"
27415 .IX Item "DO_UTF8"
27416 Returns a bool giving whether or not the PV in \f(CW\*(C`sv\*(C'\fR is to be treated as being
27417 encoded in UTF\-8.
27418 .Sp
27419 You should use this \fIafter\fR a call to \f(CWSvPV()\fR or one of its variants, in
27420 case any call to string overloading updates the internal UTF\-8 encoding flag.
27421 .RS 4
27422 .Sp
27423 .Vb 1
27424 \& bool DO_UTF8(SV* sv)
27425 .Ve
27426 .RE
27427 .RS 4
27428 .RE
27429 .ie n .IP """foldEQ_utf8""" 4
27430 .el .IP \f(CWfoldEQ_utf8\fR 4
27431 .IX Xref "foldEQ_utf8"
27432 .IX Item "foldEQ_utf8"
27433 Returns true if the leading portions of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR (either or
27434 both of which may be in UTF\-8) are the same case-insensitively; false
27435 otherwise. How far into the strings to compare is determined by other input
27436 parameters.
27437 .Sp
27438 If \f(CW\*(C`u1\*(C'\fR is true, the string \f(CW\*(C`s1\*(C'\fR is assumed to be in UTF\-8\-encoded Unicode;
27439 otherwise it is assumed to be in native 8\-bit encoding. Correspondingly for
27440 \&\f(CW\*(C`u2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR.
27441 .Sp
27442 If the byte length \f(CW\*(C`l1\*(C'\fR is non-zero, it says how far into \f(CW\*(C`s1\*(C'\fR to check for
27443 fold equality. In other words, \f(CW\*(C`s1\*(C'\fR+\f(CW\*(C`l1\*(C'\fR will be used as a goal to reach.
27444 The scan will not be considered to be a match unless the goal is reached, and
27445 scanning won't continue past that goal. Correspondingly for \f(CW\*(C`l2\*(C'\fR with respect
27446 to \f(CW\*(C`s2\*(C'\fR.
27447 .Sp
27448 If \f(CW\*(C`pe1\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR and the pointer it points to is not \f(CW\*(C`NULL\*(C'\fR, that
27449 pointer is considered an end pointer to the position 1 byte past the maximum
27450 point in \f(CW\*(C`s1\*(C'\fR beyond which scanning will not continue under any circumstances.
27451 (This routine assumes that UTF\-8 encoded input strings are not malformed;
27452 malformed input can cause it to read past \f(CW\*(C`pe1\*(C'\fR). This means that if both
27453 \&\f(CW\*(C`l1\*(C'\fR and \f(CW\*(C`pe1\*(C'\fR are specified, and \f(CW\*(C`pe1\*(C'\fR is less than \f(CW\*(C`s1\*(C'\fR+\f(CW\*(C`l1\*(C'\fR, the match
27454 will never be successful because it can never
27455 get as far as its goal (and in fact is asserted against). Correspondingly for
27456 \&\f(CW\*(C`pe2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR.
27457 .Sp
27458 At least one of \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR must have a goal (at least one of \f(CW\*(C`l1\*(C'\fR and
27459 \&\f(CW\*(C`l2\*(C'\fR must be non-zero), and if both do, both have to be
27460 reached for a successful match. Also, if the fold of a character is multiple
27461 characters, all of them must be matched (see tr21 reference below for
27462 \&'folding').
27463 .Sp
27464 Upon a successful match, if \f(CW\*(C`pe1\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR,
27465 it will be set to point to the beginning of the \fInext\fR character of \f(CW\*(C`s1\*(C'\fR
27466 beyond what was matched. Correspondingly for \f(CW\*(C`pe2\*(C'\fR and \f(CW\*(C`s2\*(C'\fR.
27467 .Sp
27468 For case-insensitiveness, the "casefolding" of Unicode is used
27469 instead of upper/lowercasing both the characters, see
27470 <https://www.unicode.org/reports/tr21/> (Case Mappings).
27471 .RS 4
27472 .Sp
27473 .Vb 2
27474 \& I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
27475 \& const char *s2, char **pe2, UV l2, bool u2)
27476 .Ve
27477 .RE
27478 .RS 4
27479 .RE
27480 .ie n .IP """is_ascii_string""" 4
27481 .el .IP \f(CWis_ascii_string\fR 4
27482 .IX Xref "is_ascii_string"
27483 .IX Item "is_ascii_string"
27484 This is a misleadingly-named synonym for "is_utf8_invariant_string".
27485 On ASCII-ish platforms, the name isn't misleading: the ASCII-range characters
27486 are exactly the UTF\-8 invariants. But EBCDIC machines have more invariants
27487 than just the ASCII characters, so \f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred.
27488 .RS 4
27489 .Sp
27490 .Vb 1
27491 \& bool is_ascii_string(const U8 * const s, STRLEN len)
27492 .Ve
27493 .RE
27494 .RS 4
27495 .RE
27496 .ie n .IP """isC9_STRICT_UTF8_CHAR""" 4
27497 .el .IP \f(CWisC9_STRICT_UTF8_CHAR\fR 4
27498 .IX Xref "isC9_STRICT_UTF8_CHAR"
27499 .IX Item "isC9_STRICT_UTF8_CHAR"
27500 Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
27501 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents some
27502 Unicode non-surrogate code point; otherwise it evaluates to 0. If non-zero,
27503 the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's
27504 representation. Any bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to
27505 form the first code point in \f(CW\*(C`s\*(C'\fR, are not examined.
27506 .Sp
27507 The largest acceptable code point is the Unicode maximum 0x10FFFF. This
27508 differs from \f(CW"isSTRICT_UTF8_CHAR"\fR only in that it accepts non-character
27509 code points. This corresponds to
27510 Unicode Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>.
27511 which said that non-character code points are merely discouraged rather than
27512 completely forbidden in open interchange. See
27513 "Noncharacter code points" in perlunicode.
27514 .Sp
27515 Use \f(CW"isUTF8_CHAR"\fR to check for Perl's extended UTF\-8; and
27516 \&\f(CW"isUTF8_CHAR_flags"\fR for a more customized definition.
27517 .Sp
27518 Use \f(CW"is_c9strict_utf8_string"\fR, \f(CW"is_c9strict_utf8_string_loc"\fR, and
27519 \&\f(CW"is_c9strict_utf8_string_loclen"\fR to check entire strings.
27520 .RS 4
27521 .Sp
27522 .Vb 2
27523 \& Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
27524 \& const U8 * const e)
27525 .Ve
27526 .RE
27527 .RS 4
27528 .RE
27529 .ie n .IP """is_c9strict_utf8_string""" 4
27530 .el .IP \f(CWis_c9strict_utf8_string\fR 4
27531 .IX Xref "is_c9strict_utf8_string"
27532 .IX Item "is_c9strict_utf8_string"
27533 Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
27534 UTF\-8\-encoded string that conforms to
27535 Unicode Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>;
27536 otherwise it returns FALSE. If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated using
27537 \&\f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded
27538 \&\f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte). Note that all
27539 characters being ASCII constitute 'a valid UTF\-8 string'.
27540 .Sp
27541 This function returns FALSE for strings containing any code points above the
27542 Unicode max of 0x10FFFF or surrogate code points, but accepts non-character
27543 code points per
27544 Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>.
27545 .Sp
27546 See also
27547 \&\f(CW"is_utf8_invariant_string"\fR,
27548 \&\f(CW"is_utf8_invariant_string_loc"\fR,
27549 \&\f(CW"is_utf8_string"\fR,
27550 \&\f(CW"is_utf8_string_flags"\fR,
27551 \&\f(CW"is_utf8_string_loc"\fR,
27552 \&\f(CW"is_utf8_string_loc_flags"\fR,
27553 \&\f(CW"is_utf8_string_loclen"\fR,
27554 \&\f(CW"is_utf8_string_loclen_flags"\fR,
27555 \&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
27556 \&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
27557 \&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
27558 \&\f(CW"is_strict_utf8_string"\fR,
27559 \&\f(CW"is_strict_utf8_string_loc"\fR,
27560 \&\f(CW"is_strict_utf8_string_loclen"\fR,
27561 \&\f(CW"is_c9strict_utf8_string_loc"\fR,
27562 and
27563 \&\f(CW"is_c9strict_utf8_string_loclen"\fR.
27564 .RS 4
27565 .Sp
27566 .Vb 1
27567 \& bool is_c9strict_utf8_string(const U8 *s, STRLEN len)
27568 .Ve
27569 .RE
27570 .RS 4
27571 .RE
27572 .ie n .IP """is_c9strict_utf8_string_loc""" 4
27573 .el .IP \f(CWis_c9strict_utf8_string_loc\fR 4
27574 .IX Xref "is_c9strict_utf8_string_loc"
27575 .IX Item "is_c9strict_utf8_string_loc"
27576 Like \f(CW"is_c9strict_utf8_string"\fR but stores the location of the failure (in
27577 the case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
27578 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
27579 .Sp
27580 See also \f(CW"is_c9strict_utf8_string_loclen"\fR.
27581 .RS 4
27582 .Sp
27583 .Vb 2
27584 \& bool is_c9strict_utf8_string_loc(const U8 *s, STRLEN len,
27585 \& const U8 **ep)
27586 .Ve
27587 .RE
27588 .RS 4
27589 .RE
27590 .ie n .IP """is_c9strict_utf8_string_loclen""" 4
27591 .el .IP \f(CWis_c9strict_utf8_string_loclen\fR 4
27592 .IX Xref "is_c9strict_utf8_string_loclen"
27593 .IX Item "is_c9strict_utf8_string_loclen"
27594 Like \f(CW"is_c9strict_utf8_string"\fR but stores the location of the failure (in
27595 the case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
27596 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8 encoded
27597 characters in the \f(CW\*(C`el\*(C'\fR pointer.
27598 .Sp
27599 See also \f(CW"is_c9strict_utf8_string_loc"\fR.
27600 .RS 4
27601 .Sp
27602 .Vb 2
27603 \& bool is_c9strict_utf8_string_loclen(const U8 *s, STRLEN len,
27604 \& const U8 **ep, STRLEN *el)
27605 .Ve
27606 .RE
27607 .RS 4
27608 .RE
27609 .ie n .IP """is_invariant_string""" 4
27610 .el .IP \f(CWis_invariant_string\fR 4
27611 .IX Xref "is_invariant_string"
27612 .IX Item "is_invariant_string"
27613 This is a somewhat misleadingly-named synonym for "is_utf8_invariant_string".
27614 \&\f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred, as it indicates under what conditions
27615 the string is invariant.
27616 .RS 4
27617 .Sp
27618 .Vb 1
27619 \& bool is_invariant_string(const U8 * const s, STRLEN len)
27620 .Ve
27621 .RE
27622 .RS 4
27623 .RE
27624 .ie n .IP """isSTRICT_UTF8_CHAR""" 4
27625 .el .IP \f(CWisSTRICT_UTF8_CHAR\fR 4
27626 .IX Xref "isSTRICT_UTF8_CHAR"
27627 .IX Item "isSTRICT_UTF8_CHAR"
27628 Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
27629 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents some
27630 Unicode code point completely acceptable for open interchange between all
27631 applications; otherwise it evaluates to 0. If non-zero, the value gives how
27632 many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation. Any
27633 bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to form the first code
27634 point in \f(CW\*(C`s\*(C'\fR, are not examined.
27635 .Sp
27636 The largest acceptable code point is the Unicode maximum 0x10FFFF, and must not
27637 be a surrogate nor a non-character code point. Thus this excludes any code
27638 point from Perl's extended UTF\-8.
27639 .Sp
27640 This is used to efficiently decide if the next few bytes in \f(CW\*(C`s\*(C'\fR is
27641 legal Unicode-acceptable UTF\-8 for a single character.
27642 .Sp
27643 Use \f(CW"isC9_STRICT_UTF8_CHAR"\fR to use the Unicode Corrigendum
27644 #9 <http://www.unicode.org/versions/corrigendum9.html> definition of allowable
27645 code points; \f(CW"isUTF8_CHAR"\fR to check for Perl's extended UTF\-8;
27646 and \f(CW"isUTF8_CHAR_flags"\fR for a more customized definition.
27647 .Sp
27648 Use \f(CW"is_strict_utf8_string"\fR, \f(CW"is_strict_utf8_string_loc"\fR, and
27649 \&\f(CW"is_strict_utf8_string_loclen"\fR to check entire strings.
27650 .RS 4
27651 .Sp
27652 .Vb 2
27653 \& Size_t isSTRICT_UTF8_CHAR(const U8 * const s0,
27654 \& const U8 * const e)
27655 .Ve
27656 .RE
27657 .RS 4
27658 .RE
27659 .ie n .IP """is_strict_utf8_string""" 4
27660 .el .IP \f(CWis_strict_utf8_string\fR 4
27661 .IX Xref "is_strict_utf8_string"
27662 .IX Item "is_strict_utf8_string"
27663 Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
27664 UTF\-8\-encoded string that is fully interchangeable by any application using
27665 Unicode rules; otherwise it returns FALSE. If \f(CW\*(C`len\*(C'\fR is 0, it will be
27666 calculated using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR
27667 can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR
27668 byte). Note that all characters being ASCII constitute 'a valid UTF\-8 string'.
27669 .Sp
27670 This function returns FALSE for strings containing any
27671 code points above the Unicode max of 0x10FFFF, surrogate code points, or
27672 non-character code points.
27673 .Sp
27674 See also
27675 \&\f(CW"is_utf8_invariant_string"\fR,
27676 \&\f(CW"is_utf8_invariant_string_loc"\fR,
27677 \&\f(CW"is_utf8_string"\fR,
27678 \&\f(CW"is_utf8_string_flags"\fR,
27679 \&\f(CW"is_utf8_string_loc"\fR,
27680 \&\f(CW"is_utf8_string_loc_flags"\fR,
27681 \&\f(CW"is_utf8_string_loclen"\fR,
27682 \&\f(CW"is_utf8_string_loclen_flags"\fR,
27683 \&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
27684 \&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
27685 \&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
27686 \&\f(CW"is_strict_utf8_string_loc"\fR,
27687 \&\f(CW"is_strict_utf8_string_loclen"\fR,
27688 \&\f(CW"is_c9strict_utf8_string"\fR,
27689 \&\f(CW"is_c9strict_utf8_string_loc"\fR,
27690 and
27691 \&\f(CW"is_c9strict_utf8_string_loclen"\fR.
27692 .RS 4
27693 .Sp
27694 .Vb 1
27695 \& bool is_strict_utf8_string(const U8 *s, STRLEN len)
27696 .Ve
27697 .RE
27698 .RS 4
27699 .RE
27700 .ie n .IP """is_strict_utf8_string_loc""" 4
27701 .el .IP \f(CWis_strict_utf8_string_loc\fR 4
27702 .IX Xref "is_strict_utf8_string_loc"
27703 .IX Item "is_strict_utf8_string_loc"
27704 Like \f(CW"is_strict_utf8_string"\fR but stores the location of the failure (in the
27705 case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
27706 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
27707 .Sp
27708 See also \f(CW"is_strict_utf8_string_loclen"\fR.
27709 .RS 4
27710 .Sp
27711 .Vb 2
27712 \& bool is_strict_utf8_string_loc(const U8 *s, STRLEN len,
27713 \& const U8 **ep)
27714 .Ve
27715 .RE
27716 .RS 4
27717 .RE
27718 .ie n .IP """is_strict_utf8_string_loclen""" 4
27719 .el .IP \f(CWis_strict_utf8_string_loclen\fR 4
27720 .IX Xref "is_strict_utf8_string_loclen"
27721 .IX Item "is_strict_utf8_string_loclen"
27722 Like \f(CW"is_strict_utf8_string"\fR but stores the location of the failure (in the
27723 case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
27724 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8
27725 encoded characters in the \f(CW\*(C`el\*(C'\fR pointer.
27726 .Sp
27727 See also \f(CW"is_strict_utf8_string_loc"\fR.
27728 .RS 4
27729 .Sp
27730 .Vb 2
27731 \& bool is_strict_utf8_string_loclen(const U8 *s, STRLEN len,
27732 \& const U8 **ep, STRLEN *el)
27733 .Ve
27734 .RE
27735 .RS 4
27736 .RE
27737 .ie n .IP """isUTF8_CHAR""" 4
27738 .el .IP \f(CWisUTF8_CHAR\fR 4
27739 .IX Xref "isUTF8_CHAR"
27740 .IX Item "isUTF8_CHAR"
27741 Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
27742 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8, as extended by Perl,
27743 that represents some code point; otherwise it evaluates to 0. If non-zero, the
27744 value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's
27745 representation. Any bytes remaining before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to
27746 form the first code point in \f(CW\*(C`s\*(C'\fR, are not examined.
27747 .Sp
27748 The code point can be any that will fit in an IV on this machine, using Perl's
27749 extension to official UTF\-8 to represent those higher than the Unicode maximum
27750 of 0x10FFFF. That means that this macro is used to efficiently decide if the
27751 next few bytes in \f(CW\*(C`s\*(C'\fR is legal UTF\-8 for a single character.
27752 .Sp
27753 Use \f(CW"isSTRICT_UTF8_CHAR"\fR to restrict the acceptable code points to those
27754 defined by Unicode to be fully interchangeable across applications;
27755 \&\f(CW"isC9_STRICT_UTF8_CHAR"\fR to use the Unicode Corrigendum
27756 #9 <http://www.unicode.org/versions/corrigendum9.html> definition of allowable
27757 code points; and \f(CW"isUTF8_CHAR_flags"\fR for a more customized definition.
27758 .Sp
27759 Use \f(CW"is_utf8_string"\fR, \f(CW"is_utf8_string_loc"\fR, and
27760 \&\f(CW"is_utf8_string_loclen"\fR to check entire strings.
27761 .Sp
27762 Note also that a UTF\-8 "invariant" character (i.e. ASCII on non-EBCDIC
27763 machines) is a valid UTF\-8 character.
27764 .RS 4
27765 .Sp
27766 .Vb 1
27767 \& Size_t isUTF8_CHAR(const U8 * const s0, const U8 * const e)
27768 .Ve
27769 .RE
27770 .RS 4
27771 .RE
27772 .ie n .IP """is_utf8_char_buf""" 4
27773 .el .IP \f(CWis_utf8_char_buf\fR 4
27774 .IX Xref "is_utf8_char_buf"
27775 .IX Item "is_utf8_char_buf"
27776 This is identical to the macro "isUTF8_CHAR" in perlapi.
27777 .RS 4
27778 .Sp
27779 .Vb 1
27780 \& STRLEN is_utf8_char_buf(const U8 *buf, const U8 *buf_end)
27781 .Ve
27782 .RE
27783 .RS 4
27784 .RE
27785 .ie n .IP """isUTF8_CHAR_flags""" 4
27786 .el .IP \f(CWisUTF8_CHAR_flags\fR 4
27787 .IX Xref "isUTF8_CHAR_flags"
27788 .IX Item "isUTF8_CHAR_flags"
27789 Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
27790 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8, as extended by Perl,
27791 that represents some code point, subject to the restrictions given by \f(CW\*(C`flags\*(C'\fR;
27792 otherwise it evaluates to 0. If non-zero, the value gives how many bytes
27793 starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation. Any bytes remaining
27794 before \f(CW\*(C`e\*(C'\fR, but beyond the ones needed to form the first code point in \f(CW\*(C`s\*(C'\fR,
27795 are not examined.
27796 .Sp
27797 If \f(CW\*(C`flags\*(C'\fR is 0, this gives the same results as \f(CW"isUTF8_CHAR"\fR;
27798 if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, this gives the same results
27799 as \f(CW"isSTRICT_UTF8_CHAR"\fR;
27800 and if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, this gives
27801 the same results as \f(CW"isC9_STRICT_UTF8_CHAR"\fR.
27802 Otherwise \f(CW\*(C`flags\*(C'\fR may be any combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags
27803 understood by \f(CW"utf8n_to_uvchr"\fR, with the same meanings.
27804 .Sp
27805 The three alternative macros are for the most commonly needed validations; they
27806 are likely to run somewhat faster than this more general one, as they can be
27807 inlined into your code.
27808 .Sp
27809 Use "is_utf8_string_flags", "is_utf8_string_loc_flags", and
27810 "is_utf8_string_loclen_flags" to check entire strings.
27811 .RS 4
27812 .Sp
27813 .Vb 2
27814 \& Size_t isUTF8_CHAR_flags(const U8 * const s0, const U8 * const e,
27815 \& const U32 flags)
27816 .Ve
27817 .RE
27818 .RS 4
27819 .RE
27820 .ie n .IP """is_utf8_fixed_width_buf_flags""" 4
27821 .el .IP \f(CWis_utf8_fixed_width_buf_flags\fR 4
27822 .IX Xref "is_utf8_fixed_width_buf_flags"
27823 .IX Item "is_utf8_fixed_width_buf_flags"
27824 Returns TRUE if the fixed-width buffer starting at \f(CW\*(C`s\*(C'\fR with length \f(CW\*(C`len\*(C'\fR
27825 is entirely valid UTF\-8, subject to the restrictions given by \f(CW\*(C`flags\*(C'\fR;
27826 otherwise it returns FALSE.
27827 .Sp
27828 If \f(CW\*(C`flags\*(C'\fR is 0, any well-formed UTF\-8, as extended by Perl, is accepted
27829 without restriction. If the final few bytes of the buffer do not form a
27830 complete code point, this will return TRUE anyway, provided that
27831 \&\f(CW"is_utf8_valid_partial_char_flags"\fR returns TRUE for them.
27832 .Sp
27833 If \f(CW\*(C`flags\*(C'\fR in non-zero, it can be any combination of the
27834 \&\f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags accepted by \f(CW"utf8n_to_uvchr"\fR, and with the
27835 same meanings.
27836 .Sp
27837 This function differs from \f(CW"is_utf8_string_flags"\fR only in that the latter
27838 returns FALSE if the final few bytes of the string don't form a complete code
27839 point.
27840 .RS 4
27841 .Sp
27842 .Vb 2
27843 \& bool is_utf8_fixed_width_buf_flags(const U8 * const s,
27844 \& STRLEN len, const U32 flags)
27845 .Ve
27846 .RE
27847 .RS 4
27848 .RE
27849 .ie n .IP """is_utf8_fixed_width_buf_loc_flags""" 4
27850 .el .IP \f(CWis_utf8_fixed_width_buf_loc_flags\fR 4
27851 .IX Xref "is_utf8_fixed_width_buf_loc_flags"
27852 .IX Item "is_utf8_fixed_width_buf_loc_flags"
27853 Like \f(CW"is_utf8_fixed_width_buf_flags"\fR but stores the location of the
27854 failure in the \f(CW\*(C`ep\*(C'\fR pointer. If the function returns TRUE, \f(CW*ep\fR will point
27855 to the beginning of any partial character at the end of the buffer; if there is
27856 no partial character \f(CW*ep\fR will contain \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR.
27857 .Sp
27858 See also \f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR.
27859 .RS 4
27860 .Sp
27861 .Vb 3
27862 \& bool is_utf8_fixed_width_buf_loc_flags(const U8 * const s,
27863 \& STRLEN len, const U8 **ep,
27864 \& const U32 flags)
27865 .Ve
27866 .RE
27867 .RS 4
27868 .RE
27869 .ie n .IP """is_utf8_fixed_width_buf_loclen_flags""" 4
27870 .el .IP \f(CWis_utf8_fixed_width_buf_loclen_flags\fR 4
27871 .IX Xref "is_utf8_fixed_width_buf_loclen_flags"
27872 .IX Item "is_utf8_fixed_width_buf_loclen_flags"
27873 Like \f(CW"is_utf8_fixed_width_buf_loc_flags"\fR but stores the number of
27874 complete, valid characters found in the \f(CW\*(C`el\*(C'\fR pointer.
27875 .RS 4
27876 .Sp
27877 .Vb 5
27878 \& bool is_utf8_fixed_width_buf_loclen_flags(const U8 * const s,
27879 \& STRLEN len,
27880 \& const U8 **ep,
27881 \& STRLEN *el,
27882 \& const U32 flags)
27883 .Ve
27884 .RE
27885 .RS 4
27886 .RE
27887 .ie n .IP """is_utf8_invariant_string""" 4
27888 .el .IP \f(CWis_utf8_invariant_string\fR 4
27889 .IX Xref "is_utf8_invariant_string"
27890 .IX Item "is_utf8_invariant_string"
27891 Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of the string \f(CW\*(C`s\*(C'\fR are the same
27892 regardless of the UTF\-8 encoding of the string (or UTF-EBCDIC encoding on
27893 EBCDIC machines); otherwise it returns FALSE. That is, it returns TRUE if they
27894 are UTF\-8 invariant. On ASCII-ish machines, all the ASCII characters and only
27895 the ASCII characters fit this definition. On EBCDIC machines, the ASCII-range
27896 characters are invariant, but so also are the C1 controls.
27897 .Sp
27898 If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated using \f(CWstrlen(s)\fR, (which means if you
27899 use this option, that \f(CW\*(C`s\*(C'\fR can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to
27900 have a terminating \f(CW\*(C`NUL\*(C'\fR byte).
27901 .Sp
27902 See also
27903 \&\f(CW"is_utf8_string"\fR,
27904 \&\f(CW"is_utf8_string_flags"\fR,
27905 \&\f(CW"is_utf8_string_loc"\fR,
27906 \&\f(CW"is_utf8_string_loc_flags"\fR,
27907 \&\f(CW"is_utf8_string_loclen"\fR,
27908 \&\f(CW"is_utf8_string_loclen_flags"\fR,
27909 \&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
27910 \&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
27911 \&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
27912 \&\f(CW"is_strict_utf8_string"\fR,
27913 \&\f(CW"is_strict_utf8_string_loc"\fR,
27914 \&\f(CW"is_strict_utf8_string_loclen"\fR,
27915 \&\f(CW"is_c9strict_utf8_string"\fR,
27916 \&\f(CW"is_c9strict_utf8_string_loc"\fR,
27917 and
27918 \&\f(CW"is_c9strict_utf8_string_loclen"\fR.
27919 .RS 4
27920 .Sp
27921 .Vb 1
27922 \& bool is_utf8_invariant_string(const U8 * const s, STRLEN len)
27923 .Ve
27924 .RE
27925 .RS 4
27926 .RE
27927 .ie n .IP """is_utf8_invariant_string_loc""" 4
27928 .el .IP \f(CWis_utf8_invariant_string_loc\fR 4
27929 .IX Xref "is_utf8_invariant_string_loc"
27930 .IX Item "is_utf8_invariant_string_loc"
27931 Like \f(CW"is_utf8_invariant_string"\fR but upon failure, stores the location of
27932 the first UTF\-8 variant character in the \f(CW\*(C`ep\*(C'\fR pointer; if all characters are
27933 UTF\-8 invariant, this function does not change the contents of \f(CW*ep\fR.
27934 .RS 4
27935 .Sp
27936 .Vb 2
27937 \& bool is_utf8_invariant_string_loc(const U8 * const s, STRLEN len,
27938 \& const U8 **ep)
27939 .Ve
27940 .RE
27941 .RS 4
27942 .RE
27943 .ie n .IP """is_utf8_string""" 4
27944 .el .IP \f(CWis_utf8_string\fR 4
27945 .IX Xref "is_utf8_string"
27946 .IX Item "is_utf8_string"
27947 Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
27948 Perl\-extended\-UTF\-8 string; returns FALSE otherwise. If \f(CW\*(C`len\*(C'\fR is 0, it will
27949 be calculated using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR
27950 can't have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR
27951 byte). Note that all characters being ASCII constitute 'a valid UTF\-8 string'.
27952 .Sp
27953 This function considers Perl's extended UTF\-8 to be valid. That means that
27954 code points above Unicode, surrogates, and non-character code points are
27955 considered valid by this function. Use \f(CW"is_strict_utf8_string"\fR,
27956 \&\f(CW"is_c9strict_utf8_string"\fR, or \f(CW"is_utf8_string_flags"\fR to restrict what
27957 code points are considered valid.
27958 .Sp
27959 See also
27960 \&\f(CW"is_utf8_invariant_string"\fR,
27961 \&\f(CW"is_utf8_invariant_string_loc"\fR,
27962 \&\f(CW"is_utf8_string_loc"\fR,
27963 \&\f(CW"is_utf8_string_loclen"\fR,
27964 \&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
27965 \&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
27966 \&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
27967 .RS 4
27968 .Sp
27969 .Vb 1
27970 \& bool is_utf8_string(const U8 *s, STRLEN len)
27971 .Ve
27972 .RE
27973 .RS 4
27974 .RE
27975 .ie n .IP """is_utf8_string_flags""" 4
27976 .el .IP \f(CWis_utf8_string_flags\fR 4
27977 .IX Xref "is_utf8_string_flags"
27978 .IX Item "is_utf8_string_flags"
27979 Returns TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
27980 UTF\-8 string, subject to the restrictions imposed by \f(CW\*(C`flags\*(C'\fR;
27981 returns FALSE otherwise. If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated
27982 using \f(CWstrlen(s)\fR (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can't have
27983 embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte). Note
27984 that all characters being ASCII constitute 'a valid UTF\-8 string'.
27985 .Sp
27986 If \f(CW\*(C`flags\*(C'\fR is 0, this gives the same results as \f(CW"is_utf8_string"\fR; if
27987 \&\f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, this gives the same results
27988 as \f(CW"is_strict_utf8_string"\fR; and if \f(CW\*(C`flags\*(C'\fR is
27989 \&\f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, this gives the same results as
27990 \&\f(CW"is_c9strict_utf8_string"\fR. Otherwise \f(CW\*(C`flags\*(C'\fR may be any
27991 combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags understood by
27992 \&\f(CW"utf8n_to_uvchr"\fR, with the same meanings.
27993 .Sp
27994 See also
27995 \&\f(CW"is_utf8_invariant_string"\fR,
27996 \&\f(CW"is_utf8_invariant_string_loc"\fR,
27997 \&\f(CW"is_utf8_string"\fR,
27998 \&\f(CW"is_utf8_string_loc"\fR,
27999 \&\f(CW"is_utf8_string_loc_flags"\fR,
28000 \&\f(CW"is_utf8_string_loclen"\fR,
28001 \&\f(CW"is_utf8_string_loclen_flags"\fR,
28002 \&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
28003 \&\f(CW"is_utf8_fixed_width_buf_loc_flags"\fR,
28004 \&\f(CW"is_utf8_fixed_width_buf_loclen_flags"\fR,
28005 \&\f(CW"is_strict_utf8_string"\fR,
28006 \&\f(CW"is_strict_utf8_string_loc"\fR,
28007 \&\f(CW"is_strict_utf8_string_loclen"\fR,
28008 \&\f(CW"is_c9strict_utf8_string"\fR,
28009 \&\f(CW"is_c9strict_utf8_string_loc"\fR,
28010 and
28011 \&\f(CW"is_c9strict_utf8_string_loclen"\fR.
28012 .RS 4
28013 .Sp
28014 .Vb 2
28015 \& bool is_utf8_string_flags(const U8 *s, STRLEN len,
28016 \& const U32 flags)
28017 .Ve
28018 .RE
28019 .RS 4
28020 .RE
28021 .ie n .IP """is_utf8_string_loc""" 4
28022 .el .IP \f(CWis_utf8_string_loc\fR 4
28023 .IX Xref "is_utf8_string_loc"
28024 .IX Item "is_utf8_string_loc"
28025 Like \f(CW"is_utf8_string"\fR but stores the location of the failure (in the
28026 case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
28027 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
28028 .Sp
28029 See also \f(CW"is_utf8_string_loclen"\fR.
28030 .RS 4
28031 .Sp
28032 .Vb 2
28033 \& bool is_utf8_string_loc(const U8 *s, const STRLEN len,
28034 \& const U8 **ep)
28035 .Ve
28036 .RE
28037 .RS 4
28038 .RE
28039 .ie n .IP """is_utf8_string_loc_flags""" 4
28040 .el .IP \f(CWis_utf8_string_loc_flags\fR 4
28041 .IX Xref "is_utf8_string_loc_flags"
28042 .IX Item "is_utf8_string_loc_flags"
28043 Like \f(CW"is_utf8_string_flags"\fR but stores the location of the failure (in the
28044 case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
28045 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer.
28046 .Sp
28047 See also \f(CW"is_utf8_string_loclen_flags"\fR.
28048 .RS 4
28049 .Sp
28050 .Vb 2
28051 \& bool is_utf8_string_loc_flags(const U8 *s, STRLEN len,
28052 \& const U8 **ep, const U32 flags)
28053 .Ve
28054 .RE
28055 .RS 4
28056 .RE
28057 .ie n .IP """is_utf8_string_loclen""" 4
28058 .el .IP \f(CWis_utf8_string_loclen\fR 4
28059 .IX Xref "is_utf8_string_loclen"
28060 .IX Item "is_utf8_string_loclen"
28061 Like \f(CW"is_utf8_string"\fR but stores the location of the failure (in the
28062 case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
28063 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8
28064 encoded characters in the \f(CW\*(C`el\*(C'\fR pointer.
28065 .Sp
28066 See also \f(CW"is_utf8_string_loc"\fR.
28067 .RS 4
28068 .Sp
28069 .Vb 2
28070 \& bool is_utf8_string_loclen(const U8 *s, STRLEN len,
28071 \& const U8 **ep, STRLEN *el)
28072 .Ve
28073 .RE
28074 .RS 4
28075 .RE
28076 .ie n .IP """is_utf8_string_loclen_flags""" 4
28077 .el .IP \f(CWis_utf8_string_loclen_flags\fR 4
28078 .IX Xref "is_utf8_string_loclen_flags"
28079 .IX Item "is_utf8_string_loclen_flags"
28080 Like \f(CW"is_utf8_string_flags"\fR but stores the location of the failure (in the
28081 case of "utf8ness failure") or the location \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR (in the case of
28082 "utf8ness success") in the \f(CW\*(C`ep\*(C'\fR pointer, and the number of UTF\-8
28083 encoded characters in the \f(CW\*(C`el\*(C'\fR pointer.
28084 .Sp
28085 See also \f(CW"is_utf8_string_loc_flags"\fR.
28086 .RS 4
28087 .Sp
28088 .Vb 3
28089 \& bool is_utf8_string_loclen_flags(const U8 *s, STRLEN len,
28090 \& const U8 **ep, STRLEN *el,
28091 \& const U32 flags)
28092 .Ve
28093 .RE
28094 .RS 4
28095 .RE
28096 .ie n .IP """is_utf8_valid_partial_char""" 4
28097 .el .IP \f(CWis_utf8_valid_partial_char\fR 4
28098 .IX Xref "is_utf8_valid_partial_char"
28099 .IX Item "is_utf8_valid_partial_char"
28100 Returns 0 if the sequence of bytes starting at \f(CW\*(C`s\*(C'\fR and looking no further than
28101 \&\f(CW\*(C`e\ \-\ 1\*(C'\fR is the UTF\-8 encoding, as extended by Perl, for one or more code
28102 points. Otherwise, it returns 1 if there exists at least one non-empty
28103 sequence of bytes that when appended to sequence \f(CW\*(C`s\*(C'\fR, starting at position
28104 \&\f(CW\*(C`e\*(C'\fR causes the entire sequence to be the well-formed UTF\-8 of some code point;
28105 otherwise returns 0.
28106 .Sp
28107 In other words this returns TRUE if \f(CW\*(C`s\*(C'\fR points to a partial UTF\-8\-encoded code
28108 point.
28109 .Sp
28110 This is useful when a fixed-length buffer is being tested for being well-formed
28111 UTF\-8, but the final few bytes in it don't comprise a full character; that is,
28112 it is split somewhere in the middle of the final code point's UTF\-8
28113 representation. (Presumably when the buffer is refreshed with the next chunk
28114 of data, the new first bytes will complete the partial code point.) This
28115 function is used to verify that the final bytes in the current buffer are in
28116 fact the legal beginning of some code point, so that if they aren't, the
28117 failure can be signalled without having to wait for the next read.
28118 .RS 4
28119 .Sp
28120 .Vb 2
28121 \& bool is_utf8_valid_partial_char(const U8 * const s0,
28122 \& const U8 * const e)
28123 .Ve
28124 .RE
28125 .RS 4
28126 .RE
28127 .ie n .IP """is_utf8_valid_partial_char_flags""" 4
28128 .el .IP \f(CWis_utf8_valid_partial_char_flags\fR 4
28129 .IX Xref "is_utf8_valid_partial_char_flags"
28130 .IX Item "is_utf8_valid_partial_char_flags"
28131 Like \f(CW"is_utf8_valid_partial_char"\fR, it returns a boolean giving whether
28132 or not the input is a valid UTF\-8 encoded partial character, but it takes an
28133 extra parameter, \f(CW\*(C`flags\*(C'\fR, which can further restrict which code points are
28134 considered valid.
28135 .Sp
28136 If \f(CW\*(C`flags\*(C'\fR is 0, this behaves identically to
28137 \&\f(CW"is_utf8_valid_partial_char"\fR. Otherwise \f(CW\*(C`flags\*(C'\fR can be any combination
28138 of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags accepted by \f(CW"utf8n_to_uvchr"\fR. If
28139 there is any sequence of bytes that can complete the input partial character in
28140 such a way that a non-prohibited character is formed, the function returns
28141 TRUE; otherwise FALSE. Non character code points cannot be determined based on
28142 partial character input. But many of the other possible excluded types can be
28143 determined from just the first one or two bytes.
28144 .RS 4
28145 .Sp
28146 .Vb 3
28147 \& bool is_utf8_valid_partial_char_flags(const U8 * const s0,
28148 \& const U8 * const e,
28149 \& const U32 flags)
28150 .Ve
28151 .RE
28152 .RS 4
28153 .RE
28154 .ie n .IP """LATIN1_TO_NATIVE""" 4
28155 .el .IP \f(CWLATIN1_TO_NATIVE\fR 4
28156 .IX Xref "LATIN1_TO_NATIVE"
28157 .IX Item "LATIN1_TO_NATIVE"
28158 Returns the native equivalent of the input Latin\-1 code point (including ASCII
28159 and control characters) given by \f(CW\*(C`ch\*(C'\fR. Thus, \f(CWLATIN1_TO_NATIVE(66)\fR on
28160 EBCDIC platforms returns 194. These each represent the character \f(CW"B"\fR on
28161 their respective platforms. On ASCII platforms no conversion is needed, so
28162 this macro expands to just its input, adding no time nor space requirements to
28163 the implementation.
28164 .Sp
28165 For conversion of code points potentially larger than will fit in a character,
28166 use "UNI_TO_NATIVE".
28167 .RS 4
28168 .Sp
28169 .Vb 1
28170 \& U8 LATIN1_TO_NATIVE(U8 ch)
28171 .Ve
28172 .RE
28173 .RS 4
28174 .RE
28175 .ie n .IP """NATIVE_TO_LATIN1""" 4
28176 .el .IP \f(CWNATIVE_TO_LATIN1\fR 4
28177 .IX Xref "NATIVE_TO_LATIN1"
28178 .IX Item "NATIVE_TO_LATIN1"
28179 Returns the Latin\-1 (including ASCII and control characters) equivalent of the
28180 input native code point given by \f(CW\*(C`ch\*(C'\fR. Thus, \f(CWNATIVE_TO_LATIN1(193)\fR on
28181 EBCDIC platforms returns 65. These each represent the character \f(CW"A"\fR on
28182 their respective platforms. On ASCII platforms no conversion is needed, so
28183 this macro expands to just its input, adding no time nor space requirements to
28184 the implementation.
28185 .Sp
28186 For conversion of code points potentially larger than will fit in a character,
28187 use "NATIVE_TO_UNI".
28188 .RS 4
28189 .Sp
28190 .Vb 1
28191 \& U8 NATIVE_TO_LATIN1(U8 ch)
28192 .Ve
28193 .RE
28194 .RS 4
28195 .RE
28196 .ie n .IP """NATIVE_TO_UNI""" 4
28197 .el .IP \f(CWNATIVE_TO_UNI\fR 4
28198 .IX Xref "NATIVE_TO_UNI"
28199 .IX Item "NATIVE_TO_UNI"
28200 Returns the Unicode equivalent of the input native code point given by \f(CW\*(C`ch\*(C'\fR.
28201 Thus, \f(CWNATIVE_TO_UNI(195)\fR on EBCDIC platforms returns 67. These each
28202 represent the character \f(CW"C"\fR on their respective platforms. On ASCII
28203 platforms no conversion is needed, so this macro expands to just its input,
28204 adding no time nor space requirements to the implementation.
28205 .RS 4
28206 .Sp
28207 .Vb 1
28208 \& UV NATIVE_TO_UNI(UV ch)
28209 .Ve
28210 .RE
28211 .RS 4
28212 .RE
28213 .ie n .IP """pv_uni_display""" 4
28214 .el .IP \f(CWpv_uni_display\fR 4
28215 .IX Xref "pv_uni_display"
28216 .IX Item "pv_uni_display"
28217 Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the UTF\-8 encoded string
28218 \&\f(CW\*(C`spv\*(C'\fR, length \f(CW\*(C`len\*(C'\fR, the displayable version being at most \f(CW\*(C`pvlim\*(C'\fR bytes
28219 long (if longer, the rest is truncated and \f(CW"..."\fR will be appended).
28220 .Sp
28221 The \f(CW\*(C`flags\*(C'\fR argument can have \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR set to display
28222 \&\f(CWisPRINT()\fRable characters as themselves, \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR
28223 to display the \f(CW\*(C`\e\e[nrfta\e\e]\*(C'\fR as the backslashed versions (like \f(CW"\en"\fR)
28224 (\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR is preferred over \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR for \f(CW"\e\e"\fR).
28225 \&\f(CW\*(C`UNI_DISPLAY_QQ\*(C'\fR (and its alias \f(CW\*(C`UNI_DISPLAY_REGEX\*(C'\fR) have both
28226 \&\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR and \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR turned on.
28227 .Sp
28228 Additionally, there is now \f(CW\*(C`UNI_DISPLAY_BACKSPACE\*(C'\fR which allows \f(CW\*(C`\eb\*(C'\fR for a
28229 backspace, but only when \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR also is set.
28230 .Sp
28231 The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned.
28232 .Sp
28233 See also "sv_uni_display".
28234 .RS 4
28235 .Sp
28236 .Vb 2
28237 \& char * pv_uni_display(SV *dsv, const U8 *spv, STRLEN len,
28238 \& STRLEN pvlim, UV flags)
28239 .Ve
28240 .RE
28241 .RS 4
28242 .RE
28243 .ie n .IP """REPLACEMENT_CHARACTER_UTF8""" 4
28244 .el .IP \f(CWREPLACEMENT_CHARACTER_UTF8\fR 4
28245 .IX Xref "REPLACEMENT_CHARACTER_UTF8"
28246 .IX Item "REPLACEMENT_CHARACTER_UTF8"
28247 This is a macro that evaluates to a string constant of the UTF\-8 bytes that
28248 define the Unicode REPLACEMENT CHARACTER (U+FFFD) for the platform that perl
28249 is compiled on. This allows code to use a mnemonic for this character that
28250 works on both ASCII and EBCDIC platforms.
28251 \&\f(CW\*(C`sizeof(REPLACEMENT_CHARACTER_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in
28252 bytes.
28253 .ie n .IP """sv_cat_decode""" 4
28254 .el .IP \f(CWsv_cat_decode\fR 4
28255 .IX Xref "sv_cat_decode"
28256 .IX Item "sv_cat_decode"
28257 \&\f(CW\*(C`encoding\*(C'\fR is assumed to be an \f(CW\*(C`Encode\*(C'\fR object, the PV of \f(CW\*(C`ssv\*(C'\fR is
28258 assumed to be octets in that encoding and decoding the input starts
28259 from the position which \f(CW\*(C`(PV\ +\ *offset)\*(C'\fR pointed to. \f(CW\*(C`dsv\*(C'\fR will be
28260 concatenated with the decoded UTF\-8 string from \f(CW\*(C`ssv\*(C'\fR. Decoding will terminate
28261 when the string \f(CW\*(C`tstr\*(C'\fR appears in decoding output or the input ends on
28262 the PV of \f(CW\*(C`ssv\*(C'\fR. The value which \f(CW\*(C`offset\*(C'\fR points will be modified
28263 to the last input position on \f(CW\*(C`ssv\*(C'\fR.
28264 .Sp
28265 Returns TRUE if the terminator was found, else returns FALSE.
28266 .RS 4
28267 .Sp
28268 .Vb 2
28269 \& bool sv_cat_decode(SV *dsv, SV *encoding, SV *ssv, int *offset,
28270 \& char *tstr, int tlen)
28271 .Ve
28272 .RE
28273 .RS 4
28274 .RE
28275 .ie n .IP """sv_recode_to_utf8""" 4
28276 .el .IP \f(CWsv_recode_to_utf8\fR 4
28277 .IX Xref "sv_recode_to_utf8"
28278 .IX Item "sv_recode_to_utf8"
28279 \&\f(CW\*(C`encoding\*(C'\fR is assumed to be an \f(CW\*(C`Encode\*(C'\fR object, on entry the PV
28280 of \f(CW\*(C`sv\*(C'\fR is assumed to be octets in that encoding, and \f(CW\*(C`sv\*(C'\fR
28281 will be converted into Unicode (and UTF\-8).
28282 .Sp
28283 If \f(CW\*(C`sv\*(C'\fR already is UTF\-8 (or if it is not \f(CW\*(C`POK\*(C'\fR), or if \f(CW\*(C`encoding\*(C'\fR
28284 is not a reference, nothing is done to \f(CW\*(C`sv\*(C'\fR. If \f(CW\*(C`encoding\*(C'\fR is not
28285 an \f(CW\*(C`Encode::XS\*(C'\fR Encoding object, bad things will happen.
28286 (See encoding and Encode.)
28287 .Sp
28288 The PV of \f(CW\*(C`sv\*(C'\fR is returned.
28289 .RS 4
28290 .Sp
28291 .Vb 1
28292 \& char * sv_recode_to_utf8(SV *sv, SV *encoding)
28293 .Ve
28294 .RE
28295 .RS 4
28296 .RE
28297 .ie n .IP """sv_uni_display""" 4
28298 .el .IP \f(CWsv_uni_display\fR 4
28299 .IX Xref "sv_uni_display"
28300 .IX Item "sv_uni_display"
28301 Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the scalar \f(CW\*(C`sv\*(C'\fR,
28302 the displayable version being at most \f(CW\*(C`pvlim\*(C'\fR bytes long
28303 (if longer, the rest is truncated and "..." will be appended).
28304 .Sp
28305 The \f(CW\*(C`flags\*(C'\fR argument is as in "pv_uni_display"().
28306 .Sp
28307 The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned.
28308 .RS 4
28309 .Sp
28310 .Vb 1
28311 \& char * sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
28312 .Ve
28313 .RE
28314 .RS 4
28315 .RE
28316 .ie n .IP """UNICODE_IS_NONCHAR""" 4
28317 .el .IP \f(CWUNICODE_IS_NONCHAR\fR 4
28318 .IX Xref "UNICODE_IS_NONCHAR"
28319 .IX Item "UNICODE_IS_NONCHAR"
28320 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode
28321 non-character code points
28322 .RS 4
28323 .Sp
28324 .Vb 1
28325 \& bool UNICODE_IS_NONCHAR(const UV uv)
28326 .Ve
28327 .RE
28328 .RS 4
28329 .RE
28330 .ie n .IP """UNICODE_IS_REPLACEMENT""" 4
28331 .el .IP \f(CWUNICODE_IS_REPLACEMENT\fR 4
28332 .IX Xref "UNICODE_IS_REPLACEMENT"
28333 .IX Item "UNICODE_IS_REPLACEMENT"
28334 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is the Unicode REPLACEMENT
28335 CHARACTER
28336 .RS 4
28337 .Sp
28338 .Vb 1
28339 \& bool UNICODE_IS_REPLACEMENT(const UV uv)
28340 .Ve
28341 .RE
28342 .RS 4
28343 .RE
28344 .ie n .IP """UNICODE_IS_SUPER""" 4
28345 .el .IP \f(CWUNICODE_IS_SUPER\fR 4
28346 .IX Xref "UNICODE_IS_SUPER"
28347 .IX Item "UNICODE_IS_SUPER"
28348 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is above the maximum legal Unicode
28349 code point of U+10FFFF.
28350 .RS 4
28351 .Sp
28352 .Vb 1
28353 \& bool UNICODE_IS_SUPER(const UV uv)
28354 .Ve
28355 .RE
28356 .RS 4
28357 .RE
28358 .ie n .IP """UNICODE_IS_SURROGATE""" 4
28359 .el .IP \f(CWUNICODE_IS_SURROGATE\fR 4
28360 .IX Xref "UNICODE_IS_SURROGATE"
28361 .IX Item "UNICODE_IS_SURROGATE"
28362 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode surrogate
28363 code points
28364 .RS 4
28365 .Sp
28366 .Vb 1
28367 \& bool UNICODE_IS_SURROGATE(const UV uv)
28368 .Ve
28369 .RE
28370 .RS 4
28371 .RE
28372 .ie n .IP """UNICODE_REPLACEMENT""" 4
28373 .el .IP \f(CWUNICODE_REPLACEMENT\fR 4
28374 .IX Xref "UNICODE_REPLACEMENT"
28375 .IX Item "UNICODE_REPLACEMENT"
28376 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT CHARACTER
28377 .ie n .IP """UNI_TO_NATIVE""" 4
28378 .el .IP \f(CWUNI_TO_NATIVE\fR 4
28379 .IX Xref "UNI_TO_NATIVE"
28380 .IX Item "UNI_TO_NATIVE"
28381 Returns the native equivalent of the input Unicode code point given by \f(CW\*(C`ch\*(C'\fR.
28382 Thus, \f(CWUNI_TO_NATIVE(68)\fR on EBCDIC platforms returns 196. These each
28383 represent the character \f(CW"D"\fR on their respective platforms. On ASCII
28384 platforms no conversion is needed, so this macro expands to just its input,
28385 adding no time nor space requirements to the implementation.
28386 .RS 4
28387 .Sp
28388 .Vb 1
28389 \& UV UNI_TO_NATIVE(UV ch)
28390 .Ve
28391 .RE
28392 .RS 4
28393 .RE
28394 .ie n .IP """UTF8_CHK_SKIP""" 4
28395 .el .IP \f(CWUTF8_CHK_SKIP\fR 4
28396 .IX Xref "UTF8_CHK_SKIP"
28397 .IX Item "UTF8_CHK_SKIP"
28398 This is a safer version of \f(CW"UTF8SKIP"\fR, but still not as safe as
28399 \&\f(CW"UTF8_SAFE_SKIP"\fR. This version doesn't blindly assume that the input
28400 string pointed to by \f(CW\*(C`s\*(C'\fR is well-formed, but verifies that there isn't a NUL
28401 terminating character before the expected end of the next character in \f(CW\*(C`s\*(C'\fR.
28402 The length \f(CW\*(C`UTF8_CHK_SKIP\*(C'\fR returns stops just before any such NUL.
28403 .Sp
28404 Perl tends to add NULs, as an insurance policy, after the end of strings in
28405 SV's, so it is likely that using this macro will prevent inadvertent reading
28406 beyond the end of the input buffer, even if it is malformed UTF\-8.
28407 .Sp
28408 This macro is intended to be used by XS modules where the inputs could be
28409 malformed, and it isn't feasible to restructure to use the safer
28410 \&\f(CW"UTF8_SAFE_SKIP"\fR, for example when interfacing with a C library.
28411 .RS 4
28412 .Sp
28413 .Vb 1
28414 \& STRLEN UTF8_CHK_SKIP(char* s)
28415 .Ve
28416 .RE
28417 .RS 4
28418 .RE
28419 .ie n .IP """utf8_distance""" 4
28420 .el .IP \f(CWutf8_distance\fR 4
28421 .IX Xref "utf8_distance"
28422 .IX Item "utf8_distance"
28423 Returns the number of UTF\-8 characters between the UTF\-8 pointers \f(CW\*(C`a\*(C'\fR
28424 and \f(CW\*(C`b\*(C'\fR.
28425 .Sp
28426 WARNING: use only if you *know* that the pointers point inside the
28427 same UTF\-8 buffer.
28428 .RS 4
28429 .Sp
28430 .Vb 1
28431 \& IV utf8_distance(const U8 *a, const U8 *b)
28432 .Ve
28433 .RE
28434 .RS 4
28435 .RE
28436 .ie n .IP """utf8_hop""" 4
28437 .el .IP \f(CWutf8_hop\fR 4
28438 .IX Xref "utf8_hop"
28439 .IX Item "utf8_hop"
28440 Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by \f(CW\*(C`off\*(C'\fR characters, either
28441 forward (if \f(CW\*(C`off\*(C'\fR is positive) or backward (if negative). \f(CW\*(C`s\*(C'\fR does not need
28442 to be pointing to the starting byte of a character. If it isn't, one count of
28443 \&\f(CW\*(C`off\*(C'\fR will be used up to get to the start of the next character for forward
28444 hops, and to the start of the current character for negative ones.
28445 .Sp
28446 WARNING: Prefer "utf8_hop_safe" to this one.
28447 .Sp
28448 Do NOT use this function unless you \fBknow\fR \f(CW\*(C`off\*(C'\fR is within
28449 the UTF\-8 data pointed to by \f(CW\*(C`s\*(C'\fR \fBand\fR that on entry \f(CW\*(C`s\*(C'\fR is aligned
28450 on the first byte of a character or just after the last byte of a character.
28451 .RS 4
28452 .Sp
28453 .Vb 1
28454 \& U8 * utf8_hop(const U8 *s, SSize_t off)
28455 .Ve
28456 .RE
28457 .RS 4
28458 .RE
28459 .ie n .IP """utf8_hop_back""" 4
28460 .el .IP \f(CWutf8_hop_back\fR 4
28461 .IX Xref "utf8_hop_back"
28462 .IX Item "utf8_hop_back"
28463 Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters,
28464 backward. \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a
28465 character. If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to that
28466 start.
28467 .Sp
28468 \&\f(CW\*(C`off\*(C'\fR must be non-positive.
28469 .Sp
28470 \&\f(CW\*(C`s\*(C'\fR must be after or equal to \f(CW\*(C`start\*(C'\fR.
28471 .Sp
28472 When moving backward it will not move before \f(CW\*(C`start\*(C'\fR.
28473 .Sp
28474 Will not exceed this limit even if the string is not valid "UTF\-8".
28475 .RS 4
28476 .Sp
28477 .Vb 1
28478 \& U8 * utf8_hop_back(const U8 *s, SSize_t off, const U8 *start)
28479 .Ve
28480 .RE
28481 .RS 4
28482 .RE
28483 .ie n .IP """utf8_hop_forward""" 4
28484 .el .IP \f(CWutf8_hop_forward\fR 4
28485 .IX Xref "utf8_hop_forward"
28486 .IX Item "utf8_hop_forward"
28487 Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters,
28488 forward. \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a
28489 character. If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to the
28490 start of the next character.
28491 .Sp
28492 \&\f(CW\*(C`off\*(C'\fR must be non-negative.
28493 .Sp
28494 \&\f(CW\*(C`s\*(C'\fR must be before or equal to \f(CW\*(C`end\*(C'\fR.
28495 .Sp
28496 When moving forward it will not move beyond \f(CW\*(C`end\*(C'\fR.
28497 .Sp
28498 Will not exceed this limit even if the string is not valid "UTF\-8".
28499 .RS 4
28500 .Sp
28501 .Vb 1
28502 \& U8 * utf8_hop_forward(const U8 *s, SSize_t off, const U8 *end)
28503 .Ve
28504 .RE
28505 .RS 4
28506 .RE
28507 .ie n .IP """utf8_hop_safe""" 4
28508 .el .IP \f(CWutf8_hop_safe\fR 4
28509 .IX Xref "utf8_hop_safe"
28510 .IX Item "utf8_hop_safe"
28511 Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters,
28512 either forward or backward. \f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting
28513 byte of a character. If it isn't, one count of \f(CW\*(C`off\*(C'\fR will be used up to get
28514 to the start of the next character for forward hops, and to the start of the
28515 current character for negative ones.
28516 .Sp
28517 When moving backward it will not move before \f(CW\*(C`start\*(C'\fR.
28518 .Sp
28519 When moving forward it will not move beyond \f(CW\*(C`end\*(C'\fR.
28520 .Sp
28521 Will not exceed those limits even if the string is not valid "UTF\-8".
28522 .RS 4
28523 .Sp
28524 .Vb 2
28525 \& U8 * utf8_hop_safe(const U8 *s, SSize_t off, const U8 *start,
28526 \& const U8 *end)
28527 .Ve
28528 .RE
28529 .RS 4
28530 .RE
28531 .ie n .IP """UTF8_IS_INVARIANT""" 4
28532 .el .IP \f(CWUTF8_IS_INVARIANT\fR 4
28533 .IX Xref "UTF8_IS_INVARIANT"
28534 .IX Item "UTF8_IS_INVARIANT"
28535 Evaluates to 1 if the byte \f(CW\*(C`c\*(C'\fR represents the same character when encoded in
28536 UTF\-8 as when not; otherwise evaluates to 0. UTF\-8 invariant characters can be
28537 copied as-is when converting to/from UTF\-8, saving time.
28538 .Sp
28539 In spite of the name, this macro gives the correct result if the input string
28540 from which \f(CW\*(C`c\*(C'\fR comes is not encoded in UTF\-8.
28541 .Sp
28542 See \f(CW"UVCHR_IS_INVARIANT"\fR for checking if a UV is invariant.
28543 .RS 4
28544 .Sp
28545 .Vb 1
28546 \& bool UTF8_IS_INVARIANT(char c)
28547 .Ve
28548 .RE
28549 .RS 4
28550 .RE
28551 .ie n .IP """UTF8_IS_NONCHAR""" 4
28552 .el .IP \f(CWUTF8_IS_NONCHAR\fR 4
28553 .IX Xref "UTF8_IS_NONCHAR"
28554 .IX Item "UTF8_IS_NONCHAR"
28555 Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
28556 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents one
28557 of the Unicode non-character code points; otherwise it evaluates to 0. If
28558 non-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code
28559 point's representation.
28560 .RS 4
28561 .Sp
28562 .Vb 1
28563 \& bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
28564 .Ve
28565 .RE
28566 .RS 4
28567 .RE
28568 .ie n .IP """UTF8_IS_REPLACEMENT""" 4
28569 .el .IP \f(CWUTF8_IS_REPLACEMENT\fR 4
28570 .IX Xref "UTF8_IS_REPLACEMENT"
28571 .IX Item "UTF8_IS_REPLACEMENT"
28572 Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
28573 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents the
28574 Unicode REPLACEMENT CHARACTER; otherwise it evaluates to 0. If non-zero, the
28575 value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point's
28576 representation.
28577 .RS 4
28578 .Sp
28579 .Vb 1
28580 \& bool UTF8_IS_REPLACEMENT(const U8 *s, const U8 *e)
28581 .Ve
28582 .RE
28583 .RS 4
28584 .RE
28585 .ie n .IP """UTF8_IS_SUPER""" 4
28586 .el .IP \f(CWUTF8_IS_SUPER\fR 4
28587 .IX Xref "UTF8_IS_SUPER"
28588 .IX Item "UTF8_IS_SUPER"
28589 Recall that Perl recognizes an extension to UTF\-8 that can encode code
28590 points larger than the ones defined by Unicode, which are 0..0x10FFFF.
28591 .Sp
28592 This macro evaluates to non-zero if the first few bytes of the string starting
28593 at \f(CW\*(C`s\*(C'\fR and looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are from this UTF\-8 extension;
28594 otherwise it evaluates to 0. If non-zero, the return is how many bytes
28595 starting at \f(CW\*(C`s\*(C'\fR comprise the code point's representation.
28596 .Sp
28597 0 is returned if the bytes are not well-formed extended UTF\-8, or if they
28598 represent a code point that cannot fit in a UV on the current platform. Hence
28599 this macro can give different results when run on a 64\-bit word machine than on
28600 one with a 32\-bit word size.
28601 .Sp
28602 Note that it is illegal in Perl to have code points that are larger than what can
28603 fit in an IV on the current machine; and illegal in Unicode to have any that
28604 this macro matches
28605 .RS 4
28606 .Sp
28607 .Vb 1
28608 \& bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
28609 .Ve
28610 .RE
28611 .RS 4
28612 .RE
28613 .ie n .IP """UTF8_IS_SURROGATE""" 4
28614 .el .IP \f(CWUTF8_IS_SURROGATE\fR 4
28615 .IX Xref "UTF8_IS_SURROGATE"
28616 .IX Item "UTF8_IS_SURROGATE"
28617 Evaluates to non-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
28618 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well-formed UTF\-8 that represents one
28619 of the Unicode surrogate code points; otherwise it evaluates to 0. If
28620 non-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code
28621 point's representation.
28622 .RS 4
28623 .Sp
28624 .Vb 1
28625 \& bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
28626 .Ve
28627 .RE
28628 .RS 4
28629 .RE
28630 .ie n .IP """utf8_length""" 4
28631 .el .IP \f(CWutf8_length\fR 4
28632 .IX Xref "utf8_length"
28633 .IX Item "utf8_length"
28634 Returns the number of characters in the sequence of UTF\-8\-encoded bytes starting
28635 at \f(CW\*(C`s\*(C'\fR and ending at the byte just before \f(CW\*(C`e\*(C'\fR. If <s> and <e> point to the
28636 same place, it returns 0 with no warning raised.
28637 .Sp
28638 If \f(CW\*(C`e < s\*(C'\fR or if the scan would end up past \f(CW\*(C`e\*(C'\fR, it raises a UTF8 warning
28639 and returns the number of valid characters.
28640 .RS 4
28641 .Sp
28642 .Vb 1
28643 \& STRLEN utf8_length(const U8 *s0, const U8 *e)
28644 .Ve
28645 .RE
28646 .RS 4
28647 .RE
28648 .ie n .IP """UTF8_MAXBYTES""" 4
28649 .el .IP \f(CWUTF8_MAXBYTES\fR 4
28650 .IX Xref "UTF8_MAXBYTES"
28651 .IX Item "UTF8_MAXBYTES"
28652 The maximum width of a single UTF\-8 encoded character, in bytes.
28653 .Sp
28654 NOTE: Strictly speaking Perl's UTF\-8 should not be called UTF\-8 since UTF\-8
28655 is an encoding of Unicode, and Unicode's upper limit, 0x10FFFF, can be
28656 expressed with 4 bytes. However, Perl thinks of UTF\-8 as a way to encode
28657 non-negative integers in a binary format, even those above Unicode.
28658 .ie n .IP """UTF8_MAXBYTES_CASE""" 4
28659 .el .IP \f(CWUTF8_MAXBYTES_CASE\fR 4
28660 .IX Xref "UTF8_MAXBYTES_CASE"
28661 .IX Item "UTF8_MAXBYTES_CASE"
28662 The maximum number of UTF\-8 bytes a single Unicode character can
28663 uppercase/lowercase/titlecase/fold into.
28664 .ie n .IP """utf8ness_t""" 4
28665 .el .IP \f(CWutf8ness_t\fR 4
28666 .IX Xref "utf8ness_t"
28667 .IX Item "utf8ness_t"
28668 This typedef is used by several core functions that return PV strings, to
28669 indicate the UTF\-8ness of those strings.
28670 .Sp
28671 (If you write a new function, you probably should instead return the PV in an
28672 SV with the UTF\-8 flag of the SV properly set, rather than use this mechanism.)
28673 .Sp
28674 The possible values this can be are:
28675 .RS 4
28676 .ie n .IP """UTF8NESS_YES""" 4
28677 .el .IP \f(CWUTF8NESS_YES\fR 4
28678 .IX Item "UTF8NESS_YES"
28679 This means the string definitely should be treated as a sequence of
28680 UTF\-8\-encoded characters.
28681 .Sp
28682 Most code that needs to handle this typedef should be of the form:
28683 .Sp
28684 .Vb 3
28685 \& if (utf8ness_flag == UTF8NESS_YES) {
28686 \& treat as utf8; // like turning on an SV UTF\-8 flag
28687 \& }
28688 .Ve
28689 .ie n .IP """UTF8NESS_NO""" 4
28690 .el .IP \f(CWUTF8NESS_NO\fR 4
28691 .IX Item "UTF8NESS_NO"
28692 This means the string definitely should be treated as a sequence of bytes, not
28693 encoded as UTF\-8.
28694 .ie n .IP """UTF8NESS_IMMATERIAL""" 4
28695 .el .IP \f(CWUTF8NESS_IMMATERIAL\fR 4
28696 .IX Item "UTF8NESS_IMMATERIAL"
28697 This means it is equally valid to treat the string as bytes, or as UTF\-8
28698 characters; use whichever way you want. This happens when the string consists
28699 entirely of characters which have the same representation whether encoded in
28700 UTF\-8 or not.
28701 .ie n .IP """UTF8NESS_UNKNOWN""" 4
28702 .el .IP \f(CWUTF8NESS_UNKNOWN\fR 4
28703 .IX Item "UTF8NESS_UNKNOWN"
28704 This means it is unknown how the string should be treated. No core function
28705 will ever return this value to a non-core caller. Instead, it is used by the
28706 caller to initialize a variable to a non-legal value. A typical call will look like:
28707 .Sp
28708 .Vb 5
28709 \& utf8ness_t string_is_utf8 = UTF8NESS_UNKNOWN
28710 \& const char * string = foo(arg1, arg2, ..., &string_is_utf8);
28711 \& if (string_is_utf8 == UTF8NESS_YES) {
28712 \& do something for UTF\-8;
28713 \& }
28714 .Ve
28715 .RE
28716 .RS 4
28717 .Sp
28718 The following relationships hold between the enum values:
28719 .ie n .IP """0\ <=\ \fIenum\ value\fR\ <=\ UTF8NESS_IMMATERIAL""" 4
28720 .el .IP "\f(CW0\ <=\ \fR\f(CIenum\ value\fR\f(CW\ <=\ UTF8NESS_IMMATERIAL\fR" 4
28721 .IX Item "0 <= enum value <= UTF8NESS_IMMATERIAL"
28722 the string may be treated in code as non\-UTF8
28723 .ie n .IP """UTF8NESS_IMMATERIAL\ <=\ <\fIenum\ value\fR""" 4
28724 .el .IP "\f(CWUTF8NESS_IMMATERIAL\ <=\ <\fR\f(CIenum\ value\fR\f(CW\fR" 4
28725 .IX Item "UTF8NESS_IMMATERIAL <= <enum value"
28726 the string may be treated in code as encoded in UTF\-8
28727 .RE
28728 .RS 4
28729 .RE
28730 .ie n .IP """utf8n_to_uvchr""" 4
28731 .el .IP \f(CWutf8n_to_uvchr\fR 4
28732 .IX Xref "utf8n_to_uvchr"
28733 .IX Item "utf8n_to_uvchr"
28734 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
28735 Most code should use "utf8_to_uvchr_buf"() rather than call this
28736 directly.
28737 .Sp
28738 Bottom level UTF\-8 decode routine.
28739 Returns the native code point value of the first character in the string \f(CW\*(C`s\*(C'\fR,
28740 which is assumed to be in UTF\-8 (or UTF-EBCDIC) encoding, and no longer than
28741 \&\f(CW\*(C`curlen\*(C'\fR bytes; \f(CW*retlen\fR (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) will be set to
28742 the length, in bytes, of that character.
28743 .Sp
28744 The value of \f(CW\*(C`flags\*(C'\fR determines the behavior when \f(CW\*(C`s\*(C'\fR does not point to a
28745 well-formed UTF\-8 character. If \f(CW\*(C`flags\*(C'\fR is 0, encountering a malformation
28746 causes zero to be returned and \f(CW*retlen\fR is set so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR)
28747 is the next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed
28748 character. Also, if UTF\-8 warnings haven't been lexically disabled, a warning
28749 is raised. Some UTF\-8 input sequences may contain multiple malformations.
28750 This function tries to find every possible one in each call, so multiple
28751 warnings can be raised for the same sequence.
28752 .Sp
28753 Various ALLOW flags can be set in \f(CW\*(C`flags\*(C'\fR to allow (and not warn on)
28754 individual types of malformations, such as the sequence being overlong (that
28755 is, when there is a shorter sequence that can express the same code point;
28756 overlong sequences are expressly forbidden in the UTF\-8 standard due to
28757 potential security issues). Another malformation example is the first byte of
28758 a character not being a legal first byte. See \fIutf8.h\fR for the list of such
28759 flags. Even if allowed, this function generally returns the Unicode
28760 REPLACEMENT CHARACTER when it encounters a malformation. There are flags in
28761 \&\fIutf8.h\fR to override this behavior for the overlong malformations, but don't
28762 do that except for very specialized purposes.
28763 .Sp
28764 The \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag overrides the behavior when a non-allowed (by other
28765 flags) malformation is found. If this flag is set, the routine assumes that
28766 the caller will raise a warning, and this function will silently just set
28767 \&\f(CW\*(C`retlen\*(C'\fR to \f(CW\-1\fR (cast to \f(CW\*(C`STRLEN\*(C'\fR) and return zero.
28768 .Sp
28769 Note that this API requires disambiguation between successful decoding a \f(CW\*(C`NUL\*(C'\fR
28770 character, and an error return (unless the \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag is set), as
28771 in both cases, 0 is returned, and, depending on the malformation, \f(CW\*(C`retlen\*(C'\fR may
28772 be set to 1. To disambiguate, upon a zero return, see if the first byte of
28773 \&\f(CW\*(C`s\*(C'\fR is 0 as well. If so, the input was a \f(CW\*(C`NUL\*(C'\fR; if not, the input had an
28774 error. Or you can use \f(CW"utf8n_to_uvchr_error"\fR.
28775 .Sp
28776 Certain code points are considered problematic. These are Unicode surrogates,
28777 Unicode non-characters, and code points above the Unicode maximum of 0x10FFFF.
28778 By default these are considered regular code points, but certain situations
28779 warrant special handling for them, which can be specified using the \f(CW\*(C`flags\*(C'\fR
28780 parameter. If \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, all
28781 three classes are treated as malformations and handled as such. The flags
28782 \&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR, \f(CW\*(C`UTF8_DISALLOW_NONCHAR\*(C'\fR, and
28783 \&\f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR (meaning above the legal Unicode maximum) can be set to
28784 disallow these categories individually. \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR
28785 restricts the allowed inputs to the strict UTF\-8 traditionally defined by
28786 Unicode. Use \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR to use the strictness
28787 definition given by
28788 Unicode Corrigendum #9 <https://www.unicode.org/versions/corrigendum9.html>.
28789 The difference between traditional strictness and C9 strictness is that the
28790 latter does not forbid non-character code points. (They are still discouraged,
28791 however.) For more discussion see "Noncharacter code points" in perlunicode.
28792 .Sp
28793 The flags \f(CW\*(C`UTF8_WARN_ILLEGAL_INTERCHANGE\*(C'\fR,
28794 \&\f(CW\*(C`UTF8_WARN_ILLEGAL_C9_INTERCHANGE\*(C'\fR, \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR,
28795 \&\f(CW\*(C`UTF8_WARN_NONCHAR\*(C'\fR, and \f(CW\*(C`UTF8_WARN_SUPER\*(C'\fR will cause warning messages to be
28796 raised for their respective categories, but otherwise the code points are
28797 considered valid (not malformations). To get a category to both be treated as
28798 a malformation and raise a warning, specify both the WARN and DISALLOW flags.
28799 (But note that warnings are not raised if lexically disabled nor if
28800 \&\f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR is also specified.)
28801 .Sp
28802 Extremely high code points were never specified in any standard, and require an
28803 extension to UTF\-8 to express, which Perl does. It is likely that programs
28804 written in something other than Perl would not be able to read files that
28805 contain these; nor would Perl understand files written by something that uses a
28806 different extension. For these reasons, there is a separate set of flags that
28807 can warn and/or disallow these extremely high code points, even if other
28808 above-Unicode ones are accepted. They are the \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR and
28809 \&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR flags. For more information see
28810 \&\f(CW"UTF8_GOT_PERL_EXTENDED"\fR. Of course \f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR will treat all
28811 above-Unicode code points, including these, as malformations.
28812 (Note that the Unicode standard considers anything above 0x10FFFF to be
28813 illegal, but there are standards predating it that allow up to 0x7FFF_FFFF
28814 (2**31 \-1))
28815 .Sp
28816 A somewhat misleadingly named synonym for \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR is
28817 retained for backward compatibility: \f(CW\*(C`UTF8_WARN_ABOVE_31_BIT\*(C'\fR. Similarly,
28818 \&\f(CW\*(C`UTF8_DISALLOW_ABOVE_31_BIT\*(C'\fR is usable instead of the more accurately named
28819 \&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR. The names are misleading because these flags
28820 can apply to code points that actually do fit in 31 bits. This happens on
28821 EBCDIC platforms, and sometimes when the overlong
28822 malformation is also present. The new names accurately
28823 describe the situation in all cases.
28824 .Sp
28825 All other code points corresponding to Unicode characters, including private
28826 use and those yet to be assigned, are never considered malformed and never
28827 warn.
28828 .RS 4
28829 .Sp
28830 .Vb 2
28831 \& UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen,
28832 \& const U32 flags)
28833 .Ve
28834 .RE
28835 .RS 4
28836 .RE
28837 .ie n .IP """utf8n_to_uvchr_error""" 4
28838 .el .IP \f(CWutf8n_to_uvchr_error\fR 4
28839 .IX Xref "utf8n_to_uvchr_error"
28840 .IX Item "utf8n_to_uvchr_error"
28841 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
28842 Most code should use "utf8_to_uvchr_buf"() rather than call this
28843 directly.
28844 .Sp
28845 This function is for code that needs to know what the precise malformation(s)
28846 are when an error is found. If you also need to know the generated warning
28847 messages, use "utf8n_to_uvchr_msgs"() instead.
28848 .Sp
28849 It is like \f(CW"utf8n_to_uvchr"\fR but it takes an extra parameter placed after
28850 all the others, \f(CW\*(C`errors\*(C'\fR. If this parameter is 0, this function behaves
28851 identically to \f(CW"utf8n_to_uvchr"\fR. Otherwise, \f(CW\*(C`errors\*(C'\fR should be a pointer
28852 to a \f(CW\*(C`U32\*(C'\fR variable, which this function sets to indicate any errors found.
28853 Upon return, if \f(CW*errors\fR is 0, there were no errors found. Otherwise,
28854 \&\f(CW*errors\fR is the bit-wise \f(CW\*(C`OR\*(C'\fR of the bits described in the list below. Some
28855 of these bits will be set if a malformation is found, even if the input
28856 \&\f(CW\*(C`flags\*(C'\fR parameter indicates that the given malformation is allowed; those
28857 exceptions are noted:
28858 .RS 4
28859 .ie n .IP """UTF8_GOT_PERL_EXTENDED""" 4
28860 .el .IP \f(CWUTF8_GOT_PERL_EXTENDED\fR 4
28861 .IX Item "UTF8_GOT_PERL_EXTENDED"
28862 The input sequence is not standard UTF\-8, but a Perl extension. This bit is
28863 set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
28864 \&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR or the \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR flags.
28865 .Sp
28866 Code points above 0x7FFF_FFFF (2**31 \- 1) were never specified in any standard,
28867 and so some extension must be used to express them. Perl uses a natural
28868 extension to UTF\-8 to represent the ones up to 2**36\-1, and invented a further
28869 extension to represent even higher ones, so that any code point that fits in a
28870 64\-bit word can be represented. Text using these extensions is not likely to
28871 be portable to non-Perl code. We lump both of these extensions together and
28872 refer to them as Perl extended UTF\-8. There exist other extensions that people
28873 have invented, incompatible with Perl's.
28874 .Sp
28875 On EBCDIC platforms starting in Perl v5.24, the Perl extension for representing
28876 extremely high code points kicks in at 0x3FFF_FFFF (2**30 \-1), which is lower
28877 than on ASCII. Prior to that, code points 2**31 and higher were simply
28878 unrepresentable, and a different, incompatible method was used to represent
28879 code points between 2**30 and 2**31 \- 1.
28880 .Sp
28881 On both platforms, ASCII and EBCDIC, \f(CW\*(C`UTF8_GOT_PERL_EXTENDED\*(C'\fR is set if
28882 Perl extended UTF\-8 is used.
28883 .Sp
28884 In earlier Perls, this bit was named \f(CW\*(C`UTF8_GOT_ABOVE_31_BIT\*(C'\fR, which you still
28885 may use for backward compatibility. That name is misleading, as this flag may
28886 be set when the code point actually does fit in 31 bits. This happens on
28887 EBCDIC platforms, and sometimes when the overlong
28888 malformation is also present. The new name accurately
28889 describes the situation in all cases.
28890 .ie n .IP """UTF8_GOT_CONTINUATION""" 4
28891 .el .IP \f(CWUTF8_GOT_CONTINUATION\fR 4
28892 .IX Item "UTF8_GOT_CONTINUATION"
28893 The input sequence was malformed in that the first byte was a UTF\-8
28894 continuation byte.
28895 .ie n .IP """UTF8_GOT_EMPTY""" 4
28896 .el .IP \f(CWUTF8_GOT_EMPTY\fR 4
28897 .IX Item "UTF8_GOT_EMPTY"
28898 The input \f(CW\*(C`curlen\*(C'\fR parameter was 0.
28899 .ie n .IP """UTF8_GOT_LONG""" 4
28900 .el .IP \f(CWUTF8_GOT_LONG\fR 4
28901 .IX Item "UTF8_GOT_LONG"
28902 The input sequence was malformed in that there is some other sequence that
28903 evaluates to the same code point, but that sequence is shorter than this one.
28904 .Sp
28905 Until Unicode 3.1, it was legal for programs to accept this malformation, but
28906 it was discovered that this created security issues.
28907 .ie n .IP """UTF8_GOT_NONCHAR""" 4
28908 .el .IP \f(CWUTF8_GOT_NONCHAR\fR 4
28909 .IX Item "UTF8_GOT_NONCHAR"
28910 The code point represented by the input UTF\-8 sequence is for a Unicode
28911 non-character code point.
28912 This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
28913 \&\f(CW\*(C`UTF8_DISALLOW_NONCHAR\*(C'\fR or the \f(CW\*(C`UTF8_WARN_NONCHAR\*(C'\fR flags.
28914 .ie n .IP """UTF8_GOT_NON_CONTINUATION""" 4
28915 .el .IP \f(CWUTF8_GOT_NON_CONTINUATION\fR 4
28916 .IX Item "UTF8_GOT_NON_CONTINUATION"
28917 The input sequence was malformed in that a non-continuation type byte was found
28918 in a position where only a continuation type one should be. See also
28919 \&\f(CW"UTF8_GOT_SHORT"\fR.
28920 .ie n .IP """UTF8_GOT_OVERFLOW""" 4
28921 .el .IP \f(CWUTF8_GOT_OVERFLOW\fR 4
28922 .IX Item "UTF8_GOT_OVERFLOW"
28923 The input sequence was malformed in that it is for a code point that is not
28924 representable in the number of bits available in an IV on the current platform.
28925 .ie n .IP """UTF8_GOT_SHORT""" 4
28926 .el .IP \f(CWUTF8_GOT_SHORT\fR 4
28927 .IX Item "UTF8_GOT_SHORT"
28928 The input sequence was malformed in that \f(CW\*(C`curlen\*(C'\fR is smaller than required for
28929 a complete sequence. In other words, the input is for a partial character
28930 sequence.
28931 .Sp
28932 \&\f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR and \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR both indicate a too short
28933 sequence. The difference is that \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR indicates always
28934 that there is an error, while \f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR means that an incomplete
28935 sequence was looked at. If no other flags are present, it means that the
28936 sequence was valid as far as it went. Depending on the application, this could
28937 mean one of three things:
28938 .RS 4
28939 .IP \(bu 4
28940 The \f(CW\*(C`curlen\*(C'\fR length parameter passed in was too small, and the function was
28941 prevented from examining all the necessary bytes.
28942 .IP \(bu 4
28943 The buffer being looked at is based on reading data, and the data received so
28944 far stopped in the middle of a character, so that the next read will
28945 read the remainder of this character. (It is up to the caller to deal with the
28946 split bytes somehow.)
28947 .IP \(bu 4
28948 This is a real error, and the partial sequence is all we're going to get.
28949 .RE
28950 .RS 4
28951 .RE
28952 .ie n .IP """UTF8_GOT_SUPER""" 4
28953 .el .IP \f(CWUTF8_GOT_SUPER\fR 4
28954 .IX Item "UTF8_GOT_SUPER"
28955 The input sequence was malformed in that it is for a non-Unicode code point;
28956 that is, one above the legal Unicode maximum.
28957 This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
28958 \&\f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SUPER\*(C'\fR flags.
28959 .ie n .IP """UTF8_GOT_SURROGATE""" 4
28960 .el .IP \f(CWUTF8_GOT_SURROGATE\fR 4
28961 .IX Item "UTF8_GOT_SURROGATE"
28962 The input sequence was malformed in that it is for a \-Unicode UTF\-16 surrogate
28963 code point.
28964 This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
28965 \&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR flags.
28966 .RE
28967 .RS 4
28968 .Sp
28969 To do your own error handling, call this function with the \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR
28970 flag to suppress any warnings, and then examine the \f(CW*errors\fR return.
28971 .Sp
28972 .Vb 3
28973 \& UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
28974 \& STRLEN *retlen, const U32 flags,
28975 \& U32 *errors)
28976 .Ve
28977 .RE
28978 .RS 4
28979 .RE
28980 .ie n .IP """utf8n_to_uvchr_msgs""" 4
28981 .el .IP \f(CWutf8n_to_uvchr_msgs\fR 4
28982 .IX Xref "utf8n_to_uvchr_msgs"
28983 .IX Item "utf8n_to_uvchr_msgs"
28984 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
28985 Most code should use "utf8_to_uvchr_buf"() rather than call this
28986 directly.
28987 .Sp
28988 This function is for code that needs to know what the precise malformation(s)
28989 are when an error is found, and wants the corresponding warning and/or error
28990 messages to be returned to the caller rather than be displayed. All messages
28991 that would have been displayed if all lexical warnings are enabled will be
28992 returned.
28993 .Sp
28994 It is just like \f(CW"utf8n_to_uvchr_error"\fR but it takes an extra parameter
28995 placed after all the others, \f(CW\*(C`msgs\*(C'\fR. If this parameter is 0, this function
28996 behaves identically to \f(CW"utf8n_to_uvchr_error"\fR. Otherwise, \f(CW\*(C`msgs\*(C'\fR should
28997 be a pointer to an \f(CW\*(C`AV *\*(C'\fR variable, in which this function creates a new AV to
28998 contain any appropriate messages. The elements of the array are ordered so
28999 that the first message that would have been displayed is in the 0th element,
29000 and so on. Each element is a hash with three key-value pairs, as follows:
29001 .RS 4
29002 .ie n .IP """text""" 4
29003 .el .IP \f(CWtext\fR 4
29004 .IX Item "text"
29005 The text of the message as a \f(CW\*(C`SVpv\*(C'\fR.
29006 .ie n .IP """warn_categories""" 4
29007 .el .IP \f(CWwarn_categories\fR 4
29008 .IX Item "warn_categories"
29009 The warning category (or categories) packed into a \f(CW\*(C`SVuv\*(C'\fR.
29010 .ie n .IP """flag""" 4
29011 .el .IP \f(CWflag\fR 4
29012 .IX Item "flag"
29013 A single flag bit associated with this message, in a \f(CW\*(C`SVuv\*(C'\fR.
29014 The bit corresponds to some bit in the \f(CW*errors\fR return value,
29015 such as \f(CW\*(C`UTF8_GOT_LONG\*(C'\fR.
29016 .RE
29017 .RS 4
29018 .Sp
29019 It's important to note that specifying this parameter as non-null will cause
29020 any warnings this function would otherwise generate to be suppressed, and
29021 instead be placed in \f(CW*msgs\fR. The caller can check the lexical warnings state
29022 (or not) when choosing what to do with the returned messages.
29023 .Sp
29024 If the flag \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR is passed, no warnings are generated, and hence
29025 no AV is created.
29026 .Sp
29027 The caller, of course, is responsible for freeing any returned AV.
29028 .Sp
29029 .Vb 3
29030 \& UV utf8n_to_uvchr_msgs(const U8 *s, STRLEN curlen,
29031 \& STRLEN *retlen, const U32 flags,
29032 \& U32 *errors, AV **msgs)
29033 .Ve
29034 .RE
29035 .RS 4
29036 .RE
29037 .ie n .IP """UTF8_SAFE_SKIP""" 4
29038 .el .IP \f(CWUTF8_SAFE_SKIP\fR 4
29039 .IX Xref "UTF8_SAFE_SKIP"
29040 .IX Item "UTF8_SAFE_SKIP"
29041 returns 0 if \f(CW\*(C`s\ >=\ e\*(C'\fR; otherwise returns the number of bytes in the
29042 UTF\-8 encoded character whose first byte is pointed to by \f(CW\*(C`s\*(C'\fR. But it never
29043 returns beyond \f(CW\*(C`e\*(C'\fR. On DEBUGGING builds, it asserts that \f(CW\*(C`s\ <=\ e\*(C'\fR.
29044 .RS 4
29045 .Sp
29046 .Vb 1
29047 \& STRLEN UTF8_SAFE_SKIP(char* s, char* e)
29048 .Ve
29049 .RE
29050 .RS 4
29051 .RE
29052 .ie n .IP """UTF8SKIP""" 4
29053 .el .IP \f(CWUTF8SKIP\fR 4
29054 .IX Xref "UTF8SKIP"
29055 .IX Item "UTF8SKIP"
29056 returns the number of bytes a non-malformed UTF\-8 encoded character whose first
29057 (perhaps only) byte is pointed to by \f(CW\*(C`s\*(C'\fR.
29058 .Sp
29059 If there is a possibility of malformed input, use instead:
29060 .RS 4
29061 .ie n .IP """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by ""s""; or" 4
29062 .el .IP "\f(CW""UTF8_SAFE_SKIP""\fR if you know the maximum ending pointer in the buffer pointed to by \f(CWs\fR; or" 4
29063 .IX Item """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by s; or"
29064 .PD 0
29065 .ie n .IP """UTF8_CHK_SKIP"" if you don't know it." 4
29066 .el .IP "\f(CW""UTF8_CHK_SKIP""\fR if you don't know it." 4
29067 .IX Item """UTF8_CHK_SKIP"" if you don't know it."
29068 .RE
29069 .RS 4
29070 .PD
29071 .Sp
29072 It is better to restructure your code so the end pointer is passed down so that
29073 you know what it actually is at the point of this call, but if that isn't
29074 possible, \f(CW"UTF8_CHK_SKIP"\fR can minimize the chance of accessing beyond the end
29075 of the input buffer.
29076 .Sp
29077 .Vb 1
29078 \& STRLEN UTF8SKIP(char* s)
29079 .Ve
29080 .RE
29081 .RS 4
29082 .RE
29083 .ie n .IP """UTF8_SKIP""" 4
29084 .el .IP \f(CWUTF8_SKIP\fR 4
29085 .IX Xref "UTF8_SKIP"
29086 .IX Item "UTF8_SKIP"
29087 This is a synonym for \f(CW"UTF8SKIP"\fR
29088 .RS 4
29089 .Sp
29090 .Vb 1
29091 \& STRLEN UTF8_SKIP(char* s)
29092 .Ve
29093 .RE
29094 .RS 4
29095 .RE
29096 .ie n .IP """utf8_to_bytes""" 4
29097 .el .IP \f(CWutf8_to_bytes\fR 4
29098 .IX Xref "utf8_to_bytes"
29099 .IX Item "utf8_to_bytes"
29100 NOTE: \f(CW\*(C`utf8_to_bytes\*(C'\fR is \fBexperimental\fR and may change or be
29101 removed without notice.
29102 .Sp
29103 Converts a string \f(CW"s"\fR of length \f(CW*lenp\fR from UTF\-8 into native byte encoding.
29104 Unlike "bytes_to_utf8", this over-writes the original string, and
29105 updates \f(CW*lenp\fR to contain the new length.
29106 Returns zero on failure (leaving \f(CW"s"\fR unchanged) setting \f(CW*lenp\fR to \-1.
29107 .Sp
29108 Upon successful return, the number of variants in the string can be computed by
29109 having saved the value of \f(CW*lenp\fR before the call, and subtracting the
29110 after-call value of \f(CW*lenp\fR from it.
29111 .Sp
29112 If you need a copy of the string, see "bytes_from_utf8".
29113 .RS 4
29114 .Sp
29115 .Vb 1
29116 \& U8 * utf8_to_bytes(U8 *s, STRLEN *lenp)
29117 .Ve
29118 .RE
29119 .RS 4
29120 .RE
29121 .ie n .IP """utf8_to_uvchr""" 4
29122 .el .IP \f(CWutf8_to_uvchr\fR 4
29123 .IX Xref "utf8_to_uvchr"
29124 .IX Item "utf8_to_uvchr"
29125 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`utf8_to_uvchr\*(C'\fR
29126 from a future release of Perl. Do not use it for
29127 new code; remove it from existing code.
29128 .Sp
29129 Returns the native code point of the first character in the string \f(CW\*(C`s\*(C'\fR
29130 which is assumed to be in UTF\-8 encoding; \f(CW\*(C`retlen\*(C'\fR will be set to the
29131 length, in bytes, of that character.
29132 .Sp
29133 Some, but not all, UTF\-8 malformations are detected, and in fact, some
29134 malformed input could cause reading beyond the end of the input buffer, which
29135 is why this function is deprecated. Use "utf8_to_uvchr_buf" instead.
29136 .Sp
29137 If \f(CW\*(C`s\*(C'\fR points to one of the detected malformations, and UTF8 warnings are
29138 enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't
29139 \&\f(CW\*(C`NULL\*(C'\fR) to \-1. If those warnings are off, the computed value if well-defined (or
29140 the Unicode REPLACEMENT CHARACTER, if not) is silently returned, and \f(CW*retlen\fR
29141 is set (if \f(CW\*(C`retlen\*(C'\fR isn't NULL) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is the
29142 next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character.
29143 See "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is returned.
29144 .RS 4
29145 .Sp
29146 .Vb 1
29147 \& UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
29148 .Ve
29149 .RE
29150 .RS 4
29151 .RE
29152 .ie n .IP """utf8_to_uvchr_buf""" 4
29153 .el .IP \f(CWutf8_to_uvchr_buf\fR 4
29154 .IX Xref "utf8_to_uvchr_buf"
29155 .IX Item "utf8_to_uvchr_buf"
29156 Returns the native code point of the first character in the string \f(CW\*(C`s\*(C'\fR which
29157 is assumed to be in UTF\-8 encoding; \f(CW\*(C`send\*(C'\fR points to 1 beyond the end of \f(CW\*(C`s\*(C'\fR.
29158 \&\f(CW*retlen\fR will be set to the length, in bytes, of that character.
29159 .Sp
29160 If \f(CW\*(C`s\*(C'\fR does not point to a well-formed UTF\-8 character and UTF8 warnings are
29161 enabled, zero is returned and \f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't
29162 \&\f(CW\*(C`NULL\*(C'\fR) to \-1. If those warnings are off, the computed value, if well-defined
29163 (or the Unicode REPLACEMENT CHARACTER if not), is silently returned, and
29164 \&\f(CW*retlen\fR is set (if \f(CW\*(C`retlen\*(C'\fR isn't \f(CW\*(C`NULL\*(C'\fR) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is
29165 the next possible position in \f(CW\*(C`s\*(C'\fR that could begin a non-malformed character.
29166 See "utf8n_to_uvchr" for details on when the REPLACEMENT CHARACTER is
29167 returned.
29168 .RS 4
29169 .Sp
29170 .Vb 1
29171 \& UV utf8_to_uvchr_buf(const U8 *s, const U8 *send, STRLEN *retlen)
29172 .Ve
29173 .RE
29174 .RS 4
29175 .RE
29176 .ie n .IP """UVCHR_IS_INVARIANT""" 4
29177 .el .IP \f(CWUVCHR_IS_INVARIANT\fR 4
29178 .IX Xref "UVCHR_IS_INVARIANT"
29179 .IX Item "UVCHR_IS_INVARIANT"
29180 Evaluates to 1 if the representation of code point \f(CW\*(C`cp\*(C'\fR is the same whether or
29181 not it is encoded in UTF\-8; otherwise evaluates to 0. UTF\-8 invariant
29182 characters can be copied as-is when converting to/from UTF\-8, saving time.
29183 \&\f(CW\*(C`cp\*(C'\fR is Unicode if above 255; otherwise is platform-native.
29184 .RS 4
29185 .Sp
29186 .Vb 1
29187 \& bool UVCHR_IS_INVARIANT(UV cp)
29188 .Ve
29189 .RE
29190 .RS 4
29191 .RE
29192 .ie n .IP """UVCHR_SKIP""" 4
29193 .el .IP \f(CWUVCHR_SKIP\fR 4
29194 .IX Xref "UVCHR_SKIP"
29195 .IX Item "UVCHR_SKIP"
29196 returns the number of bytes required to represent the code point \f(CW\*(C`cp\*(C'\fR when
29197 encoded as UTF\-8. \f(CW\*(C`cp\*(C'\fR is a native (ASCII or EBCDIC) code point if less than
29198 255; a Unicode code point otherwise.
29199 .RS 4
29200 .Sp
29201 .Vb 1
29202 \& STRLEN UVCHR_SKIP(UV cp)
29203 .Ve
29204 .RE
29205 .RS 4
29206 .RE
29207 .ie n .IP """uvchr_to_utf8_flags""" 4
29208 .el .IP \f(CWuvchr_to_utf8_flags\fR 4
29209 .IX Xref "uvchr_to_utf8_flags"
29210 .IX Item "uvchr_to_utf8_flags"
29211 Adds the UTF\-8 representation of the native code point \f(CW\*(C`uv\*(C'\fR to the end
29212 of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should have at least \f(CW\*(C`UVCHR_SKIP(uv)+1\*(C'\fR (up to
29213 \&\f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR) free bytes available. The return value is the pointer to
29214 the byte after the end of the new character. In other words,
29215 .Sp
29216 .Vb 1
29217 \& d = uvchr_to_utf8_flags(d, uv, flags);
29218 .Ve
29219 .Sp
29220 or, in most cases,
29221 .Sp
29222 .Vb 1
29223 \& d = uvchr_to_utf8_flags(d, uv, 0);
29224 .Ve
29225 .Sp
29226 This is the Unicode-aware way of saying
29227 .Sp
29228 .Vb 1
29229 \& *(d++) = uv;
29230 .Ve
29231 .Sp
29232 If \f(CW\*(C`flags\*(C'\fR is 0, this function accepts any code point from 0..\f(CW\*(C`IV_MAX\*(C'\fR as
29233 input. \f(CW\*(C`IV_MAX\*(C'\fR is typically 0x7FFF_FFFF in a 32\-bit word.
29234 .Sp
29235 Specifying \f(CW\*(C`flags\*(C'\fR can further restrict what is allowed and not warned on, as
29236 follows:
29237 .Sp
29238 If \f(CW\*(C`uv\*(C'\fR is a Unicode surrogate code point and \f(CW\*(C`UNICODE_WARN_SURROGATE\*(C'\fR is set,
29239 the function will raise a warning, provided UTF8 warnings are enabled. If
29240 instead \f(CW\*(C`UNICODE_DISALLOW_SURROGATE\*(C'\fR is set, the function will fail and return
29241 NULL. If both flags are set, the function will both warn and return NULL.
29242 .Sp
29243 Similarly, the \f(CW\*(C`UNICODE_WARN_NONCHAR\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_NONCHAR\*(C'\fR flags
29244 affect how the function handles a Unicode non-character.
29245 .Sp
29246 And likewise, the \f(CW\*(C`UNICODE_WARN_SUPER\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR flags
29247 affect the handling of code points that are above the Unicode maximum of
29248 0x10FFFF. Languages other than Perl may not be able to accept files that
29249 contain these.
29250 .Sp
29251 The flag \f(CW\*(C`UNICODE_WARN_ILLEGAL_INTERCHANGE\*(C'\fR selects all three of
29252 the above WARN flags; and \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR selects all
29253 three DISALLOW flags. \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR restricts the
29254 allowed inputs to the strict UTF\-8 traditionally defined by Unicode.
29255 Similarly, \f(CW\*(C`UNICODE_WARN_ILLEGAL_C9_INTERCHANGE\*(C'\fR and
29256 \&\f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR are shortcuts to select the
29257 above-Unicode and surrogate flags, but not the non-character ones, as
29258 defined in
29259 Unicode Corrigendum #9 <https://www.unicode.org/versions/corrigendum9.html>.
29260 See "Noncharacter code points" in perlunicode.
29261 .Sp
29262 Extremely high code points were never specified in any standard, and require an
29263 extension to UTF\-8 to express, which Perl does. It is likely that programs
29264 written in something other than Perl would not be able to read files that
29265 contain these; nor would Perl understand files written by something that uses a
29266 different extension. For these reasons, there is a separate set of flags that
29267 can warn and/or disallow these extremely high code points, even if other
29268 above-Unicode ones are accepted. They are the \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR
29269 and \f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR flags. For more information see
29270 \&\f(CW"UTF8_GOT_PERL_EXTENDED"\fR. Of course \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR will
29271 treat all above-Unicode code points, including these, as malformations. (Note
29272 that the Unicode standard considers anything above 0x10FFFF to be illegal, but
29273 there are standards predating it that allow up to 0x7FFF_FFFF (2**31 \-1))
29274 .Sp
29275 A somewhat misleadingly named synonym for \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR is
29276 retained for backward compatibility: \f(CW\*(C`UNICODE_WARN_ABOVE_31_BIT\*(C'\fR. Similarly,
29277 \&\f(CW\*(C`UNICODE_DISALLOW_ABOVE_31_BIT\*(C'\fR is usable instead of the more accurately named
29278 \&\f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR. The names are misleading because on EBCDIC
29279 platforms,these flags can apply to code points that actually do fit in 31 bits.
29280 The new names accurately describe the situation in all cases.
29281 .RS 4
29282 .Sp
29283 .Vb 1
29284 \& U8 * uvchr_to_utf8_flags(U8 *d, UV uv, UV flags)
29285 .Ve
29286 .RE
29287 .RS 4
29288 .RE
29289 .ie n .IP """uvchr_to_utf8_flags_msgs""" 4
29290 .el .IP \f(CWuvchr_to_utf8_flags_msgs\fR 4
29291 .IX Xref "uvchr_to_utf8_flags_msgs"
29292 .IX Item "uvchr_to_utf8_flags_msgs"
29293 THIS FUNCTION SHOULD BE USED IN ONLY VERY SPECIALIZED CIRCUMSTANCES.
29294 .Sp
29295 Most code should use \f(CW\*(C`"uvchr_to_utf8_flags"()\*(C'\fR rather than call this directly.
29296 .Sp
29297 This function is for code that wants any warning and/or error messages to be
29298 returned to the caller rather than be displayed. All messages that would have
29299 been displayed if all lexical warnings are enabled will be returned.
29300 .Sp
29301 It is just like \f(CW"uvchr_to_utf8_flags"\fR but it takes an extra parameter
29302 placed after all the others, \f(CW\*(C`msgs\*(C'\fR. If this parameter is 0, this function
29303 behaves identically to \f(CW"uvchr_to_utf8_flags"\fR. Otherwise, \f(CW\*(C`msgs\*(C'\fR should
29304 be a pointer to an \f(CW\*(C`HV *\*(C'\fR variable, in which this function creates a new HV to
29305 contain any appropriate messages. The hash has three key-value pairs, as
29306 follows:
29307 .RS 4
29308 .ie n .IP """text""" 4
29309 .el .IP \f(CWtext\fR 4
29310 .IX Item "text"
29311 The text of the message as a \f(CW\*(C`SVpv\*(C'\fR.
29312 .ie n .IP """warn_categories""" 4
29313 .el .IP \f(CWwarn_categories\fR 4
29314 .IX Item "warn_categories"
29315 The warning category (or categories) packed into a \f(CW\*(C`SVuv\*(C'\fR.
29316 .ie n .IP """flag""" 4
29317 .el .IP \f(CWflag\fR 4
29318 .IX Item "flag"
29319 A single flag bit associated with this message, in a \f(CW\*(C`SVuv\*(C'\fR.
29320 The bit corresponds to some bit in the \f(CW*errors\fR return value,
29321 such as \f(CW\*(C`UNICODE_GOT_SURROGATE\*(C'\fR.
29322 .RE
29323 .RS 4
29324 .Sp
29325 It's important to note that specifying this parameter as non-null will cause
29326 any warnings this function would otherwise generate to be suppressed, and
29327 instead be placed in \f(CW*msgs\fR. The caller can check the lexical warnings state
29328 (or not) when choosing what to do with the returned messages.
29329 .Sp
29330 The caller, of course, is responsible for freeing any returned HV.
29331 .Sp
29332 .Vb 1
29333 \& U8 * uvchr_to_utf8_flags_msgs(U8 *d, UV uv, UV flags, HV **msgs)
29334 .Ve
29335 .RE
29336 .RS 4
29337 .RE
29338 .ie n .IP """uvchr_to_utf8""" 4
29339 .el .IP \f(CWuvchr_to_utf8\fR 4
29340 .IX Xref "uvchr_to_utf8"
29341 .IX Item "uvchr_to_utf8"
29342 Adds the UTF\-8 representation of the native code point \f(CW\*(C`uv\*(C'\fR to the end
29343 of the string \f(CW\*(C`d\*(C'\fR; \f(CW\*(C`d\*(C'\fR should have at least \f(CW\*(C`UVCHR_SKIP(uv)+1\*(C'\fR (up to
29344 \&\f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR) free bytes available. The return value is the pointer to
29345 the byte after the end of the new character. In other words,
29346 .Sp
29347 .Vb 1
29348 \& d = uvchr_to_utf8(d, uv);
29349 .Ve
29350 .Sp
29351 is the recommended wide native character-aware way of saying
29352 .Sp
29353 .Vb 1
29354 \& *(d++) = uv;
29355 .Ve
29356 .Sp
29357 This function accepts any code point from 0..\f(CW\*(C`IV_MAX\*(C'\fR as input.
29358 \&\f(CW\*(C`IV_MAX\*(C'\fR is typically 0x7FFF_FFFF in a 32\-bit word.
29359 .Sp
29360 It is possible to forbid or warn on non-Unicode code points, or those that may
29361 be problematic by using "uvchr_to_utf8_flags".
29362 .RS 4
29363 .Sp
29364 .Vb 1
29365 \& U8 * uvchr_to_utf8(U8 *d, UV uv)
29366 .Ve
29367 .RE
29368 .RS 4
29369 .RE
29370 .SH "Utility Functions"
29371 .IX Header "Utility Functions"
29372 .ie n .IP """C_ARRAY_END""" 4
29373 .el .IP \f(CWC_ARRAY_END\fR 4
29374 .IX Xref "C_ARRAY_END"
29375 .IX Item "C_ARRAY_END"
29376 Returns a pointer to one element past the final element of the input C array.
29377 .RS 4
29378 .Sp
29379 .Vb 1
29380 \& void * C_ARRAY_END(void *a)
29381 .Ve
29382 .RE
29383 .RS 4
29384 .RE
29385 .ie n .IP """C_ARRAY_LENGTH""" 4
29386 .el .IP \f(CWC_ARRAY_LENGTH\fR 4
29387 .IX Xref "C_ARRAY_LENGTH"
29388 .IX Item "C_ARRAY_LENGTH"
29389 Returns the number of elements in the input C array (so you want your
29390 zero-based indices to be less than but not equal to).
29391 .RS 4
29392 .Sp
29393 .Vb 1
29394 \& STRLEN C_ARRAY_LENGTH(void *a)
29395 .Ve
29396 .RE
29397 .RS 4
29398 .RE
29399 .ie n .IP """getcwd_sv""" 4
29400 .el .IP \f(CWgetcwd_sv\fR 4
29401 .IX Xref "getcwd_sv"
29402 .IX Item "getcwd_sv"
29403 Fill \f(CW\*(C`sv\*(C'\fR with current working directory
29404 .RS 4
29405 .Sp
29406 .Vb 1
29407 \& int getcwd_sv(SV *sv)
29408 .Ve
29409 .RE
29410 .RS 4
29411 .RE
29412 .ie n .IP """IN_PERL_COMPILETIME""" 4
29413 .el .IP \f(CWIN_PERL_COMPILETIME\fR 4
29414 .IX Xref "IN_PERL_COMPILETIME"
29415 .IX Item "IN_PERL_COMPILETIME"
29416 Returns 1 if this macro is being called during the compilation phase of the
29417 program; otherwise 0;
29418 .RS 4
29419 .Sp
29420 .Vb 1
29421 \& bool IN_PERL_COMPILETIME
29422 .Ve
29423 .RE
29424 .RS 4
29425 .RE
29426 .ie n .IP """IN_PERL_RUNTIME""" 4
29427 .el .IP \f(CWIN_PERL_RUNTIME\fR 4
29428 .IX Xref "IN_PERL_RUNTIME"
29429 .IX Item "IN_PERL_RUNTIME"
29430 Returns 1 if this macro is being called during the execution phase of the
29431 program; otherwise 0;
29432 .RS 4
29433 .Sp
29434 .Vb 1
29435 \& bool IN_PERL_RUNTIME
29436 .Ve
29437 .RE
29438 .RS 4
29439 .RE
29440 .ie n .IP """IS_SAFE_SYSCALL""" 4
29441 .el .IP \f(CWIS_SAFE_SYSCALL\fR 4
29442 .IX Xref "IS_SAFE_SYSCALL"
29443 .IX Item "IS_SAFE_SYSCALL"
29444 Same as "is_safe_syscall".
29445 .RS 4
29446 .Sp
29447 .Vb 2
29448 \& bool IS_SAFE_SYSCALL(NN const char *pv, STRLEN len,
29449 \& NN const char *what, NN const char *op_name)
29450 .Ve
29451 .RE
29452 .RS 4
29453 .RE
29454 .ie n .IP """is_safe_syscall""" 4
29455 .el .IP \f(CWis_safe_syscall\fR 4
29456 .IX Xref "is_safe_syscall"
29457 .IX Item "is_safe_syscall"
29458 Test that the given \f(CW\*(C`pv\*(C'\fR (with length \f(CW\*(C`len\*(C'\fR) doesn't contain any internal
29459 \&\f(CW\*(C`NUL\*(C'\fR characters.
29460 If it does, set \f(CW\*(C`errno\*(C'\fR to \f(CW\*(C`ENOENT\*(C'\fR, optionally warn using the \f(CW\*(C`syscalls\*(C'\fR
29461 category, and return FALSE.
29462 .Sp
29463 Return TRUE if the name is safe.
29464 .Sp
29465 \&\f(CW\*(C`what\*(C'\fR and \f(CW\*(C`op_name\*(C'\fR are used in any warning.
29466 .Sp
29467 Used by the \f(CWIS_SAFE_SYSCALL()\fR macro.
29468 .RS 4
29469 .Sp
29470 .Vb 2
29471 \& bool is_safe_syscall(const char *pv, STRLEN len,
29472 \& const char *what, const char *op_name)
29473 .Ve
29474 .RE
29475 .RS 4
29476 .RE
29477 .ie n .IP """my_setenv""" 4
29478 .el .IP \f(CWmy_setenv\fR 4
29479 .IX Xref "my_setenv"
29480 .IX Item "my_setenv"
29481 A wrapper for the C library \fBsetenv\fR\|(3). Don't use the latter, as the perl
29482 version has desirable safeguards
29483 .RS 4
29484 .Sp
29485 .Vb 1
29486 \& void my_setenv(const char *nam, const char *val)
29487 .Ve
29488 .RE
29489 .RS 4
29490 .RE
29491 .ie n .IP """newPADxVOP""" 4
29492 .el .IP \f(CWnewPADxVOP\fR 4
29493 .IX Xref "newPADxVOP"
29494 .IX Item "newPADxVOP"
29495 Constructs, checks and returns an op containing a pad offset. \f(CW\*(C`type\*(C'\fR is
29496 the opcode, which should be one of \f(CW\*(C`OP_PADSV\*(C'\fR, \f(CW\*(C`OP_PADAV\*(C'\fR, \f(CW\*(C`OP_PADHV\*(C'\fR
29497 or \f(CW\*(C`OP_PADCV\*(C'\fR. The returned op will have the \f(CW\*(C`op_targ\*(C'\fR field set by
29498 the \f(CW\*(C`padix\*(C'\fR argument.
29499 .Sp
29500 This is convenient when constructing a large optree in nested function
29501 calls, as it avoids needing to store the pad op directly to set the
29502 \&\f(CW\*(C`op_targ\*(C'\fR field as a side-effect. For example
29503 .Sp
29504 .Vb 2
29505 \& o = op_append_elem(OP_LINESEQ, o,
29506 \& newPADxVOP(OP_PADSV, 0, padix));
29507 .Ve
29508 .RS 4
29509 .Sp
29510 .Vb 1
29511 \& OP * newPADxVOP(I32 type, I32 flags, PADOFFSET padix)
29512 .Ve
29513 .RE
29514 .RS 4
29515 .RE
29516 .ie n .IP """phase_name""" 4
29517 .el .IP \f(CWphase_name\fR 4
29518 .IX Xref "phase_name"
29519 .IX Item "phase_name"
29520 Returns the given phase's name as a NUL-terminated string.
29521 .Sp
29522 For example, to print a stack trace that includes the current
29523 interpreter phase you might do:
29524 .Sp
29525 .Vb 2
29526 \& const char* phase_name = phase_name(PL_phase);
29527 \& mess("This is weird. (Perl phase: %s)", phase_name);
29528 .Ve
29529 .RS 4
29530 .Sp
29531 .Vb 1
29532 \& const char * const phase_name(enum perl_phase)
29533 .Ve
29534 .RE
29535 .RS 4
29536 .RE
29537 .ie n .IP """Poison""" 4
29538 .el .IP \f(CWPoison\fR 4
29539 .IX Xref "Poison"
29540 .IX Item "Poison"
29541 PoisonWith(0xEF) for catching access to freed memory.
29542 .RS 4
29543 .Sp
29544 .Vb 1
29545 \& void Poison(void* dest, int nitems, type)
29546 .Ve
29547 .RE
29548 .RS 4
29549 .RE
29550 .ie n .IP """PoisonFree""" 4
29551 .el .IP \f(CWPoisonFree\fR 4
29552 .IX Xref "PoisonFree"
29553 .IX Item "PoisonFree"
29554 PoisonWith(0xEF) for catching access to freed memory.
29555 .RS 4
29556 .Sp
29557 .Vb 1
29558 \& void PoisonFree(void* dest, int nitems, type)
29559 .Ve
29560 .RE
29561 .RS 4
29562 .RE
29563 .ie n .IP """PoisonNew""" 4
29564 .el .IP \f(CWPoisonNew\fR 4
29565 .IX Xref "PoisonNew"
29566 .IX Item "PoisonNew"
29567 PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
29568 .RS 4
29569 .Sp
29570 .Vb 1
29571 \& void PoisonNew(void* dest, int nitems, type)
29572 .Ve
29573 .RE
29574 .RS 4
29575 .RE
29576 .ie n .IP """PoisonWith""" 4
29577 .el .IP \f(CWPoisonWith\fR 4
29578 .IX Xref "PoisonWith"
29579 .IX Item "PoisonWith"
29580 Fill up memory with a byte pattern (a byte repeated over and over
29581 again) that hopefully catches attempts to access uninitialized memory.
29582 .RS 4
29583 .Sp
29584 .Vb 1
29585 \& void PoisonWith(void* dest, int nitems, type, U8 byte)
29586 .Ve
29587 .RE
29588 .RS 4
29589 .RE
29590 .ie n .IP """StructCopy""" 4
29591 .el .IP \f(CWStructCopy\fR 4
29592 .IX Xref "StructCopy"
29593 .IX Item "StructCopy"
29594 This is an architecture-independent macro that does a shallow copy of one
29595 structure to another.
29596 .RS 4
29597 .Sp
29598 .Vb 1
29599 \& void StructCopy(type *src, type *dest, type)
29600 .Ve
29601 .RE
29602 .RS 4
29603 .RE
29604 .ie n .IP """sv_destroyable""" 4
29605 .el .IP \f(CWsv_destroyable\fR 4
29606 .IX Xref "sv_destroyable"
29607 .IX Item "sv_destroyable"
29608 Dummy routine which reports that object can be destroyed when there is no
29609 sharing module present. It ignores its single SV argument, and returns
29610 \&'true'. Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it
29611 could potentially warn under some level of strict-ness.
29612 .RS 4
29613 .Sp
29614 .Vb 1
29615 \& bool sv_destroyable(SV *sv)
29616 .Ve
29617 .RE
29618 .RS 4
29619 .RE
29620 .ie n .IP """sv_nosharing""" 4
29621 .el .IP \f(CWsv_nosharing\fR 4
29622 .IX Xref "sv_nosharing"
29623 .IX Item "sv_nosharing"
29624 Dummy routine which "shares" an SV when there is no sharing module present.
29625 Or "locks" it. Or "unlocks" it. In other
29626 words, ignores its single SV argument.
29627 Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
29628 potentially warn under some level of strict-ness.
29629 .RS 4
29630 .Sp
29631 .Vb 1
29632 \& void sv_nosharing(SV *sv)
29633 .Ve
29634 .RE
29635 .RS 4
29636 .RE
29637 .SH Versioning
29638 .IX Header "Versioning"
29639 .ie n .IP """new_version""" 4
29640 .el .IP \f(CWnew_version\fR 4
29641 .IX Xref "new_version"
29642 .IX Item "new_version"
29643 Returns a new version object based on the passed in SV:
29644 .Sp
29645 .Vb 1
29646 \& SV *sv = new_version(SV *ver);
29647 .Ve
29648 .Sp
29649 Does not alter the passed in ver SV. See "upg_version" if you
29650 want to upgrade the SV.
29651 .RS 4
29652 .Sp
29653 .Vb 1
29654 \& SV * new_version(SV *ver)
29655 .Ve
29656 .RE
29657 .RS 4
29658 .RE
29659 .ie n .IP """PERL_REVISION""" 4
29660 .el .IP \f(CWPERL_REVISION\fR 4
29661 .IX Xref "PERL_REVISION"
29662 .IX Item "PERL_REVISION"
29663 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_REVISION\*(C'\fR
29664 from a future release of Perl. Do not use it for
29665 new code; remove it from existing code.
29666 .Sp
29667 The major number component of the perl interpreter currently being compiled or
29668 executing. This has been \f(CW5\fR from 1993 into 2020.
29669 .Sp
29670 Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR.
29671 .ie n .IP """PERL_SUBVERSION""" 4
29672 .el .IP \f(CWPERL_SUBVERSION\fR 4
29673 .IX Xref "PERL_SUBVERSION"
29674 .IX Item "PERL_SUBVERSION"
29675 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_SUBVERSION\*(C'\fR
29676 from a future release of Perl. Do not use it for
29677 new code; remove it from existing code.
29678 .Sp
29679 The micro number component of the perl interpreter currently being compiled or
29680 executing. In stable releases this gives the dot release number for
29681 maintenance updates. In development releases this gives a tag for a snapshot
29682 of the status at various points in the development cycle.
29683 .Sp
29684 Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR.
29685 .ie n .IP """PERL_VERSION""" 4
29686 .el .IP \f(CWPERL_VERSION\fR 4
29687 .IX Xref "PERL_VERSION"
29688 .IX Item "PERL_VERSION"
29689 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_VERSION\*(C'\fR
29690 from a future release of Perl. Do not use it for
29691 new code; remove it from existing code.
29692 .Sp
29693 The minor number component of the perl interpreter currently being compiled or
29694 executing. Between 1993 into 2020, this has ranged from 0 to 33.
29695 .Sp
29696 Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR.
29697 .ie n .IP """PERL_VERSION_EQ""" 4
29698 .el .IP \f(CWPERL_VERSION_EQ\fR 4
29699 .IX Item "PERL_VERSION_EQ"
29700 .PD 0
29701 .ie n .IP """PERL_VERSION_GE""" 4
29702 .el .IP \f(CWPERL_VERSION_GE\fR 4
29703 .IX Item "PERL_VERSION_GE"
29704 .ie n .IP """PERL_VERSION_GT""" 4
29705 .el .IP \f(CWPERL_VERSION_GT\fR 4
29706 .IX Item "PERL_VERSION_GT"
29707 .ie n .IP """PERL_VERSION_LE""" 4
29708 .el .IP \f(CWPERL_VERSION_LE\fR 4
29709 .IX Item "PERL_VERSION_LE"
29710 .ie n .IP """PERL_VERSION_LT""" 4
29711 .el .IP \f(CWPERL_VERSION_LT\fR 4
29712 .IX Item "PERL_VERSION_LT"
29713 .ie n .IP """PERL_VERSION_NE""" 4
29714 .el .IP \f(CWPERL_VERSION_NE\fR 4
29715 .IX Xref "PERL_VERSION_EQ PERL_VERSION_GE PERL_VERSION_GT PERL_VERSION_LE PERL_VERSION_LT PERL_VERSION_NE"
29716 .IX Item "PERL_VERSION_NE"
29717 .PD
29718 Returns whether or not the perl currently being compiled has the specified
29719 relationship to the perl given by the parameters. For example,
29720 .Sp
29721 .Vb 5
29722 \& #if PERL_VERSION_GT(5,24,2)
29723 \& code that will only be compiled on perls after v5.24.2
29724 \& #else
29725 \& fallback code
29726 \& #endif
29727 .Ve
29728 .Sp
29729 Note that this is usable in making compile-time decisions
29730 .Sp
29731 You may use the special value '*' for the final number to mean ALL possible
29732 values for it. Thus,
29733 .Sp
29734 .Vb 1
29735 \& #if PERL_VERSION_EQ(5,31,\*(Aq*\*(Aq)
29736 .Ve
29737 .Sp
29738 means all perls in the 5.31 series. And
29739 .Sp
29740 .Vb 1
29741 \& #if PERL_VERSION_NE(5,24,\*(Aq*\*(Aq)
29742 .Ve
29743 .Sp
29744 means all perls EXCEPT 5.24 ones. And
29745 .Sp
29746 .Vb 1
29747 \& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq)
29748 .Ve
29749 .Sp
29750 is effectively
29751 .Sp
29752 .Vb 1
29753 \& #if PERL_VERSION_LT(5,10,0)
29754 .Ve
29755 .Sp
29756 This means you don't have to think so much when converting from the existing
29757 deprecated \f(CW\*(C`PERL_VERSION\*(C'\fR to using this macro:
29758 .Sp
29759 .Vb 1
29760 \& #if PERL_VERSION <= 9
29761 .Ve
29762 .Sp
29763 becomes
29764 .Sp
29765 .Vb 1
29766 \& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq)
29767 .Ve
29768 .RS 4
29769 .Sp
29770 .Vb 2
29771 \& bool PERL_VERSION_EQ(const U8 major, const U8 minor,
29772 \& const U8 patch)
29773 .Ve
29774 .RE
29775 .RS 4
29776 .RE
29777 .ie n .IP """prescan_version""" 4
29778 .el .IP \f(CWprescan_version\fR 4
29779 .IX Xref "prescan_version"
29780 .IX Item "prescan_version"
29781 Validate that a given string can be parsed as a version object, but doesn't
29782 actually perform the parsing. Can use either strict or lax validation rules.
29783 Can optionally set a number of hint variables to save the parsing code
29784 some time when tokenizing.
29785 .RS 4
29786 .Sp
29787 .Vb 4
29788 \& const char * prescan_version(const char *s, bool strict,
29789 \& const char **errstr, bool *sqv,
29790 \& int *ssaw_decimal, int *swidth,
29791 \& bool *salpha)
29792 .Ve
29793 .RE
29794 .RS 4
29795 .RE
29796 .ie n .IP """scan_version""" 4
29797 .el .IP \f(CWscan_version\fR 4
29798 .IX Xref "scan_version"
29799 .IX Item "scan_version"
29800 Returns a pointer to the next character after the parsed
29801 version string, as well as upgrading the passed in SV to
29802 an RV.
29803 .Sp
29804 Function must be called with an already existing SV like
29805 .Sp
29806 .Vb 2
29807 \& sv = newSV(0);
29808 \& s = scan_version(s, SV *sv, bool qv);
29809 .Ve
29810 .Sp
29811 Performs some preprocessing to the string to ensure that
29812 it has the correct characteristics of a version. Flags the
29813 object if it contains an underscore (which denotes this
29814 is an alpha version). The boolean qv denotes that the version
29815 should be interpreted as if it had multiple decimals, even if
29816 it doesn't.
29817 .RS 4
29818 .Sp
29819 .Vb 1
29820 \& const char * scan_version(const char *s, SV *rv, bool qv)
29821 .Ve
29822 .RE
29823 .RS 4
29824 .RE
29825 .ie n .IP """upg_version""" 4
29826 .el .IP \f(CWupg_version\fR 4
29827 .IX Xref "upg_version"
29828 .IX Item "upg_version"
29829 In-place upgrade of the supplied SV to a version object.
29830 .Sp
29831 .Vb 1
29832 \& SV *sv = upg_version(SV *sv, bool qv);
29833 .Ve
29834 .Sp
29835 Returns a pointer to the upgraded SV. Set the boolean qv if you want
29836 to force this SV to be interpreted as an "extended" version.
29837 .RS 4
29838 .Sp
29839 .Vb 1
29840 \& SV * upg_version(SV *ver, bool qv)
29841 .Ve
29842 .RE
29843 .RS 4
29844 .RE
29845 .ie n .IP """vcmp""" 4
29846 .el .IP \f(CWvcmp\fR 4
29847 .IX Xref "vcmp"
29848 .IX Item "vcmp"
29849 Version object aware cmp. Both operands must already have been
29850 converted into version objects.
29851 .RS 4
29852 .Sp
29853 .Vb 1
29854 \& int vcmp(SV *lhv, SV *rhv)
29855 .Ve
29856 .RE
29857 .RS 4
29858 .RE
29859 .ie n .IP """vnormal""" 4
29860 .el .IP \f(CWvnormal\fR 4
29861 .IX Xref "vnormal"
29862 .IX Item "vnormal"
29863 Accepts a version object and returns the normalized string
29864 representation. Call like:
29865 .Sp
29866 .Vb 1
29867 \& sv = vnormal(rv);
29868 .Ve
29869 .Sp
29870 NOTE: you can pass either the object directly or the SV
29871 contained within the RV.
29872 .Sp
29873 The SV returned has a refcount of 1.
29874 .RS 4
29875 .Sp
29876 .Vb 1
29877 \& SV * vnormal(SV *vs)
29878 .Ve
29879 .RE
29880 .RS 4
29881 .RE
29882 .ie n .IP """vnumify""" 4
29883 .el .IP \f(CWvnumify\fR 4
29884 .IX Xref "vnumify"
29885 .IX Item "vnumify"
29886 Accepts a version object and returns the normalized floating
29887 point representation. Call like:
29888 .Sp
29889 .Vb 1
29890 \& sv = vnumify(rv);
29891 .Ve
29892 .Sp
29893 NOTE: you can pass either the object directly or the SV
29894 contained within the RV.
29895 .Sp
29896 The SV returned has a refcount of 1.
29897 .RS 4
29898 .Sp
29899 .Vb 1
29900 \& SV * vnumify(SV *vs)
29901 .Ve
29902 .RE
29903 .RS 4
29904 .RE
29905 .ie n .IP """vstringify""" 4
29906 .el .IP \f(CWvstringify\fR 4
29907 .IX Xref "vstringify"
29908 .IX Item "vstringify"
29909 In order to maintain maximum compatibility with earlier versions
29910 of Perl, this function will return either the floating point
29911 notation or the multiple dotted notation, depending on whether
29912 the original version contained 1 or more dots, respectively.
29913 .Sp
29914 The SV returned has a refcount of 1.
29915 .RS 4
29916 .Sp
29917 .Vb 1
29918 \& SV * vstringify(SV *vs)
29919 .Ve
29920 .RE
29921 .RS 4
29922 .RE
29923 .ie n .IP """vverify""" 4
29924 .el .IP \f(CWvverify\fR 4
29925 .IX Xref "vverify"
29926 .IX Item "vverify"
29927 Validates that the SV contains valid internal structure for a version object.
29928 It may be passed either the version object (RV) or the hash itself (HV). If
29929 the structure is valid, it returns the HV. If the structure is invalid,
29930 it returns NULL.
29931 .Sp
29932 .Vb 1
29933 \& SV *hv = vverify(sv);
29934 .Ve
29935 .Sp
29936 Note that it only confirms the bare minimum structure (so as not to get
29937 confused by derived classes which may contain additional hash entries):
29938 .RS 4
29939 .IP \(bu 4
29940 The SV is an HV or a reference to an HV
29941 .IP \(bu 4
29942 The hash contains a "version" key
29943 .IP \(bu 4
29944 The "version" key has a reference to an AV as its value
29945 .RE
29946 .RS 4
29947 .Sp
29948 .Vb 1
29949 \& SV * vverify(SV *vs)
29950 .Ve
29951 .RE
29952 .RS 4
29953 .RE
29954 .SH "Warning and Dieing"
29955 .IX Xref "WARN_ALL WARN_AMBIGUOUS WARN_BAREWORD WARN_CLOSED WARN_CLOSURE WARN_DEBUGGING WARN_DEPRECATED WARN_DEPRECATED__APOSTROPHE_AS_PACKAGE_SEPARATOR WARN_DEPRECATED__DELIMITER_WILL_BE_PAIRED WARN_DEPRECATED__DOT_IN_INC WARN_DEPRECATED__GOTO_CONSTRUCT WARN_DEPRECATED__MISSING_IMPORT_CALLED_WITH_ARGS WARN_DEPRECATED__SMARTMATCH WARN_DEPRECATED__SUBSEQUENT_USE_VERSION WARN_DEPRECATED__UNICODE_PROPERTY_NAME WARN_DEPRECATED__VERSION_DOWNGRADE WARN_DIGIT WARN_EXEC WARN_EXITING WARN_EXPERIMENTAL WARN_EXPERIMENTAL__ARGS_ARRAY_WITH_SIGNATURES WARN_EXPERIMENTAL__BUILTIN WARN_EXPERIMENTAL__CLASS WARN_EXPERIMENTAL__DECLARED_REFS WARN_EXPERIMENTAL__DEFER WARN_EXPERIMENTAL__EXTRA_PAIRED_DELIMITERS WARN_EXPERIMENTAL__PRIVATE_USE WARN_EXPERIMENTAL__REFALIASING WARN_EXPERIMENTAL__REGEX_SETS WARN_EXPERIMENTAL__RE_STRICT WARN_EXPERIMENTAL__TRY WARN_EXPERIMENTAL__UNIPROP_WILDCARDS WARN_EXPERIMENTAL__VLB WARN_GLOB WARN_ILLEGALPROTO WARN_IMPRECISION WARN_INPLACE WARN_INTERNAL WARN_IO WARN_LAYER WARN_LOCALE WARN_MALLOC WARN_MISC WARN_MISSING WARN_NEWLINE WARN_NONCHAR WARN_NON_UNICODE WARN_NUMERIC WARN_ONCE WARN_OVERFLOW WARN_PACK WARN_PARENTHESIS WARN_PIPE WARN_PORTABLE WARN_PRECEDENCE WARN_PRINTF WARN_PROTOTYPE WARN_QW WARN_RECURSION WARN_REDEFINE WARN_REDUNDANT WARN_REGEXP WARN_RESERVED WARN_SCALAR WARN_SEMICOLON WARN_SEVERE WARN_SHADOW WARN_SIGNAL WARN_SUBSTR WARN_SURROGATE WARN_SYNTAX WARN_SYSCALLS WARN_TAINT WARN_THREADS WARN_UNINITIALIZED WARN_UNOPENED WARN_UNPACK WARN_UNTIE WARN_UTF8 WARN_VOID"
29956 .IX Header "Warning and Dieing"
29957 In all these calls, the \f(CW\*(C`U32 w\fR\f(CIn\fR\f(CW\*(C'\fR parameters are warning category
29958 constants. You can see the ones currently available in
29959 "Category Hierarchy" in warnings, just capitalize all letters in the names
29960 and prefix them by \f(CW\*(C`WARN_\*(C'\fR. So, for example, the category \f(CW\*(C`void\*(C'\fR used in a
29961 perl program becomes \f(CW\*(C`WARN_VOID\*(C'\fR when used in XS code and passed to one of
29962 the calls below.
29963 .ie n .IP """ckWARN""" 4
29964 .el .IP \f(CWckWARN\fR 4
29965 .IX Item "ckWARN"
29966 .PD 0
29967 .ie n .IP """ckWARN2""" 4
29968 .el .IP \f(CWckWARN2\fR 4
29969 .IX Item "ckWARN2"
29970 .ie n .IP """ckWARN3""" 4
29971 .el .IP \f(CWckWARN3\fR 4
29972 .IX Item "ckWARN3"
29973 .ie n .IP """ckWARN4""" 4
29974 .el .IP \f(CWckWARN4\fR 4
29975 .IX Xref "ckWARN ckWARN2 ckWARN3 ckWARN4"
29976 .IX Item "ckWARN4"
29977 .PD
29978 These return a boolean as to whether or not warnings are enabled for any of
29979 the warning category(ies) parameters: \f(CW\*(C`w\*(C'\fR, \f(CW\*(C`w1\*(C'\fR, ....
29980 .Sp
29981 Should any of the categories by default be enabled even if not within the
29982 scope of \f(CW\*(C`use\ warnings\*(C'\fR, instead use the \f(CW"ckWARN_d"\fR macros.
29983 .Sp
29984 The categories must be completely independent, one may not be subclassed from
29985 the other.
29986 .RS 4
29987 .Sp
29988 .Vb 4
29989 \& bool ckWARN (U32 w)
29990 \& bool ckWARN2(U32 w1, U32 w2)
29991 \& bool ckWARN3(U32 w1, U32 w2, U32 w3)
29992 \& bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
29993 .Ve
29994 .RE
29995 .RS 4
29996 .RE
29997 .ie n .IP """ckWARN_d""" 4
29998 .el .IP \f(CWckWARN_d\fR 4
29999 .IX Item "ckWARN_d"
30000 .PD 0
30001 .ie n .IP """ckWARN2_d""" 4
30002 .el .IP \f(CWckWARN2_d\fR 4
30003 .IX Item "ckWARN2_d"
30004 .ie n .IP """ckWARN3_d""" 4
30005 .el .IP \f(CWckWARN3_d\fR 4
30006 .IX Item "ckWARN3_d"
30007 .ie n .IP """ckWARN4_d""" 4
30008 .el .IP \f(CWckWARN4_d\fR 4
30009 .IX Xref "ckWARN_d ckWARN2_d ckWARN3_d ckWARN4_d"
30010 .IX Item "ckWARN4_d"
30011 .PD
30012 Like \f(CW"ckWARN"\fR, but for use if and only if the warning category(ies) is by
30013 default enabled even if not within the scope of \f(CW\*(C`use\ warnings\*(C'\fR.
30014 .RS 4
30015 .Sp
30016 .Vb 4
30017 \& bool ckWARN_d (U32 w)
30018 \& bool ckWARN2_d(U32 w1, U32 w2)
30019 \& bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
30020 \& bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
30021 .Ve
30022 .RE
30023 .RS 4
30024 .RE
30025 .ie n .IP """ck_warner""" 4
30026 .el .IP \f(CWck_warner\fR 4
30027 .IX Item "ck_warner"
30028 .PD 0
30029 .ie n .IP """ck_warner_d""" 4
30030 .el .IP \f(CWck_warner_d\fR 4
30031 .IX Xref "ck_warner ck_warner_d"
30032 .IX Item "ck_warner_d"
30033 .PD
30034 If none of the warning categories given by \f(CW\*(C`err\*(C'\fR are enabled, do nothing;
30035 otherwise call \f(CW"warner"\fR or \f(CW"warner_nocontext"\fR with the passed-in
30036 parameters;.
30037 .Sp
30038 \&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR,
30039 \&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
30040 categories.
30041 .Sp
30042 The two forms differ only in that \f(CW\*(C`ck_warner_d\*(C'\fR should be used if warnings for
30043 any of the categories are by default enabled.
30044 .Sp
30045 NOTE: \f(CW\*(C`ck_warner\*(C'\fR must be explicitly called as
30046 \&\f(CW\*(C`Perl_ck_warner\*(C'\fR
30047 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
30048 .Sp
30049 NOTE: \f(CW\*(C`ck_warner_d\*(C'\fR must be explicitly called as
30050 \&\f(CW\*(C`Perl_ck_warner_d\*(C'\fR
30051 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
30052 .RS 4
30053 .Sp
30054 .Vb 1
30055 \& void Perl_ck_warner(pTHX_ U32 err, const char *pat, ...)
30056 .Ve
30057 .RE
30058 .RS 4
30059 .RE
30060 .ie n .IP """CLEAR_ERRSV""" 4
30061 .el .IP \f(CWCLEAR_ERRSV\fR 4
30062 .IX Xref "CLEAR_ERRSV"
30063 .IX Item "CLEAR_ERRSV"
30064 Clear the contents of \f(CW$@\fR, setting it to the empty string.
30065 .Sp
30066 This replaces any read-only SV with a fresh SV and removes any magic.
30067 .RS 4
30068 .Sp
30069 .Vb 1
30070 \& void CLEAR_ERRSV()
30071 .Ve
30072 .RE
30073 .RS 4
30074 .RE
30075 .ie n .IP """croak""" 4
30076 .el .IP \f(CWcroak\fR 4
30077 .IX Item "croak"
30078 .PD 0
30079 .ie n .IP """croak_nocontext""" 4
30080 .el .IP \f(CWcroak_nocontext\fR 4
30081 .IX Xref "croak croak_nocontext"
30082 .IX Item "croak_nocontext"
30083 .PD
30084 These are XS interfaces to Perl's \f(CW\*(C`die\*(C'\fR function.
30085 .Sp
30086 They take a sprintf-style format pattern and argument list, which are used to
30087 generate a string message. If the message does not end with a newline, then it
30088 will be extended with some indication of the current location in the code, as
30089 described for \f(CW"mess_sv"\fR.
30090 .Sp
30091 The error message will be used as an exception, by default
30092 returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
30093 modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, these croak
30094 functions never return normally.
30095 .Sp
30096 For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR
30097 (\f(CW$@\fR) will be used as an error message or object instead of building an
30098 error message from arguments. If you want to throw a non-string object,
30099 or build an error message in an SV yourself, it is preferable to use
30100 the \f(CW"croak_sv"\fR function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR.
30101 .Sp
30102 The two forms differ only in that \f(CW\*(C`croak_nocontext\*(C'\fR does not take a thread
30103 context (\f(CW\*(C`aTHX\*(C'\fR) parameter. It is usually preferred as it takes up fewer
30104 bytes of code than plain \f(CW\*(C`Perl_croak\*(C'\fR, and time is rarely a critical resource
30105 when you are about to throw an exception.
30106 .Sp
30107 NOTE: \f(CW\*(C`croak\*(C'\fR must be explicitly called as
30108 \&\f(CW\*(C`Perl_croak\*(C'\fR
30109 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
30110 .RS 4
30111 .Sp
30112 .Vb 2
30113 \& void Perl_croak (pTHX_ const char *pat, ...)
30114 \& void croak_nocontext(const char *pat, ...)
30115 .Ve
30116 .RE
30117 .RS 4
30118 .RE
30119 .ie n .IP """croak_no_modify""" 4
30120 .el .IP \f(CWcroak_no_modify\fR 4
30121 .IX Xref "croak_no_modify"
30122 .IX Item "croak_no_modify"
30123 This encapsulates a common reason for dying, generating terser object code than
30124 using the generic \f(CW\*(C`Perl_croak\*(C'\fR. It is exactly equivalent to
30125 \&\f(CW\*(C`Perl_croak(aTHX_ "%s", PL_no_modify)\*(C'\fR (which expands to something like
30126 "Modification of a read-only value attempted").
30127 .Sp
30128 Less code used on exception code paths reduces CPU cache pressure.
30129 .RS 4
30130 .Sp
30131 .Vb 1
30132 \& void croak_no_modify()
30133 .Ve
30134 .RE
30135 .RS 4
30136 .RE
30137 .ie n .IP """croak_sv""" 4
30138 .el .IP \f(CWcroak_sv\fR 4
30139 .IX Xref "croak_sv"
30140 .IX Item "croak_sv"
30141 This is an XS interface to Perl's \f(CW\*(C`die\*(C'\fR function.
30142 .Sp
30143 \&\f(CW\*(C`baseex\*(C'\fR is the error message or object. If it is a reference, it
30144 will be used as-is. Otherwise it is used as a string, and if it does
30145 not end with a newline then it will be extended with some indication of
30146 the current location in the code, as described for "mess_sv".
30147 .Sp
30148 The error message or object will be used as an exception, by default
30149 returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
30150 modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, the \f(CW\*(C`croak_sv\*(C'\fR
30151 function never returns normally.
30152 .Sp
30153 To die with a simple string message, the "croak" function may be
30154 more convenient.
30155 .RS 4
30156 .Sp
30157 .Vb 1
30158 \& void croak_sv(SV *baseex)
30159 .Ve
30160 .RE
30161 .RS 4
30162 .RE
30163 .ie n .IP """die""" 4
30164 .el .IP \f(CWdie\fR 4
30165 .IX Item "die"
30166 .PD 0
30167 .ie n .IP """die_nocontext""" 4
30168 .el .IP \f(CWdie_nocontext\fR 4
30169 .IX Xref "die die_nocontext"
30170 .IX Item "die_nocontext"
30171 .PD
30172 These behave the same as "croak", except for the return type.
30173 They should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required.
30174 They never actually return.
30175 .Sp
30176 The two forms differ only in that \f(CW\*(C`die_nocontext\*(C'\fR does not take a thread
30177 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
30178 already have the thread context.
30179 .Sp
30180 NOTE: \f(CW\*(C`die\*(C'\fR must be explicitly called as
30181 \&\f(CW\*(C`Perl_die\*(C'\fR
30182 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
30183 .RS 4
30184 .Sp
30185 .Vb 2
30186 \& OP * Perl_die (pTHX_ const char *pat, ...)
30187 \& OP * die_nocontext(const char *pat, ...)
30188 .Ve
30189 .RE
30190 .RS 4
30191 .RE
30192 .ie n .IP """die_sv""" 4
30193 .el .IP \f(CWdie_sv\fR 4
30194 .IX Xref "die_sv"
30195 .IX Item "die_sv"
30196 This behaves the same as "croak_sv", except for the return type.
30197 It should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required.
30198 The function never actually returns.
30199 .RS 4
30200 .Sp
30201 .Vb 1
30202 \& OP * die_sv(SV *baseex)
30203 .Ve
30204 .RE
30205 .RS 4
30206 .RE
30207 .ie n .IP """ERRSV""" 4
30208 .el .IP \f(CWERRSV\fR 4
30209 .IX Xref "ERRSV"
30210 .IX Item "ERRSV"
30211 Returns the SV for \f(CW$@\fR, creating it if needed.
30212 .RS 4
30213 .Sp
30214 .Vb 1
30215 \& SV * ERRSV
30216 .Ve
30217 .RE
30218 .RS 4
30219 .RE
30220 .ie n .IP """fatal_warner""" 4
30221 .el .IP \f(CWfatal_warner\fR 4
30222 .IX Xref "fatal_warner"
30223 .IX Item "fatal_warner"
30224 Like "warner" except that it acts as if fatal warnings are enabled
30225 for the warning.
30226 .Sp
30227 If called when there are pending compilation errors this function may
30228 return.
30229 .Sp
30230 This is currently used to generate "used only once" fatal warnings
30231 since the COP where the name being reported is no longer the current
30232 COP when the warning is generated and may be useful for similar cases.
30233 .Sp
30234 \&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR,
30235 \&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
30236 categories.
30237 .Sp
30238 NOTE: \f(CW\*(C`fatal_warner\*(C'\fR must be explicitly called as
30239 \&\f(CW\*(C`Perl_fatal_warner\*(C'\fR
30240 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
30241 .RS 4
30242 .Sp
30243 .Vb 1
30244 \& void Perl_fatal_warner(pTHX_ U32 err, const char *pat, ...)
30245 .Ve
30246 .RE
30247 .RS 4
30248 .RE
30249 .ie n .IP """packWARN""" 4
30250 .el .IP \f(CWpackWARN\fR 4
30251 .IX Item "packWARN"
30252 .PD 0
30253 .ie n .IP """packWARN2""" 4
30254 .el .IP \f(CWpackWARN2\fR 4
30255 .IX Item "packWARN2"
30256 .ie n .IP """packWARN3""" 4
30257 .el .IP \f(CWpackWARN3\fR 4
30258 .IX Item "packWARN3"
30259 .ie n .IP """packWARN4""" 4
30260 .el .IP \f(CWpackWARN4\fR 4
30261 .IX Xref "packWARN packWARN2 packWARN3 packWARN4"
30262 .IX Item "packWARN4"
30263 .PD
30264 These macros are used to pack warning categories into a single U32 to pass to
30265 macros and functions that take a warning category parameter. The number of
30266 categories to pack is given by the name, with a corresponding number of
30267 category parameters passed.
30268 .RS 4
30269 .Sp
30270 .Vb 4
30271 \& U32 packWARN (U32 w1)
30272 \& U32 packWARN2(U32 w1, U32 w2)
30273 \& U32 packWARN3(U32 w1, U32 w2, U32 w3)
30274 \& U32 packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
30275 .Ve
30276 .RE
30277 .RS 4
30278 .RE
30279 .ie n .IP """SANE_ERRSV""" 4
30280 .el .IP \f(CWSANE_ERRSV\fR 4
30281 .IX Xref "SANE_ERRSV"
30282 .IX Item "SANE_ERRSV"
30283 Clean up ERRSV so we can safely set it.
30284 .Sp
30285 This replaces any read-only SV with a fresh writable copy and removes
30286 any magic.
30287 .RS 4
30288 .Sp
30289 .Vb 1
30290 \& void SANE_ERRSV()
30291 .Ve
30292 .RE
30293 .RS 4
30294 .RE
30295 .ie n .IP """vcroak""" 4
30296 .el .IP \f(CWvcroak\fR 4
30297 .IX Xref "vcroak"
30298 .IX Item "vcroak"
30299 This is an XS interface to Perl's \f(CW\*(C`die\*(C'\fR function.
30300 .Sp
30301 \&\f(CW\*(C`pat\*(C'\fR and \f(CW\*(C`args\*(C'\fR are a sprintf-style format pattern and encapsulated
30302 argument list. These are used to generate a string message. If the
30303 message does not end with a newline, then it will be extended with
30304 some indication of the current location in the code, as described for
30305 "mess_sv".
30306 .Sp
30307 The error message will be used as an exception, by default
30308 returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
30309 modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, the \f(CW\*(C`croak\*(C'\fR
30310 function never returns normally.
30311 .Sp
30312 For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR
30313 (\f(CW$@\fR) will be used as an error message or object instead of building an
30314 error message from arguments. If you want to throw a non-string object,
30315 or build an error message in an SV yourself, it is preferable to use
30316 the "croak_sv" function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR.
30317 .RS 4
30318 .Sp
30319 .Vb 1
30320 \& void vcroak(const char *pat, va_list *args)
30321 .Ve
30322 .RE
30323 .RS 4
30324 .RE
30325 .ie n .IP """vfatal_warner""" 4
30326 .el .IP \f(CWvfatal_warner\fR 4
30327 .IX Xref "vfatal_warner"
30328 .IX Item "vfatal_warner"
30329 This is like \f(CW"fatal_warner"\fR but \f(CW\*(C`args\*(C'\fR are an encapsulated
30330 argument list.
30331 .RS 4
30332 .Sp
30333 .Vb 1
30334 \& void vfatal_warner(U32 err, const char *pat, va_list *args)
30335 .Ve
30336 .RE
30337 .RS 4
30338 .RE
30339 .ie n .IP """vwarn""" 4
30340 .el .IP \f(CWvwarn\fR 4
30341 .IX Xref "vwarn"
30342 .IX Item "vwarn"
30343 This is an XS interface to Perl's \f(CW\*(C`warn\*(C'\fR function.
30344 .Sp
30345 This is like \f(CW"warn"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated
30346 argument list.
30347 .Sp
30348 Unlike with "vcroak", \f(CW\*(C`pat\*(C'\fR is not permitted to be null.
30349 .RS 4
30350 .Sp
30351 .Vb 1
30352 \& void vwarn(const char *pat, va_list *args)
30353 .Ve
30354 .RE
30355 .RS 4
30356 .RE
30357 .ie n .IP """vwarner""" 4
30358 .el .IP \f(CWvwarner\fR 4
30359 .IX Xref "vwarner"
30360 .IX Item "vwarner"
30361 This is like \f(CW"warner"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated argument list.
30362 .RS 4
30363 .Sp
30364 .Vb 1
30365 \& void vwarner(U32 err, const char *pat, va_list *args)
30366 .Ve
30367 .RE
30368 .RS 4
30369 .RE
30370 .ie n .IP """warn""" 4
30371 .el .IP \f(CWwarn\fR 4
30372 .IX Item "warn"
30373 .PD 0
30374 .ie n .IP """warn_nocontext""" 4
30375 .el .IP \f(CWwarn_nocontext\fR 4
30376 .IX Xref "warn warn_nocontext"
30377 .IX Item "warn_nocontext"
30378 .PD
30379 These are XS interfaces to Perl's \f(CW\*(C`warn\*(C'\fR function.
30380 .Sp
30381 They take a sprintf-style format pattern and argument list, which are used to
30382 generate a string message. If the message does not end with a newline, then it
30383 will be extended with some indication of the current location in the code, as
30384 described for \f(CW"mess_sv"\fR.
30385 .Sp
30386 The error message or object will by default be written to standard error,
30387 but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
30388 .Sp
30389 Unlike with \f(CW"croak"\fR, \f(CW\*(C`pat\*(C'\fR is not permitted to be null.
30390 .Sp
30391 The two forms differ only in that \f(CW\*(C`warn_nocontext\*(C'\fR does not take a thread
30392 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
30393 already have the thread context.
30394 .Sp
30395 NOTE: \f(CW\*(C`warn\*(C'\fR must be explicitly called as
30396 \&\f(CW\*(C`Perl_warn\*(C'\fR
30397 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
30398 .RS 4
30399 .Sp
30400 .Vb 2
30401 \& void Perl_warn (pTHX_ const char *pat, ...)
30402 \& void warn_nocontext(const char *pat, ...)
30403 .Ve
30404 .RE
30405 .RS 4
30406 .RE
30407 .ie n .IP """warner""" 4
30408 .el .IP \f(CWwarner\fR 4
30409 .IX Item "warner"
30410 .PD 0
30411 .ie n .IP """warner_nocontext""" 4
30412 .el .IP \f(CWwarner_nocontext\fR 4
30413 .IX Xref "warner warner_nocontext"
30414 .IX Item "warner_nocontext"
30415 .PD
30416 These output a warning of the specified category (or categories) given by
30417 \&\f(CW\*(C`err\*(C'\fR, using the sprintf-style format pattern \f(CW\*(C`pat\*(C'\fR, and argument list.
30418 .Sp
30419 \&\f(CW\*(C`err\*(C'\fR must be one of the \f(CW"packWARN"\fR, \f(CW\*(C`packWARN2\*(C'\fR, \f(CW\*(C`packWARN3\*(C'\fR,
30420 \&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
30421 categories. If any of the warning categories they specify is fatal, a fatal
30422 exception is thrown.
30423 .Sp
30424 In any event a message is generated by the pattern and arguments. If the
30425 message does not end with a newline, then it will be extended with some
30426 indication of the current location in the code, as described for "mess_sv".
30427 .Sp
30428 The error message or object will by default be written to standard error,
30429 but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
30430 .Sp
30431 \&\f(CW\*(C`pat\*(C'\fR is not permitted to be null.
30432 .Sp
30433 The two forms differ only in that \f(CW\*(C`warner_nocontext\*(C'\fR does not take a thread
30434 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn't
30435 already have the thread context.
30436 .Sp
30437 These functions differ from the similarly named \f(CW"warn"\fR functions, in that
30438 the latter are for XS code to unconditionally display a warning, whereas these
30439 are for code that may be compiling a perl program, and does extra checking to
30440 see if the warning should be fatal.
30441 .Sp
30442 NOTE: \f(CW\*(C`warner\*(C'\fR must be explicitly called as
30443 \&\f(CW\*(C`Perl_warner\*(C'\fR
30444 with an \f(CW\*(C`aTHX_\*(C'\fR parameter.
30445 .RS 4
30446 .Sp
30447 .Vb 2
30448 \& void Perl_warner (pTHX_ U32 err, const char *pat, ...)
30449 \& void warner_nocontext(U32 err, const char *pat, ...)
30450 .Ve
30451 .RE
30452 .RS 4
30453 .RE
30454 .ie n .IP """warn_sv""" 4
30455 .el .IP \f(CWwarn_sv\fR 4
30456 .IX Xref "warn_sv"
30457 .IX Item "warn_sv"
30458 This is an XS interface to Perl's \f(CW\*(C`warn\*(C'\fR function.
30459 .Sp
30460 \&\f(CW\*(C`baseex\*(C'\fR is the error message or object. If it is a reference, it
30461 will be used as-is. Otherwise it is used as a string, and if it does
30462 not end with a newline then it will be extended with some indication of
30463 the current location in the code, as described for "mess_sv".
30464 .Sp
30465 The error message or object will by default be written to standard error,
30466 but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
30467 .Sp
30468 To warn with a simple string message, the "warn" function may be
30469 more convenient.
30470 .RS 4
30471 .Sp
30472 .Vb 1
30473 \& void warn_sv(SV *baseex)
30474 .Ve
30475 .RE
30476 .RS 4
30477 .RE
30478 .SH XS
30479 .IX Header "XS"
30480 \&\fIxsubpp\fR compiles XS code into C. See "xsubpp" in perlutil.
30481 .ie n .IP """aMY_CXT""" 4
30482 .el .IP \f(CWaMY_CXT\fR 4
30483 .IX Item "aMY_CXT"
30484 Described in perlxs.
30485 .ie n .IP """_aMY_CXT""" 4
30486 .el .IP \f(CW_aMY_CXT\fR 4
30487 .IX Item "_aMY_CXT"
30488 Described in perlxs.
30489 .ie n .IP """aMY_CXT_""" 4
30490 .el .IP \f(CWaMY_CXT_\fR 4
30491 .IX Item "aMY_CXT_"
30492 Described in perlxs.
30493 .ie n .IP """ax""" 4
30494 .el .IP \f(CWax\fR 4
30495 .IX Xref "ax"
30496 .IX Item "ax"
30497 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the stack base offset,
30498 used by the \f(CW\*(C`ST\*(C'\fR, \f(CW\*(C`XSprePUSH\*(C'\fR and \f(CW\*(C`XSRETURN\*(C'\fR macros. The \f(CW\*(C`dMARK\*(C'\fR macro
30499 must be called prior to setup the \f(CW\*(C`MARK\*(C'\fR variable.
30500 .RS 4
30501 .Sp
30502 .Vb 1
30503 \& Stack_off_t ax
30504 .Ve
30505 .RE
30506 .RS 4
30507 .RE
30508 .ie n .IP """CLASS""" 4
30509 .el .IP \f(CWCLASS\fR 4
30510 .IX Xref "CLASS"
30511 .IX Item "CLASS"
30512 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the
30513 class name for a C++ XS constructor. This is always a \f(CW\*(C`char*\*(C'\fR. See
30514 \&\f(CW"THIS"\fR.
30515 .RS 4
30516 .Sp
30517 .Vb 1
30518 \& char* CLASS
30519 .Ve
30520 .RE
30521 .RS 4
30522 .RE
30523 .ie n .IP """dAX""" 4
30524 .el .IP \f(CWdAX\fR 4
30525 .IX Xref "dAX"
30526 .IX Item "dAX"
30527 Sets up the \f(CW\*(C`ax\*(C'\fR variable.
30528 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
30529 .RS 4
30530 .Sp
30531 .Vb 1
30532 \& dAX;
30533 .Ve
30534 .RE
30535 .RS 4
30536 .RE
30537 .ie n .IP """dAXMARK""" 4
30538 .el .IP \f(CWdAXMARK\fR 4
30539 .IX Xref "dAXMARK"
30540 .IX Item "dAXMARK"
30541 Sets up the \f(CW\*(C`ax\*(C'\fR variable and stack marker variable \f(CW\*(C`mark\*(C'\fR.
30542 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
30543 .RS 4
30544 .Sp
30545 .Vb 1
30546 \& dAXMARK;
30547 .Ve
30548 .RE
30549 .RS 4
30550 .RE
30551 .ie n .IP """dITEMS""" 4
30552 .el .IP \f(CWdITEMS\fR 4
30553 .IX Xref "dITEMS"
30554 .IX Item "dITEMS"
30555 Sets up the \f(CW\*(C`items\*(C'\fR variable.
30556 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
30557 .RS 4
30558 .Sp
30559 .Vb 1
30560 \& dITEMS;
30561 .Ve
30562 .RE
30563 .RS 4
30564 .RE
30565 .ie n .IP """dMY_CXT""" 4
30566 .el .IP \f(CWdMY_CXT\fR 4
30567 .IX Item "dMY_CXT"
30568 Described in perlxs.
30569 .ie n .IP """dMY_CXT_SV""" 4
30570 .el .IP \f(CWdMY_CXT_SV\fR 4
30571 .IX Xref "dMY_CXT_SV"
30572 .IX Item "dMY_CXT_SV"
30573 Now a placeholder that declares nothing
30574 .RS 4
30575 .Sp
30576 .Vb 1
30577 \& dMY_CXT_SV;
30578 .Ve
30579 .RE
30580 .RS 4
30581 .RE
30582 .ie n .IP """dUNDERBAR""" 4
30583 .el .IP \f(CWdUNDERBAR\fR 4
30584 .IX Xref "dUNDERBAR"
30585 .IX Item "dUNDERBAR"
30586 Sets up any variable needed by the \f(CW\*(C`UNDERBAR\*(C'\fR macro. It used to define
30587 \&\f(CW\*(C`padoff_du\*(C'\fR, but it is currently a noop. However, it is strongly advised
30588 to still use it for ensuring past and future compatibility.
30589 .RS 4
30590 .Sp
30591 .Vb 1
30592 \& dUNDERBAR;
30593 .Ve
30594 .RE
30595 .RS 4
30596 .RE
30597 .ie n .IP """dXSARGS""" 4
30598 .el .IP \f(CWdXSARGS\fR 4
30599 .IX Xref "dXSARGS"
30600 .IX Item "dXSARGS"
30601 Sets up stack and mark pointers for an XSUB, calling \f(CW\*(C`dSP\*(C'\fR and \f(CW\*(C`dMARK\*(C'\fR.
30602 Sets up the \f(CW\*(C`ax\*(C'\fR and \f(CW\*(C`items\*(C'\fR variables by calling \f(CW\*(C`dAX\*(C'\fR and \f(CW\*(C`dITEMS\*(C'\fR.
30603 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR.
30604 .RS 4
30605 .Sp
30606 .Vb 1
30607 \& dXSARGS;
30608 .Ve
30609 .RE
30610 .RS 4
30611 .RE
30612 .ie n .IP """dXSI32""" 4
30613 .el .IP \f(CWdXSI32\fR 4
30614 .IX Xref "dXSI32"
30615 .IX Item "dXSI32"
30616 Sets up the \f(CW\*(C`ix\*(C'\fR variable for an XSUB which has aliases. This is usually
30617 handled automatically by \f(CW\*(C`xsubpp\*(C'\fR.
30618 .RS 4
30619 .Sp
30620 .Vb 1
30621 \& dXSI32;
30622 .Ve
30623 .RE
30624 .RS 4
30625 .RE
30626 .ie n .IP """items""" 4
30627 .el .IP \f(CWitems\fR 4
30628 .IX Xref "items"
30629 .IX Item "items"
30630 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the number of
30631 items on the stack. See "Variable-length Parameter Lists" in perlxs.
30632 .RS 4
30633 .Sp
30634 .Vb 1
30635 \& Stack_off_t items
30636 .Ve
30637 .RE
30638 .RS 4
30639 .RE
30640 .ie n .IP """ix""" 4
30641 .el .IP \f(CWix\fR 4
30642 .IX Xref "ix"
30643 .IX Item "ix"
30644 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate which of an
30645 XSUB's aliases was used to invoke it. See "The ALIAS: Keyword" in perlxs.
30646 .RS 4
30647 .Sp
30648 .Vb 1
30649 \& I32 ix
30650 .Ve
30651 .RE
30652 .RS 4
30653 .RE
30654 .ie n .IP """MY_CXT""" 4
30655 .el .IP \f(CWMY_CXT\fR 4
30656 .IX Item "MY_CXT"
30657 Described in perlxs.
30658 .ie n .IP """MY_CXT_CLONE""" 4
30659 .el .IP \f(CWMY_CXT_CLONE\fR 4
30660 .IX Item "MY_CXT_CLONE"
30661 Described in perlxs.
30662 .ie n .IP """MY_CXT_INIT""" 4
30663 .el .IP \f(CWMY_CXT_INIT\fR 4
30664 .IX Item "MY_CXT_INIT"
30665 Described in perlxs.
30666 .ie n .IP """pMY_CXT""" 4
30667 .el .IP \f(CWpMY_CXT\fR 4
30668 .IX Item "pMY_CXT"
30669 Described in perlxs.
30670 .ie n .IP """_pMY_CXT""" 4
30671 .el .IP \f(CW_pMY_CXT\fR 4
30672 .IX Item "_pMY_CXT"
30673 Described in perlxs.
30674 .ie n .IP """pMY_CXT_""" 4
30675 .el .IP \f(CWpMY_CXT_\fR 4
30676 .IX Item "pMY_CXT_"
30677 Described in perlxs.
30678 .ie n .IP """RETVAL""" 4
30679 .el .IP \f(CWRETVAL\fR 4
30680 .IX Xref "RETVAL"
30681 .IX Item "RETVAL"
30682 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to hold the return value for an
30683 XSUB. This is always the proper type for the XSUB. See
30684 "The RETVAL Variable" in perlxs.
30685 .RS 4
30686 .Sp
30687 .Vb 1
30688 \& type RETVAL
30689 .Ve
30690 .RE
30691 .RS 4
30692 .RE
30693 .ie n .IP """ST""" 4
30694 .el .IP \f(CWST\fR 4
30695 .IX Xref "ST"
30696 .IX Item "ST"
30697 Used to access elements on the XSUB's stack.
30698 .RS 4
30699 .Sp
30700 .Vb 1
30701 \& SV* ST(int ix)
30702 .Ve
30703 .RE
30704 .RS 4
30705 .RE
30706 .ie n .IP """START_MY_CXT""" 4
30707 .el .IP \f(CWSTART_MY_CXT\fR 4
30708 .IX Item "START_MY_CXT"
30709 Described in perlxs.
30710 .ie n .IP """THIS""" 4
30711 .el .IP \f(CWTHIS\fR 4
30712 .IX Xref "THIS"
30713 .IX Item "THIS"
30714 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to designate the object in a C++
30715 XSUB. This is always the proper type for the C++ object. See \f(CW"CLASS"\fR and
30716 "Using XS With C++" in perlxs.
30717 .RS 4
30718 .Sp
30719 .Vb 1
30720 \& type THIS
30721 .Ve
30722 .RE
30723 .RS 4
30724 .RE
30725 .ie n .IP """UNDERBAR""" 4
30726 .el .IP \f(CWUNDERBAR\fR 4
30727 .IX Xref "UNDERBAR"
30728 .IX Item "UNDERBAR"
30729 The SV* corresponding to the \f(CW$_\fR variable. Works even if there
30730 is a lexical \f(CW$_\fR in scope.
30731 .ie n .IP """XS""" 4
30732 .el .IP \f(CWXS\fR 4
30733 .IX Xref "XS"
30734 .IX Item "XS"
30735 Macro to declare an XSUB and its C parameter list. This is handled by
30736 \&\f(CW\*(C`xsubpp\*(C'\fR. It is the same as using the more explicit \f(CW\*(C`XS_EXTERNAL\*(C'\fR macro; the
30737 latter is preferred.
30738 .ie n .IP """XS_EXTERNAL""" 4
30739 .el .IP \f(CWXS_EXTERNAL\fR 4
30740 .IX Xref "XS_EXTERNAL"
30741 .IX Item "XS_EXTERNAL"
30742 Macro to declare an XSUB and its C parameter list explicitly exporting the symbols.
30743 .ie n .IP """XS_INTERNAL""" 4
30744 .el .IP \f(CWXS_INTERNAL\fR 4
30745 .IX Xref "XS_INTERNAL"
30746 .IX Item "XS_INTERNAL"
30747 Macro to declare an XSUB and its C parameter list without exporting the symbols.
30748 This is handled by \f(CW\*(C`xsubpp\*(C'\fR and generally preferable over exporting the XSUB
30749 symbols unnecessarily.
30750 .ie n .IP """XSPROTO""" 4
30751 .el .IP \f(CWXSPROTO\fR 4
30752 .IX Xref "XSPROTO"
30753 .IX Item "XSPROTO"
30754 Macro used by \f(CW"XS_INTERNAL"\fR and \f(CW"XS_EXTERNAL"\fR to declare a function
30755 prototype. You probably shouldn't be using this directly yourself.
30756 .SH "Undocumented elements"
30757 .IX Header "Undocumented elements"
30758 The following functions have been flagged as part of the public
30759 API, but are currently undocumented. Use them at your own risk,
30760 as the interfaces are subject to change. Functions that are not
30761 listed in this document are not intended for public use, and
30762 should NOT be used under any circumstances.
30763 .PP
30764 If you feel you need to use one of these functions, first send
30765 email to perl5\[email protected] <mailto:[email protected]>.
30766 It may be that there is a good reason for the function not being
30767 documented, and it should be removed from this list; or it may
30768 just be that no one has gotten around to documenting it. In the
30769 latter case, you will be asked to submit a patch to document the
30770 function. Once your patch is accepted, it will indicate that the
30771 interface is stable (unless it is explicitly marked otherwise) and
30772 usable by you.
30773 .PP
30774
30775 .IX Xref "clone_params_del clone_params_new do_open do_openn PERL_BUILD_DATE resume_compcv sv_dup sv_dup_inc"
30776 .PP
30777 .Vb 2
30778 \& clone_params_del do_open PERL_BUILD_DATE sv_dup
30779 \& clone_params_new do_openn resume_compcv sv_dup_inc
30780 .Ve
30781 .PP
30782 Next are the API-flagged elements that are considered experimental. Using one
30783 of these is even more risky than plain undocumented ones. They are listed
30784 here because they should be listed somewhere (so their existence doesn't get
30785 lost) and this is the best place for them.
30786 .PP
30787
30788 .IX Xref "apply_attrs_string gv_fetchmethod_pv_flags gv_fetchmethod_pvn_flags gv_fetchmethod_sv_flags hv_store_flags leave_adjust_stacks newXS_flags savetmps thread_locale_init thread_locale_term"
30789 .PP
30790 .Vb 4
30791 \& apply_attrs_string hv_store_flags thread_locale_init
30792 \& gv_fetchmethod_pv_flags leave_adjust_stacks thread_locale_term
30793 \& gv_fetchmethod_pvn_flags newXS_flags
30794 \& gv_fetchmethod_sv_flags savetmps
30795 .Ve
30796 .PP
30797 Finally are deprecated undocumented API elements.
30798 Do not use any for new code; remove all occurrences of all of these from
30799 existing code.
30800 .PP
30801 There are currently no items of this type
30802 .SH AUTHORS
30803 .IX Header "AUTHORS"
30804 Until May 1997, this document was maintained by Jeff Okamoto
30805 <[email protected]>. It is now maintained as part of Perl itself.
30806 .PP
30807 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
30808 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
30809 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
30810 Stephen McCamant, and Gurusamy Sarathy.
30811 .PP
30812 API Listing originally by Dean Roehrich <[email protected]>.
30813 .PP
30814 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
30815 .SH "SEE ALSO"
30816 .IX Header "SEE ALSO"
30817 \&\fIconfig.h\fR, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips, perlintern, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs