Debian Codegraph @

upstream/opensuse-tumbleweed/man1/perlapi.1

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "PERLAPI 1"
61 .TH PERLAPI 1 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 perlapi \- autogenerated documentation for the perl public API
68 .SH DESCRIPTION
69 .IX Xref "Perl API API api"
70 .IX Header "DESCRIPTION"
71 This file contains most of the documentation of the perl public API, as
72 generated by \fIembed.pl\fR. Specifically, it is a listing of functions,
73 macros, flags, and variables that may be used by extension writers. Besides
74 perlintern and \fIconfig.h\fR, some items are listed here as being actually
75 documented in another pod.
76 .PP
77 At the end is a list of functions which have yet
78 to be documented. Patches welcome! The interfaces of these are subject to
79 change without notice.
80 .PP
81 Some of the functions documented here are consolidated so that a single entry
82 serves for multiple functions which all do basically the same thing, but have
83 some slight differences. For example, one form might process magic, while
84 another doesn\*(Aqt. The name of each variation is listed at the top of the
85 single entry.
86 .PP
87 The names of all API functions begin with the prefix \f(CW\*(C`Perl_\*(C'\fR so as to
88 prevent any name collisions with your code. But, unless
89 \&\f(CW\*(C`\-Accflags=\-DPERL_NO_SHORT_NAMES\*(C'\fR has been specified in compiling your code
90 (see "Hiding Perl_" in perlembed), synonymous macros are also available to you
91 that don\*(Aqt have this prefix, and also hide from you the need (or not) to have
92 a thread context parameter passed to the function. Generally, code is easier
93 to write and to read when the short form is used, so in practice that
94 compilation flag is not used. Not all functions have the short form; both
95 are listed here when available.
96 .PP
97 Anything not listed here or in the other mentioned pods is not part of the
98 public API, and should not be used by extension writers at all. For these
99 reasons, blindly using functions listed in \fIproto.h\fR is to be avoided when
100 writing extensions.
101 .PP
102 In Perl, unlike C, a string of characters may generally contain embedded
103 \&\f(CW\*(C`NUL\*(C'\fR characters. Sometimes in the documentation a Perl string is referred
104 to as a "buffer" to distinguish it from a C string, but sometimes they are
105 both just referred to as strings.
106 .PP
107 Note that all Perl API global variables must be referenced with the \f(CW\*(C`PL_\*(C'\fR
108 prefix. Again, those not listed here are not to be used by extension writers,
109 and may be changed or removed without notice; same with macros.
110 Some macros are provided for compatibility with the older,
111 unadorned names, but this support may be disabled in a future release.
112 .PP
113 Perl was originally written to handle US\-ASCII only (that is characters
114 whose ordinal numbers are in the range 0 \- 127).
115 And documentation and comments may still use the term ASCII, when
116 sometimes in fact the entire range from 0 \- 255 is meant.
117 .PP
118 The non\-ASCII characters below 256 can have various meanings, depending on
119 various things. (See, most notably, perllocale.) But usually the whole
120 range can be referred to as ISO\-8859\-1. Often, the term "Latin\-1" (or
121 "Latin1") is used as an equivalent for ISO\-8859\-1. But some people treat
122 "Latin1" as referring just to the characters in the range 128 through 255, or
123 sometimes from 160 through 255.
124 This documentation uses "Latin1" and "Latin\-1" to refer to all 256 characters.
125 .PP
126 Note that Perl can be compiled and run under either ASCII or EBCDIC (See
127 perlebcdic). Most of the documentation (and even comments in the code)
128 ignore the EBCDIC possibility.
129 For almost all purposes the differences are transparent.
130 As an example, under EBCDIC,
131 instead of UTF\-8, UTF\-EBCDIC is used to encode Unicode strings, and so
132 whenever this documentation refers to \f(CW\*(C`utf8\*(C'\fR
133 (and variants of that name, including in function names),
134 it also (essentially transparently) means \f(CW\*(C`UTF\-EBCDIC\*(C'\fR.
135 But the ordinals of characters differ between ASCII, EBCDIC, and
136 the UTF\- encodings, and a string encoded in UTF\-EBCDIC may occupy a different
137 number of bytes than in UTF\-8.
138 .PP
139 The organization of this document is tentative and subject to change.
140 Suggestions and patches welcome
141 perl5\[email protected] <mailto:[email protected]>.
142 .PP
143 The API elements are grouped by functionality into sections, as follows.
144 Within sections the elements are ordered alphabetically, ignoring case, with
145 non\-leading underscores sorted first, and leading underscores and digits
146 sorted last.
147 .IP """AV Handling""" 4
148 .IX Item """AV Handling"""
149 .PD 0
150 .IP """Callback Functions""" 4
151 .IX Item """Callback Functions"""
152 .IP """Casting""" 4
153 .IX Item """Casting"""
154 .IP """Character case changing""" 4
155 .IX Item """Character case changing"""
156 .IP """Character classification""" 4
157 .IX Item """Character classification"""
158 .IP """Compiler and Preprocessor information""" 4
159 .IX Item """Compiler and Preprocessor information"""
160 .IP """Compiler directives""" 4
161 .IX Item """Compiler directives"""
162 .IP """Compile\-time scope hooks""" 4
163 .IX Item """Compile-time scope hooks"""
164 .IP """Concurrency""" 4
165 .IX Item """Concurrency"""
166 .IP """COPs and Hint Hashes""" 4
167 .IX Item """COPs and Hint Hashes"""
168 .IP """Custom Operators""" 4
169 .IX Item """Custom Operators"""
170 .IP """CV Handling""" 4
171 .IX Item """CV Handling"""
172 .IP """Debugging""" 4
173 .IX Item """Debugging"""
174 .IP """Display functions""" 4
175 .IX Item """Display functions"""
176 .IP """Embedding, Threads, and Interpreter Cloning""" 4
177 .IX Item """Embedding, Threads, and Interpreter Cloning"""
178 .IP """Errno""" 4
179 .IX Item """Errno"""
180 .IP """Exception Handling (simple) Macros""" 4
181 .IX Item """Exception Handling (simple) Macros"""
182 .IP """Filesystem configuration values""" 4
183 .IX Item """Filesystem configuration values"""
184 .IP """Floating point""" 4
185 .IX Item """Floating point"""
186 .IP """General Configuration""" 4
187 .IX Item """General Configuration"""
188 .IP """Global Variables""" 4
189 .IX Item """Global Variables"""
190 .IP """GV Handling and Stashes""" 4
191 .IX Item """GV Handling and Stashes"""
192 .IP """Hook manipulation""" 4
193 .IX Item """Hook manipulation"""
194 .IP """HV Handling""" 4
195 .IX Item """HV Handling"""
196 .IP """Input/Output""" 4
197 .IX Item """Input/Output"""
198 .IP """Integer""" 4
199 .IX Item """Integer"""
200 .IP """I/O Formats""" 4
201 .IX Item """I/O Formats"""
202 .IP """Lexer interface""" 4
203 .IX Item """Lexer interface"""
204 .IP """Locales""" 4
205 .IX Item """Locales"""
206 .IP """Magic""" 4
207 .IX Item """Magic"""
208 .IP """Memory Management""" 4
209 .IX Item """Memory Management"""
210 .IP """MRO""" 4
211 .IX Item """MRO"""
212 .IP """Multicall Functions""" 4
213 .IX Item """Multicall Functions"""
214 .IP """Numeric Functions""" 4
215 .IX Item """Numeric Functions"""
216 .IP """Optrees""" 4
217 .IX Item """Optrees"""
218 .IP """Pack and Unpack""" 4
219 .IX Item """Pack and Unpack"""
220 .IP """Pad Data Structures""" 4
221 .IX Item """Pad Data Structures"""
222 .IP """Password and Group access""" 4
223 .IX Item """Password and Group access"""
224 .IP """Paths to system commands""" 4
225 .IX Item """Paths to system commands"""
226 .IP """Prototype information""" 4
227 .IX Item """Prototype information"""
228 .IP """Reference\-counted stack manipulation""" 4
229 .IX Item """Reference-counted stack manipulation"""
230 .IP """REGEXP Functions""" 4
231 .IX Item """REGEXP Functions"""
232 .IP """Reports and Formats""" 4
233 .IX Item """Reports and Formats"""
234 .IP """Signals""" 4
235 .IX Item """Signals"""
236 .IP """Site configuration""" 4
237 .IX Item """Site configuration"""
238 .IP """Sockets configuration values""" 4
239 .IX Item """Sockets configuration values"""
240 .IP """Source Filters""" 4
241 .IX Item """Source Filters"""
242 .IP """Stack Manipulation Macros""" 4
243 .IX Item """Stack Manipulation Macros"""
244 .IP """String Handling""" 4
245 .IX Item """String Handling"""
246 .IP """SV Flags""" 4
247 .IX Item """SV Flags"""
248 .IP """SV Handling""" 4
249 .IX Item """SV Handling"""
250 .IP """Tainting""" 4
251 .IX Item """Tainting"""
252 .IP """Time""" 4
253 .IX Item """Time"""
254 .IP """Typedef names""" 4
255 .IX Item """Typedef names"""
256 .IP """Unicode Support""" 4
257 .IX Item """Unicode Support"""
258 .IP """Utility Functions""" 4
259 .IX Item """Utility Functions"""
260 .IP """Versioning""" 4
261 .IX Item """Versioning"""
262 .IP """Warning and Dieing""" 4
263 .IX Item """Warning and Dieing"""
264 .IP """XS""" 4
265 .IX Item """XS"""
266 .IP """Undocumented elements""" 4
267 .IX Item """Undocumented elements"""
268 .PD
269 .PP
270 The listing below is alphabetical, case insensitive.
271 .SH "AV Handling"
272 .IX Header "AV Handling"
273 .ie n .IP """AV""" 4
274 .el .IP \f(CWAV\fR 4
275 .IX Item "AV"
276 Described in perlguts.
277 .ie n .IP """av_clear""" 4
278 .el .IP \f(CWav_clear\fR 4
279 .IX Xref "av_clear"
280 .IX Item "av_clear"
281 Frees all the elements of an array, leaving it empty.
282 The XS equivalent of \f(CW\*(C`@array = ()\*(C'\fR. See also "av_undef".
283 .Sp
284 Note that it is possible that the actions of a destructor called directly
285 or indirectly by freeing an element of the array could cause the reference
286 count of the array itself to be reduced (e.g. by deleting an entry in the
287 symbol table). So it is a possibility that the AV could have been freed
288 (or even reallocated) on return from the call unless you hold a reference
289 to it.
290 .RS 4
291 .Sp
292 .Vb 2
293 \& void av_clear( AV *av)
294 \& void Perl_av_clear(pTHX_ AV *av)
295 .Ve
296 .RE
297 .RS 4
298 .RE
299 .ie n .IP """av_count""" 4
300 .el .IP \f(CWav_count\fR 4
301 .IX Xref "av_count"
302 .IX Item "av_count"
303 Returns the number of elements in the array \f(CW\*(C`av\*(C'\fR. This is the true length of
304 the array, including any undefined elements. It is always the same as
305 \&\f(CW\*(C`av_top_index(av)\ +\ 1\*(C'\fR.
306 .RS 4
307 .Sp
308 .Vb 2
309 \& Size_t av_count( AV *av)
310 \& Size_t Perl_av_count(pTHX_ AV *av)
311 .Ve
312 .RE
313 .RS 4
314 .RE
315 .ie n .IP """av_create_and_push""" 4
316 .el .IP \f(CWav_create_and_push\fR 4
317 .IX Xref "av_create_and_push"
318 .IX Item "av_create_and_push"
319 Push an SV onto the end of the array, creating the array if necessary.
320 A small internal helper function to remove a commonly duplicated idiom.
321 .RS 4
322 .Sp
323 .Vb 2
324 \& void Perl_av_create_and_push(pTHX_ AV ** const avp,
325 \& SV * const val)
326 .Ve
327 .RE
328 .RS 4
329 .RE
330 .ie n .IP """av_create_and_unshift_one""" 4
331 .el .IP \f(CWav_create_and_unshift_one\fR 4
332 .IX Xref "av_create_and_unshift_one"
333 .IX Item "av_create_and_unshift_one"
334 Unshifts an SV onto the beginning of the array, creating the array if
335 necessary.
336 A small internal helper function to remove a commonly duplicated idiom.
337 .RS 4
338 .Sp
339 .Vb 2
340 \& SV ** Perl_av_create_and_unshift_one(pTHX_ AV ** const avp,
341 \& SV * const val)
342 .Ve
343 .RE
344 .RS 4
345 .RE
346 .ie n .IP """av_delete""" 4
347 .el .IP \f(CWav_delete\fR 4
348 .IX Xref "av_delete"
349 .IX Item "av_delete"
350 Deletes the element indexed by \f(CW\*(C`key\*(C'\fR from the array, makes the element
351 mortal, and returns it. If \f(CW\*(C`flags\*(C'\fR equals \f(CW\*(C`G_DISCARD\*(C'\fR, the element is
352 freed and NULL is returned. NULL is also returned if \f(CW\*(C`key\*(C'\fR is out of
353 range.
354 .Sp
355 Perl equivalent: \f(CW\*(C`splice(@myarray,\ $key,\ 1,\ undef)\*(C'\fR (with the
356 \&\f(CW\*(C`splice\*(C'\fR in void context if \f(CW\*(C`G_DISCARD\*(C'\fR is present).
357 .RS 4
358 .Sp
359 .Vb 2
360 \& SV * av_delete( AV *av, SSize_t key, I32 flags)
361 \& SV * Perl_av_delete(pTHX_ AV *av, SSize_t key, I32 flags)
362 .Ve
363 .RE
364 .RS 4
365 .RE
366 .ie n .IP """av_exists""" 4
367 .el .IP \f(CWav_exists\fR 4
368 .IX Xref "av_exists"
369 .IX Item "av_exists"
370 Returns true if the element indexed by \f(CW\*(C`key\*(C'\fR has been initialized.
371 .Sp
372 This relies on the fact that uninitialized array elements are set to
373 \&\f(CW\*(C`NULL\*(C'\fR.
374 .Sp
375 Perl equivalent: \f(CWexists($myarray[$key])\fR.
376 .RS 4
377 .Sp
378 .Vb 2
379 \& bool av_exists( AV *av, SSize_t key)
380 \& bool Perl_av_exists(pTHX_ AV *av, SSize_t key)
381 .Ve
382 .RE
383 .RS 4
384 .RE
385 .ie n .IP """av_extend""" 4
386 .el .IP \f(CWav_extend\fR 4
387 .IX Xref "av_extend"
388 .IX Item "av_extend"
389 Pre\-extend an array so that it is capable of storing values at indexes
390 \&\f(CW\*(C`0..key\*(C'\fR. Thus \f(CW\*(C`av_extend(av,99)\*(C'\fR guarantees that the array can store 100
391 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
392 on a plain array will work without any further memory allocation.
393 .Sp
394 If the av argument is a tied array then will call the \f(CW\*(C`EXTEND\*(C'\fR tied
395 array method with an argument of \f(CW\*(C`(key+1)\*(C'\fR.
396 .RS 4
397 .Sp
398 .Vb 2
399 \& void av_extend( AV *av, SSize_t key)
400 \& void Perl_av_extend(pTHX_ AV *av, SSize_t key)
401 .Ve
402 .RE
403 .RS 4
404 .RE
405 .ie n .IP """av_fetch""" 4
406 .el .IP \f(CWav_fetch\fR 4
407 .IX Xref "av_fetch"
408 .IX Item "av_fetch"
409 Returns the SV at the specified index in the array. The \f(CW\*(C`key\*(C'\fR is the
410 index. If \f(CW\*(C`lval\*(C'\fR is true, you are guaranteed to get a real SV back (in case
411 it wasn\*(Aqt real before), which you can then modify. Check that the return
412 value is non\-NULL before dereferencing it to a \f(CW\*(C`SV*\*(C'\fR.
413 .Sp
414 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for
415 more information on how to use this function on tied arrays.
416 .Sp
417 The rough perl equivalent is \f(CW$myarray[$key]\fR.
418 .RS 4
419 .Sp
420 .Vb 2
421 \& SV ** av_fetch( AV *av, SSize_t key, I32 lval)
422 \& SV ** Perl_av_fetch(pTHX_ AV *av, SSize_t key, I32 lval)
423 .Ve
424 .RE
425 .RS 4
426 .RE
427 .ie n .IP """av_fill""" 4
428 .el .IP \f(CWav_fill\fR 4
429 .IX Xref "av_fill"
430 .IX Item "av_fill"
431 Set the highest index in the array to the given number, equivalent to
432 Perl\*(Aqs \f(CW\*(C`$#array\ =\ $fill;\*(C'\fR.
433 .Sp
434 The number of elements in the array will be \f(CW\*(C`fill\ +\ 1\*(C'\fR after
435 \&\f(CWav_fill()\fR returns. If the array was previously shorter, then the
436 additional elements appended are set to NULL. If the array
437 was longer, then the excess elements are freed. \f(CW\*(C`av_fill(av,\ \-1)\*(C'\fR is
438 the same as \f(CWav_clear(av)\fR.
439 .RS 4
440 .Sp
441 .Vb 2
442 \& void av_fill( AV *av, SSize_t fill)
443 \& void Perl_av_fill(pTHX_ AV *av, SSize_t fill)
444 .Ve
445 .RE
446 .RS 4
447 .RE
448 .ie n .IP """av_len*""" 4
449 .el .IP \f(CWav_len*\fR 4
450 .IX Item "av_len*"
451 Described under \f(CW"av_top_index"\fR
452 .ie n .IP """av_make""" 4
453 .el .IP \f(CWav_make\fR 4
454 .IX Xref "av_make"
455 .IX Item "av_make"
456 Creates a new AV and populates it with a list (\f(CW**strp\fR, length \f(CW\*(C`size\*(C'\fR) of
457 SVs. A copy is made of each SV, so their refcounts are not changed. The new
458 AV will have a reference count of 1.
459 .Sp
460 Perl equivalent: \f(CW\*(C`my @new_array = ($scalar1, $scalar2, $scalar3...);\*(C'\fR
461 .RS 4
462 .Sp
463 .Vb 2
464 \& AV * av_make( SSize_t size, SV **strp)
465 \& AV * Perl_av_make(pTHX_ SSize_t size, SV **strp)
466 .Ve
467 .RE
468 .RS 4
469 .RE
470 .ie n .IP """av_pop""" 4
471 .el .IP \f(CWav_pop\fR 4
472 .IX Xref "av_pop"
473 .IX Item "av_pop"
474 Removes one SV from the end of the array, reducing its size by one and
475 returning the SV (transferring control of one reference count) to the
476 caller. Returns \f(CW&PL_sv_undef\fR if the array is empty.
477 .Sp
478 Perl equivalent: \f(CW\*(C`pop(@myarray);\*(C'\fR
479 .RS 4
480 .Sp
481 .Vb 2
482 \& SV * av_pop( AV *av)
483 \& SV * Perl_av_pop(pTHX_ AV *av)
484 .Ve
485 .RE
486 .RS 4
487 .RE
488 .ie n .IP """av_push""" 4
489 .el .IP \f(CWav_push\fR 4
490 .IX Item "av_push"
491 .PD 0
492 .ie n .IP """av_push_simple""" 4
493 .el .IP \f(CWav_push_simple\fR 4
494 .IX Xref "av_push av_push_simple"
495 .IX Item "av_push_simple"
496 .PD
497 These each push an SV (transferring control of one reference count) onto the
498 end of the array. The array will grow automatically to accommodate the
499 addition.
500 .Sp
501 Perl equivalent: \f(CW\*(C`push @myarray, $val;\*(C'\fR.
502 .Sp
503 \&\f(CW\*(C`av_push\*(C'\fR is the general purpose form, suitable for all situations.
504 .Sp
505 \&\f(CW\*(C`av_push_simple\*(C'\fR is a cut\-down version of \f(CW\*(C`av_push\*(C'\fR that assumes that the
506 array is very straightforward, with no magic, not readonly, and is AvREAL
507 (see "Real AVs \- and those that are not" in perlguts), and that \f(CW\*(C`key\*(C'\fR is not
508 less than \-1. This function MUST NOT be used in situations where any of those
509 assumptions may not hold.
510 .RS 4
511 .Sp
512 .Vb 4
513 \& void av_push ( AV *av, SV *val)
514 \& void Perl_av_push (pTHX_ AV *av, SV *val)
515 \& void av_push_simple( AV *av, SV *val)
516 \& void Perl_av_push_simple(pTHX_ AV *av, SV *val)
517 .Ve
518 .RE
519 .RS 4
520 .RE
521 .ie n .IP """av_shift""" 4
522 .el .IP \f(CWav_shift\fR 4
523 .IX Xref "av_shift"
524 .IX Item "av_shift"
525 Removes one SV from the start of the array, reducing its size by one and
526 returning the SV (transferring control of one reference count) to the
527 caller. Returns \f(CW&PL_sv_undef\fR if the array is empty.
528 .Sp
529 Perl equivalent: \f(CW\*(C`shift(@myarray);\*(C'\fR
530 .RS 4
531 .Sp
532 .Vb 2
533 \& SV * av_shift( AV *av)
534 \& SV * Perl_av_shift(pTHX_ AV *av)
535 .Ve
536 .RE
537 .RS 4
538 .RE
539 .ie n .IP """av_store""" 4
540 .el .IP \f(CWav_store\fR 4
541 .IX Xref "av_store"
542 .IX Item "av_store"
543 Stores an SV in an array. The array index is specified as \f(CW\*(C`key\*(C'\fR. The
544 return value will be \f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not
545 need to be actually stored within the array (as in the case of tied
546 arrays). Otherwise, it can be dereferenced
547 to get the \f(CW\*(C`SV*\*(C'\fR that was stored
548 there (= \f(CW\*(C`val\*(C'\fR)).
549 .Sp
550 Note that the caller is responsible for suitably incrementing the reference
551 count of \f(CW\*(C`val\*(C'\fR before the call, and decrementing it if the function
552 returned \f(CW\*(C`NULL\*(C'\fR.
553 .Sp
554 Approximate Perl equivalent: \f(CW\*(C`splice(@myarray, $key, 1, $val)\*(C'\fR.
555 .Sp
556 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for
557 more information on how to use this function on tied arrays.
558 .RS 4
559 .Sp
560 .Vb 2
561 \& SV ** av_store( AV *av, SSize_t key, SV *val)
562 \& SV ** Perl_av_store(pTHX_ AV *av, SSize_t key, SV *val)
563 .Ve
564 .RE
565 .RS 4
566 .RE
567 .ie n .IP """av_top_index""" 4
568 .el .IP \f(CWav_top_index\fR 4
569 .IX Item "av_top_index"
570 .PD 0
571 .ie n .IP """av_tindex""" 4
572 .el .IP \f(CWav_tindex\fR 4
573 .IX Item "av_tindex"
574 .ie n .IP """AvFILL""" 4
575 .el .IP \f(CWAvFILL\fR 4
576 .IX Item "AvFILL"
577 .ie n .IP """av_len""" 4
578 .el .IP \f(CWav_len\fR 4
579 .IX Xref "av_len av_tindex av_top_index AvFILL"
580 .IX Item "av_len"
581 .PD
582 These behave identically.
583 If the array \f(CW\*(C`av\*(C'\fR is empty, these return \-1; otherwise they return the maximum
584 value of the indices of all the array elements which are currently defined in
585 \&\f(CW\*(C`av\*(C'\fR.
586 .Sp
587 They process \*(Aqget\*(Aq magic.
588 .Sp
589 The Perl equivalent for these is \f(CW$#av\fR.
590 .Sp
591 Note that, unlike what the name \f(CW\*(C`av_len\*(C'\fR implies, it returns
592 the maximum index in the array. This is unlike "sv_len", which returns what
593 you would expect. To get the actual number of elements in an array, use
594 \&\f(CW"av_count"\fR.
595 .RS 4
596 .Sp
597 .Vb 5
598 \& SSize_t av_top_index( AV *av)
599 \& SSize_t av_tindex ( AV *av)
600 \& SSize_t AvFILL ( AV* av)
601 \& SSize_t av_len ( AV *av)
602 \& SSize_t Perl_av_len (pTHX_ AV *av)
603 .Ve
604 .RE
605 .RS 4
606 .RE
607 .ie n .IP """av_undef""" 4
608 .el .IP \f(CWav_undef\fR 4
609 .IX Xref "av_undef"
610 .IX Item "av_undef"
611 Undefines the array. The XS equivalent of \f(CWundef(@array)\fR.
612 .Sp
613 As well as freeing all the elements of the array (like \f(CWav_clear()\fR), this
614 also frees the memory used by the av to store its list of scalars.
615 .Sp
616 See "av_clear" for a note about the array possibly being invalid on
617 return.
618 .RS 4
619 .Sp
620 .Vb 2
621 \& void av_undef( AV *av)
622 \& void Perl_av_undef(pTHX_ AV *av)
623 .Ve
624 .RE
625 .RS 4
626 .RE
627 .ie n .IP """av_unshift""" 4
628 .el .IP \f(CWav_unshift\fR 4
629 .IX Xref "av_unshift"
630 .IX Item "av_unshift"
631 Unshift the given number of \f(CW\*(C`undef\*(C'\fR values onto the beginning of the
632 array. The array will grow automatically to accommodate the addition.
633 .Sp
634 Perl equivalent: \f(CW\*(C`unshift\ @myarray,\ ((undef)\ x\ $num);\*(C'\fR
635 .RS 4
636 .Sp
637 .Vb 2
638 \& void av_unshift( AV *av, SSize_t num)
639 \& void Perl_av_unshift(pTHX_ AV *av, SSize_t num)
640 .Ve
641 .RE
642 .RS 4
643 .RE
644 .ie n .IP """AvALLOC""" 4
645 .el .IP \f(CWAvALLOC\fR 4
646 .IX Item "AvALLOC"
647 Described in perlguts.
648 .RS 4
649 .Sp
650 .Vb 1
651 \& AvALLOC(AV* av)
652 .Ve
653 .RE
654 .RS 4
655 .RE
656 .ie n .IP """AvARRAY""" 4
657 .el .IP \f(CWAvARRAY\fR 4
658 .IX Xref "AvARRAY"
659 .IX Item "AvARRAY"
660 Returns a pointer to the AV\*(Aqs internal SV* array.
661 .Sp
662 This is useful for doing pointer arithmetic on the array.
663 If all you need is to look up an array element, then prefer \f(CW\*(C`av_fetch\*(C'\fR.
664 .RS 4
665 .Sp
666 .Vb 1
667 \& SV** AvARRAY(AV* av)
668 .Ve
669 .RE
670 .RS 4
671 .RE
672 .ie n .IP """AvFILL*""" 4
673 .el .IP \f(CWAvFILL*\fR 4
674 .IX Item "AvFILL*"
675 Described under \f(CW"av_top_index"\fR
676 .ie n .IP """AvREFCNT_inc""" 4
677 .el .IP \f(CWAvREFCNT_inc\fR 4
678 .IX Item "AvREFCNT_inc"
679 .PD 0
680 .ie n .IP """AvREFCNT_inc_simple""" 4
681 .el .IP \f(CWAvREFCNT_inc_simple\fR 4
682 .IX Item "AvREFCNT_inc_simple"
683 .ie n .IP """AvREFCNT_inc_simple_NN""" 4
684 .el .IP \f(CWAvREFCNT_inc_simple_NN\fR 4
685 .IX Xref "AvREFCNT_inc AvREFCNT_inc_simple AvREFCNT_inc_simple_NN"
686 .IX Item "AvREFCNT_inc_simple_NN"
687 .PD
688 These all increment the reference count of the given SV, which must be an AV.
689 They are useful when assigning the result into a typed pointer as they avoid
690 the need to cast the result to the appropriate type.
691 .RS 4
692 .Sp
693 .Vb 3
694 \& AV * AvREFCNT_inc (AV *av)
695 \& AV * AvREFCNT_inc_simple (AV *av)
696 \& AV * AvREFCNT_inc_simple_NN(AV *av)
697 .Ve
698 .RE
699 .RS 4
700 .RE
701 .ie n .IP """get_av""" 4
702 .el .IP \f(CWget_av\fR 4
703 .IX Xref "get_av"
704 .IX Item "get_av"
705 Returns the AV of the specified Perl global or package array with the given
706 name (so it won\*(Aqt work on lexical variables). \f(CW\*(C`flags\*(C'\fR are passed
707 to \f(CW\*(C`gv_fetchpv\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
708 Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero
709 (ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is
710 returned.
711 .Sp
712 Perl equivalent: \f(CW\*(C`@{"$name"}\*(C'\fR.
713 .Sp
714 NOTE: the \f(CWperl_get_av()\fR form is \fBdeprecated\fR.
715 .RS 4
716 .Sp
717 .Vb 2
718 \& AV * get_av( const char *name, I32 flags)
719 \& AV * Perl_get_av(pTHX_ const char *name, I32 flags)
720 .Ve
721 .RE
722 .RS 4
723 .RE
724 .ie n .IP """newAV""" 4
725 .el .IP \f(CWnewAV\fR 4
726 .IX Item "newAV"
727 .PD 0
728 .ie n .IP """newAV_mortal""" 4
729 .el .IP \f(CWnewAV_mortal\fR 4
730 .IX Item "newAV_mortal"
731 .ie n .IP """newAV_alloc_x""" 4
732 .el .IP \f(CWnewAV_alloc_x\fR 4
733 .IX Item "newAV_alloc_x"
734 .ie n .IP """newAV_alloc_xz""" 4
735 .el .IP \f(CWnewAV_alloc_xz\fR 4
736 .IX Xref "newAV newAV_alloc_x newAV_alloc_xz newAV_mortal"
737 .IX Item "newAV_alloc_xz"
738 .PD
739 These all create a new AV, setting the reference count to 1. If you also know
740 the initial elements of the array with, see "\f(CW\*(C`av_make\*(C'\fR".
741 .Sp
742 As background, an array consists of three things:
743 .RS 4
744 .IP 1. 4
745 A data structure containing information about the array as a whole, such as its
746 size and reference count.
747 .IP 2. 4
748 A C language array of pointers to the individual elements. These are treated
749 as pointers to SVs, so all must be castable to SV*.
750 .IP 3. 4
751 The individual elements themselves. These could be, for instance, SVs and/or
752 AVs and/or HVs, etc.
753 .RE
754 .RS 4
755 .Sp
756 An empty array need only have the first data structure, and all these functions
757 create that. They differ in what else they do, as follows:
758 .ie n .IP """newAV"" form" 4
759 .el .IP "\f(CWnewAV\fR form" 4
760 .IX Item "newAV form"
761 This does nothing beyond creating the whole\-array data structure.
762 The Perl equivalent is approximately \f(CW\*(C`my\ @array;\*(C'\fR
763 .Sp
764 This is useful when the minimum size of the array could be zero (perhaps there
765 are likely code paths that will entirely skip using it).
766 .Sp
767 If the array does get used, the pointers data structure will need to be
768 allocated at that time. This will end up being done by "av_extend">,
769 either explicitly:
770 .Sp
771 .Vb 1
772 \& av_extend(av, len);
773 .Ve
774 .Sp
775 or implicitly when the first element is stored:
776 .Sp
777 .Vb 1
778 \& (void)av_store(av, 0, sv);
779 .Ve
780 .Sp
781 Unused array elements are typically initialized by \f(CW\*(C`av_extend\*(C'\fR.
782 .ie n .IP """newAV_mortal"" form" 4
783 .el .IP "\f(CWnewAV_mortal\fR form" 4
784 .IX Item "newAV_mortal form"
785 This also creates the whole\-array data structure, but also mortalises it.
786 (That is to say, a reference to the AV is added to the \f(CW\*(C`temps\*(C'\fR stack.)
787 .ie n .IP """newAV_alloc_x"" form" 4
788 .el .IP "\f(CWnewAV_alloc_x\fR form" 4
789 .IX Item "newAV_alloc_x form"
790 This effectively does a \f(CW\*(C`newAV\*(C'\fR followed by also allocating (uninitialized)
791 space for the pointers array. This is used when you know ahead of time the
792 likely minimum size of the array. It is more efficient to do this than doing a
793 plain \f(CW\*(C`newAV\*(C'\fR followed by an \f(CW\*(C`av_extend\*(C'\fR.
794 .Sp
795 Of course the array can be extended later should it become necessary.
796 .Sp
797 \&\f(CW\*(C`size\*(C'\fR must be at least 1.
798 .ie n .IP """newAV_alloc_xz"" form" 4
799 .el .IP "\f(CWnewAV_alloc_xz\fR form" 4
800 .IX Item "newAV_alloc_xz form"
801 This is \f(CW\*(C`newAV_alloc_x\*(C'\fR, but initializes each pointer in it to NULL. This
802 gives added safety to guard against them being read before being set.
803 .Sp
804 \&\f(CW\*(C`size\*(C'\fR must be at least 1.
805 .RE
806 .RS 4
807 .Sp
808 The following examples all result in an array that can fit four elements
809 (indexes 0 .. 3):
810 .Sp
811 .Vb 2
812 \& AV *av = newAV();
813 \& av_extend(av, 3);
814 \&
815 \& AV *av = newAV_alloc_x(4);
816 \&
817 \& AV *av = newAV_alloc_xz(4);
818 .Ve
819 .Sp
820 In contrast, the following examples allocate an array that is only guaranteed
821 to fit one element without extending:
822 .Sp
823 .Vb 2
824 \& AV *av = newAV_alloc_x(1);
825 \& AV *av = newAV_alloc_xz(1);
826 .Ve
827 .Sp
828 .Vb 5
829 \& AV * newAV ()
830 \& AV * Perl_newAV (pTHX)
831 \& AV * newAV_mortal ()
832 \& AV * newAV_alloc_x (SSize_t size)
833 \& AV * newAV_alloc_xz(SSize_t size)
834 .Ve
835 .RE
836 .RS 4
837 .RE
838 .ie n .IP """newAVav""" 4
839 .el .IP \f(CWnewAVav\fR 4
840 .IX Xref "newAVav"
841 .IX Item "newAVav"
842 Creates a new AV and populates it with values copied from an existing AV. The
843 new AV will have a reference count of 1, and will contain newly created SVs
844 copied from the original SV. The original source will remain unchanged.
845 .Sp
846 Perl equivalent: \f(CW\*(C`my @new_array = @existing_array;\*(C'\fR
847 .RS 4
848 .Sp
849 .Vb 2
850 \& AV * newAVav( AV *oav)
851 \& AV * Perl_newAVav(pTHX_ AV *oav)
852 .Ve
853 .RE
854 .RS 4
855 .RE
856 .ie n .IP """newAVhv""" 4
857 .el .IP \f(CWnewAVhv\fR 4
858 .IX Xref "newAVhv"
859 .IX Item "newAVhv"
860 Creates a new AV and populates it with keys and values copied from an existing
861 HV. The new AV will have a reference count of 1, and will contain newly
862 created SVs copied from the original HV. The original source will remain
863 unchanged.
864 .Sp
865 Perl equivalent: \f(CW\*(C`my @new_array = %existing_hash;\*(C'\fR
866 .RS 4
867 .Sp
868 .Vb 2
869 \& AV * newAVhv( HV *ohv)
870 \& AV * Perl_newAVhv(pTHX_ HV *ohv)
871 .Ve
872 .RE
873 .RS 4
874 .RE
875 .ie n .IP """Nullav""" 4
876 .el .IP \f(CWNullav\fR 4
877 .IX Xref "Nullav"
878 .IX Item "Nullav"
879 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullav\*(C'\fR
880 from a future release of Perl. Do not use it for
881 new code; remove it from existing code.
882 .Sp
883 Null AV pointer.
884 .Sp
885 (deprecated \- use \f(CW\*(C`(AV *)NULL\*(C'\fR instead)
886 .SH "Callback Functions"
887 .IX Xref "G_METHOD G_METHOD_NAMED G_RETHROW G_USEHINTS SAVEf_KEEPOLDELEM SAVEf_SETMAGIC"
888 .IX Header "Callback Functions"
889 .ie n .IP """call_argv""" 4
890 .el .IP \f(CWcall_argv\fR 4
891 .IX Xref "call_argv"
892 .IX Item "call_argv"
893 Performs a callback to the specified named and package\-scoped Perl subroutine
894 with \f(CW\*(C`argv\*(C'\fR (a \f(CW\*(C`NULL\*(C'\fR\-terminated array of strings) as arguments. See
895 perlcall.
896 .Sp
897 Approximate Perl equivalent: \f(CW\*(C`&{"$sub_name"}(@$argv)\*(C'\fR.
898 .Sp
899 NOTE: the \f(CWperl_call_argv()\fR form is \fBdeprecated\fR.
900 .RS 4
901 .Sp
902 .Vb 4
903 \& SSize_t call_argv( const char *sub_name, I32 flags,
904 \& char **argv)
905 \& SSize_t Perl_call_argv(pTHX_ const char *sub_name, I32 flags,
906 \& char **argv)
907 .Ve
908 .RE
909 .RS 4
910 .RE
911 .ie n .IP """call_method""" 4
912 .el .IP \f(CWcall_method\fR 4
913 .IX Xref "call_method"
914 .IX Item "call_method"
915 Performs a callback to the specified Perl method. The blessed object must
916 be on the stack. See perlcall.
917 .Sp
918 NOTE: the \f(CWperl_call_method()\fR form is \fBdeprecated\fR.
919 .RS 4
920 .Sp
921 .Vb 2
922 \& SSize_t call_method( const char *methname, I32 flags)
923 \& SSize_t Perl_call_method(pTHX_ const char *methname, I32 flags)
924 .Ve
925 .RE
926 .RS 4
927 .RE
928 .ie n .IP """call_pv""" 4
929 .el .IP \f(CWcall_pv\fR 4
930 .IX Xref "call_pv"
931 .IX Item "call_pv"
932 Performs a callback to the specified Perl sub. See perlcall.
933 .Sp
934 NOTE: the \f(CWperl_call_pv()\fR form is \fBdeprecated\fR.
935 .RS 4
936 .Sp
937 .Vb 2
938 \& SSize_t call_pv( const char *sub_name, I32 flags)
939 \& SSize_t Perl_call_pv(pTHX_ const char *sub_name, I32 flags)
940 .Ve
941 .RE
942 .RS 4
943 .RE
944 .ie n .IP """call_sv""" 4
945 .el .IP \f(CWcall_sv\fR 4
946 .IX Xref "call_sv"
947 .IX Item "call_sv"
948 Performs a callback to the Perl sub specified by the SV.
949 .Sp
950 If neither the \f(CW\*(C`G_METHOD\*(C'\fR nor \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, the
951 SV may be any of a CV, a GV, a reference to a CV, a reference to a GV
952 or \f(CWSvPV(sv)\fR will be used as the name of the sub to call.
953 .Sp
954 If the \f(CW\*(C`G_METHOD\*(C'\fR flag is supplied, the SV may be a reference to a CV or
955 \&\f(CWSvPV(sv)\fR will be used as the name of the method to call.
956 .Sp
957 If the \f(CW\*(C`G_METHOD_NAMED\*(C'\fR flag is supplied, \f(CWSvPV(sv)\fR will be used as
958 the name of the method to call.
959 .Sp
960 Some other values are treated specially for internal use and should
961 not be depended on.
962 .Sp
963 See perlcall.
964 .Sp
965 NOTE: the \f(CWperl_call_sv()\fR form is \fBdeprecated\fR.
966 .RS 4
967 .Sp
968 .Vb 2
969 \& SSize_t call_sv( SV *sv, I32 flags)
970 \& SSize_t Perl_call_sv(pTHX_ SV *sv, I32 flags)
971 .Ve
972 .RE
973 .RS 4
974 .RE
975 .ie n .IP """DESTRUCTORFUNC_NOCONTEXT_t""" 4
976 .el .IP \f(CWDESTRUCTORFUNC_NOCONTEXT_t\fR 4
977 .IX Item "DESTRUCTORFUNC_NOCONTEXT_t"
978 .PD 0
979 .ie n .IP """DESTRUCTORFUNC_t""" 4
980 .el .IP \f(CWDESTRUCTORFUNC_t\fR 4
981 .IX Item "DESTRUCTORFUNC_t"
982 .PD
983 Described in perlguts.
984 .ie n .IP """ENTER""" 4
985 .el .IP \f(CWENTER\fR 4
986 .IX Xref "ENTER"
987 .IX Item "ENTER"
988 Opening bracket on a callback. See \f(CW"LEAVE"\fR and perlcall.
989 .RS 4
990 .Sp
991 .Vb 1
992 \& ENTER;
993 .Ve
994 .RE
995 .RS 4
996 .RE
997 .ie n .IP """ENTER_with_name""" 4
998 .el .IP \f(CWENTER_with_name\fR 4
999 .IX Xref "ENTER_with_name"
1000 .IX Item "ENTER_with_name"
1001 Same as \f(CW"ENTER"\fR, but when debugging is enabled it also associates the
1002 given literal string with the new scope.
1003 .RS 4
1004 .Sp
1005 .Vb 1
1006 \& ENTER_with_name("name");
1007 .Ve
1008 .RE
1009 .RS 4
1010 .RE
1011 .ie n .IP """eval_pv""" 4
1012 .el .IP \f(CWeval_pv\fR 4
1013 .IX Xref "eval_pv"
1014 .IX Item "eval_pv"
1015 Tells Perl to \f(CW\*(C`eval\*(C'\fR the given string in scalar context and return an SV* result.
1016 .Sp
1017 NOTE: the \f(CWperl_eval_pv()\fR form is \fBdeprecated\fR.
1018 .RS 4
1019 .Sp
1020 .Vb 2
1021 \& SV * eval_pv( const char *p, I32 croak_on_error)
1022 \& SV * Perl_eval_pv(pTHX_ const char *p, I32 croak_on_error)
1023 .Ve
1024 .RE
1025 .RS 4
1026 .RE
1027 .ie n .IP """eval_sv""" 4
1028 .el .IP \f(CWeval_sv\fR 4
1029 .IX Xref "eval_sv"
1030 .IX Item "eval_sv"
1031 Tells Perl to \f(CW\*(C`eval\*(C'\fR the string in the SV. It supports the same flags
1032 as \f(CW\*(C`call_sv\*(C'\fR, with the obvious exception of \f(CW\*(C`G_EVAL\*(C'\fR. See perlcall.
1033 .Sp
1034 The \f(CW\*(C`G_RETHROW\*(C'\fR flag can be used if you only need \fBeval_sv()\fR to
1035 execute code specified by a string, but not catch any errors.
1036 .Sp
1037 By default the code is compiled and executed with the default hints,
1038 such as strict and features. Set \f(CW\*(C`G_USEHINTS\*(C'\fR in flags to use the
1039 current hints from \f(CW\*(C`PL_curcop\*(C'\fR.
1040 .Sp
1041 NOTE: the \f(CWperl_eval_sv()\fR form is \fBdeprecated\fR.
1042 .RS 4
1043 .Sp
1044 .Vb 2
1045 \& SSize_t eval_sv( SV *sv, I32 flags)
1046 \& SSize_t Perl_eval_sv(pTHX_ SV *sv, I32 flags)
1047 .Ve
1048 .RE
1049 .RS 4
1050 .RE
1051 .ie n .IP """FREETMPS""" 4
1052 .el .IP \f(CWFREETMPS\fR 4
1053 .IX Xref "FREETMPS"
1054 .IX Item "FREETMPS"
1055 Closing bracket for temporaries on a callback. See \f(CW"SAVETMPS"\fR and
1056 perlcall.
1057 .RS 4
1058 .Sp
1059 .Vb 1
1060 \& FREETMPS;
1061 .Ve
1062 .RE
1063 .RS 4
1064 .RE
1065 .ie n .IP """G_DISCARD""" 4
1066 .el .IP \f(CWG_DISCARD\fR 4
1067 .IX Item "G_DISCARD"
1068 .PD 0
1069 .ie n .IP """G_EVAL""" 4
1070 .el .IP \f(CWG_EVAL\fR 4
1071 .IX Item "G_EVAL"
1072 .ie n .IP """G_KEEPERR""" 4
1073 .el .IP \f(CWG_KEEPERR\fR 4
1074 .IX Item "G_KEEPERR"
1075 .ie n .IP """G_LIST""" 4
1076 .el .IP \f(CWG_LIST\fR 4
1077 .IX Item "G_LIST"
1078 .ie n .IP """G_NOARGS""" 4
1079 .el .IP \f(CWG_NOARGS\fR 4
1080 .IX Item "G_NOARGS"
1081 .ie n .IP """G_SCALAR""" 4
1082 .el .IP \f(CWG_SCALAR\fR 4
1083 .IX Item "G_SCALAR"
1084 .ie n .IP """G_VOID""" 4
1085 .el .IP \f(CWG_VOID\fR 4
1086 .IX Item "G_VOID"
1087 .PD
1088 Described in perlcall.
1089 .ie n .IP """GIMME""" 4
1090 .el .IP \f(CWGIMME\fR 4
1091 .IX Xref "GIMME"
1092 .IX Item "GIMME"
1093 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`GIMME\*(C'\fR
1094 from a future release of Perl. Do not use it for
1095 new code; remove it from existing code.
1096 .Sp
1097 A backward\-compatible version of \f(CW\*(C`GIMME_V\*(C'\fR which can only return
1098 \&\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.
1099 Deprecated. Use \f(CW\*(C`GIMME_V\*(C'\fR instead.
1100 .RS 4
1101 .Sp
1102 .Vb 1
1103 \& U32 GIMME
1104 .Ve
1105 .RE
1106 .RS 4
1107 .RE
1108 .ie n .IP """GIMME_V""" 4
1109 .el .IP \f(CWGIMME_V\fR 4
1110 .IX Xref "GIMME_V"
1111 .IX Item "GIMME_V"
1112 The XSUB\-writer\*(Aqs equivalent to Perl\*(Aqs \f(CW\*(C`wantarray\*(C'\fR. Returns \f(CW\*(C`G_VOID\*(C'\fR,
1113 \&\f(CW\*(C`G_SCALAR\*(C'\fR or \f(CW\*(C`G_LIST\*(C'\fR for void, scalar or list context,
1114 respectively. See perlcall for a usage example.
1115 .RS 4
1116 .Sp
1117 .Vb 1
1118 \& U32 GIMME_V
1119 .Ve
1120 .RE
1121 .RS 4
1122 .RE
1123 .ie n .IP """is_lvalue_sub""" 4
1124 .el .IP \f(CWis_lvalue_sub\fR 4
1125 .IX Xref "is_lvalue_sub"
1126 .IX Item "is_lvalue_sub"
1127 Returns non\-zero if the sub calling this function is being called in an lvalue
1128 context. Returns 0 otherwise.
1129 .RS 4
1130 .Sp
1131 .Vb 2
1132 \& I32 is_lvalue_sub()
1133 \& I32 Perl_is_lvalue_sub(pTHX)
1134 .Ve
1135 .RE
1136 .RS 4
1137 .RE
1138 .ie n .IP """LEAVE""" 4
1139 .el .IP \f(CWLEAVE\fR 4
1140 .IX Xref "LEAVE"
1141 .IX Item "LEAVE"
1142 Closing bracket on a callback. See \f(CW"ENTER"\fR and perlcall.
1143 .RS 4
1144 .Sp
1145 .Vb 1
1146 \& LEAVE;
1147 .Ve
1148 .RE
1149 .RS 4
1150 .RE
1151 .ie n .IP """LEAVE_with_name""" 4
1152 .el .IP \f(CWLEAVE_with_name\fR 4
1153 .IX Xref "LEAVE_with_name"
1154 .IX Item "LEAVE_with_name"
1155 Same as \f(CW"LEAVE"\fR, but when debugging is enabled it first checks that the
1156 scope has the given name. \f(CW\*(C`name\*(C'\fR must be a literal string.
1157 .RS 4
1158 .Sp
1159 .Vb 1
1160 \& LEAVE_with_name("name");
1161 .Ve
1162 .RE
1163 .RS 4
1164 .RE
1165 .ie n .IP """mortal_destructor_sv""" 4
1166 .el .IP \f(CWmortal_destructor_sv\fR 4
1167 .IX Xref "mortal_destructor_sv"
1168 .IX Item "mortal_destructor_sv"
1169 This function arranges for either a Perl code reference, or a C function
1170 reference to be called at the \fBend of the current statement\fR.
1171 .Sp
1172 The \f(CW\*(C`coderef\*(C'\fR argument determines the type of function that will be
1173 called. If it is \f(CWSvROK()\fR it is assumed to be a reference to a CV and
1174 will arrange for the coderef to be called. If it is not \fBSvROK()\fR then it
1175 is assumed to be a \f(CWSvIV()\fR which is \f(CWSvIOK()\fR whose value is a pointer
1176 to a C function of type \f(CW\*(C`DESTRUCTORFUNC_t\*(C'\fR created using \f(CWPTR2INT()\fR.
1177 Either way the \f(CW\*(C`args\*(C'\fR parameter will be provided to the callback as a
1178 parameter, although the rules for doing so differ between the Perl and
1179 C mode. Normally this function is only used directly for the Perl case
1180 and the wrapper \f(CWmortal_destructor_x()\fR is used for the C function case.
1181 .Sp
1182 When operating in Perl callback mode the \f(CW\*(C`args\*(C'\fR parameter may be NULL
1183 in which case the code reference is called with no arguments, otherwise
1184 if it is an AV (SvTYPE(args) == SVt_PVAV) then the contents of the AV
1185 will be used as the arguments to the code reference, and if it is any
1186 other type then the \f(CW\*(C`args\*(C'\fR SV will be provided as a single argument to
1187 the code reference.
1188 .Sp
1189 When operating in a C callback mode the \f(CW\*(C`args\*(C'\fR parameter will be passed
1190 directly to the C function as a \f(CW\*(C`void *\*(C'\fR pointer. No additional
1191 processing of the argument will be performed, and it is the callers
1192 responsibility to free the \f(CW\*(C`args\*(C'\fR parameter if necessary.
1193 .Sp
1194 Be aware that there is a significant difference in timing between the
1195 \&\fIend of the current statement\fR and the \fIend of the current pseudo
1196 block\fR. If you are looking for a mechanism to trigger a function at the
1197 end of the \fBcurrent pseudo block\fR you should look at
1198 "\f(CW\*(C`SAVEDESTRUCTOR_X\*(C'\fR" in perlapi instead of this function.
1199 .RS 4
1200 .Sp
1201 .Vb 2
1202 \& void mortal_destructor_sv( SV *coderef, SV *args)
1203 \& void Perl_mortal_destructor_sv(pTHX_ SV *coderef, SV *args)
1204 .Ve
1205 .RE
1206 .RS 4
1207 .RE
1208 .ie n .IP """MORTALDESTRUCTOR_SV""" 4
1209 .el .IP \f(CWMORTALDESTRUCTOR_SV\fR 4
1210 .IX Item "MORTALDESTRUCTOR_SV"
1211 .PD 0
1212 .ie n .IP """MORTALSVFUNC_X""" 4
1213 .el .IP \f(CWMORTALSVFUNC_X\fR 4
1214 .IX Item "MORTALSVFUNC_X"
1215 .PD
1216 Described in perlguts.
1217 .RS 4
1218 .Sp
1219 .Vb 2
1220 \& MORTALDESTRUCTOR_SV(SV *coderef, SV *args)
1221 \& MORTALSVFUNC_X (SVFUNC_t f, SV *sv)
1222 .Ve
1223 .RE
1224 .RS 4
1225 .RE
1226 .ie n .IP """PL_errgv""" 4
1227 .el .IP \f(CWPL_errgv\fR 4
1228 .IX Item "PL_errgv"
1229 Described in perlcall.
1230 .ie n .IP """save_aelem""" 4
1231 .el .IP \f(CWsave_aelem\fR 4
1232 .IX Item "save_aelem"
1233 .PD 0
1234 .ie n .IP """save_aelem_flags""" 4
1235 .el .IP \f(CWsave_aelem_flags\fR 4
1236 .IX Xref "save_aelem save_aelem_flags"
1237 .IX Item "save_aelem_flags"
1238 .PD
1239 These each arrange for the value of the array element \f(CW\*(C`av[idx]\*(C'\fR to be restored
1240 at the end of the enclosing \fIpseudo\-block\fR.
1241 .Sp
1242 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
1243 scalar. That scalar will inherit any magic from the original \f(CW**sptr\fR,
1244 and any \*(Aqset\*(Aq magic will be processed.
1245 .Sp
1246 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
1247 the function to forgo all that: the scalar at \f(CW**sptr\fR is untouched.
1248 If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a
1249 new \f(CW\*(C`undef\*(C'\fR scalar. That scalar will inherit any magic from the original
1250 \&\f(CW**sptr\fR. Any \*(Aqset\*(Aq magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR
1251 is set in in \f(CW\*(C`flags\*(C'\fR.
1252 .RS 4
1253 .Sp
1254 .Vb 5
1255 \& void save_aelem ( AV *av, SSize_t idx, SV **sptr)
1256 \& void save_aelem_flags( AV *av, SSize_t idx, SV **sptr,
1257 \& const U32 flags)
1258 \& void Perl_save_aelem_flags(pTHX_ AV *av, SSize_t idx, SV **sptr,
1259 \& const U32 flags)
1260 .Ve
1261 .RE
1262 .RS 4
1263 .RE
1264 .ie n .IP """save_aptr""" 4
1265 .el .IP \f(CWsave_aptr\fR 4
1266 .IX Item "save_aptr"
1267 .PD 0
1268 .ie n .IP """save_ary""" 4
1269 .el .IP \f(CWsave_ary\fR 4
1270 .IX Item "save_ary"
1271 .ie n .IP """save_hash""" 4
1272 .el .IP \f(CWsave_hash\fR 4
1273 .IX Item "save_hash"
1274 .PD
1275 Described in perlguts.
1276 .RS 4
1277 .Sp
1278 .Vb 6
1279 \& void save_aptr( AV **aptr)
1280 \& void Perl_save_aptr(pTHX_ AV **aptr)
1281 \& AV * save_ary ( GV *gv)
1282 \& AV * Perl_save_ary (pTHX_ GV *gv)
1283 \& HV * save_hash( GV *gv)
1284 \& HV * Perl_save_hash(pTHX_ GV *gv)
1285 .Ve
1286 .RE
1287 .RS 4
1288 .RE
1289 .ie n .IP """save_helem""" 4
1290 .el .IP \f(CWsave_helem\fR 4
1291 .IX Item "save_helem"
1292 .PD 0
1293 .ie n .IP """save_helem_flags""" 4
1294 .el .IP \f(CWsave_helem_flags\fR 4
1295 .IX Xref "save_helem save_helem_flags"
1296 .IX Item "save_helem_flags"
1297 .PD
1298 These each arrange for the value of the hash element (in Perlish terms)
1299 \&\f(CW\*(C`$hv{key}]\*(C'\fR to be restored at the end of the enclosing \fIpseudo\-block\fR.
1300 .Sp
1301 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
1302 scalar. That scalar will inherit any magic from the original \f(CW**sptr\fR,
1303 and any \*(Aqset\*(Aq magic will be processed.
1304 .Sp
1305 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
1306 the function to forgo all that: the scalar at \f(CW**sptr\fR is untouched.
1307 If \f(CW\*(C`SAVEf_KEEPOLDELEM\*(C'\fR is not set, the SV at C**sptr> will be replaced by a
1308 new \f(CW\*(C`undef\*(C'\fR scalar. That scalar will inherit any magic from the original
1309 \&\f(CW**sptr\fR. Any \*(Aqset\*(Aq magic will be processed if and only if \f(CW\*(C`SAVEf_SETMAGIC\*(C'\fR
1310 is set in in \f(CW\*(C`flags\*(C'\fR.
1311 .RS 4
1312 .Sp
1313 .Vb 5
1314 \& void save_helem ( HV *hv, SV *key, SV **sptr)
1315 \& void save_helem_flags( HV *hv, SV *key, SV **sptr,
1316 \& const U32 flags)
1317 \& void Perl_save_helem_flags(pTHX_ HV *hv, SV *key, SV **sptr,
1318 \& const U32 flags)
1319 .Ve
1320 .RE
1321 .RS 4
1322 .RE
1323 .ie n .IP """save_hptr""" 4
1324 .el .IP \f(CWsave_hptr\fR 4
1325 .IX Item "save_hptr"
1326 .PD 0
1327 .ie n .IP """save_item""" 4
1328 .el .IP \f(CWsave_item\fR 4
1329 .IX Item "save_item"
1330 .ie n .IP """save_scalar""" 4
1331 .el .IP \f(CWsave_scalar\fR 4
1332 .IX Item "save_scalar"
1333 .ie n .IP """save_svref""" 4
1334 .el .IP \f(CWsave_svref\fR 4
1335 .IX Item "save_svref"
1336 .ie n .IP """SAVEBOOL""" 4
1337 .el .IP \f(CWSAVEBOOL\fR 4
1338 .IX Item "SAVEBOOL"
1339 .ie n .IP """SAVEDELETE""" 4
1340 .el .IP \f(CWSAVEDELETE\fR 4
1341 .IX Item "SAVEDELETE"
1342 .ie n .IP """SAVEDESTRUCTOR""" 4
1343 .el .IP \f(CWSAVEDESTRUCTOR\fR 4
1344 .IX Item "SAVEDESTRUCTOR"
1345 .ie n .IP """SAVEDESTRUCTOR_X""" 4
1346 .el .IP \f(CWSAVEDESTRUCTOR_X\fR 4
1347 .IX Item "SAVEDESTRUCTOR_X"
1348 .ie n .IP """SAVEFREEOP""" 4
1349 .el .IP \f(CWSAVEFREEOP\fR 4
1350 .IX Item "SAVEFREEOP"
1351 .ie n .IP """SAVEFREEPV""" 4
1352 .el .IP \f(CWSAVEFREEPV\fR 4
1353 .IX Item "SAVEFREEPV"
1354 .ie n .IP """SAVEFREERCPV""" 4
1355 .el .IP \f(CWSAVEFREERCPV\fR 4
1356 .IX Item "SAVEFREERCPV"
1357 .ie n .IP """SAVEFREESV""" 4
1358 .el .IP \f(CWSAVEFREESV\fR 4
1359 .IX Item "SAVEFREESV"
1360 .ie n .IP """SAVEGENERICSV""" 4
1361 .el .IP \f(CWSAVEGENERICSV\fR 4
1362 .IX Item "SAVEGENERICSV"
1363 .ie n .IP """SAVEINT""" 4
1364 .el .IP \f(CWSAVEINT\fR 4
1365 .IX Item "SAVEINT"
1366 .ie n .IP """SAVEIV""" 4
1367 .el .IP \f(CWSAVEIV\fR 4
1368 .IX Item "SAVEIV"
1369 .ie n .IP """SAVEI8""" 4
1370 .el .IP \f(CWSAVEI8\fR 4
1371 .IX Item "SAVEI8"
1372 .ie n .IP """SAVEI16""" 4
1373 .el .IP \f(CWSAVEI16\fR 4
1374 .IX Item "SAVEI16"
1375 .ie n .IP """SAVEI32""" 4
1376 .el .IP \f(CWSAVEI32\fR 4
1377 .IX Item "SAVEI32"
1378 .ie n .IP """SAVEMORTALIZESV""" 4
1379 .el .IP \f(CWSAVEMORTALIZESV\fR 4
1380 .IX Item "SAVEMORTALIZESV"
1381 .ie n .IP """SAVEPPTR""" 4
1382 .el .IP \f(CWSAVEPPTR\fR 4
1383 .IX Item "SAVEPPTR"
1384 .ie n .IP """SAVERCPV""" 4
1385 .el .IP \f(CWSAVERCPV\fR 4
1386 .IX Item "SAVERCPV"
1387 .ie n .IP """SAVESPTR""" 4
1388 .el .IP \f(CWSAVESPTR\fR 4
1389 .IX Item "SAVESPTR"
1390 .ie n .IP """SAVESTACK_POS""" 4
1391 .el .IP \f(CWSAVESTACK_POS\fR 4
1392 .IX Item "SAVESTACK_POS"
1393 .ie n .IP """SAVESTRLEN""" 4
1394 .el .IP \f(CWSAVESTRLEN\fR 4
1395 .IX Item "SAVESTRLEN"
1396 .PD
1397 Described in perlguts.
1398 .RS 4
1399 .Sp
1400 .Vb 10
1401 \& void save_hptr ( HV **hptr)
1402 \& void Perl_save_hptr (pTHX_ HV **hptr)
1403 \& void save_item ( SV *item)
1404 \& void Perl_save_item (pTHX_ SV *item)
1405 \& SV * save_scalar ( GV *gv)
1406 \& SV * Perl_save_scalar (pTHX_ GV *gv)
1407 \& SV * save_svref ( SV **sptr)
1408 \& SV * Perl_save_svref (pTHX_ SV **sptr)
1409 \& SAVEBOOL ( bool i)
1410 \& SAVEDELETE ( HV * hv, char * key,
1411 \& I32 length)
1412 \& SAVEDESTRUCTOR ( DESTRUCTORFUNC_NOCONTEXT_t f,
1413 \& void *p)
1414 \& SAVEDESTRUCTOR_X( DESTRUCTORFUNC_t f, void *p)
1415 \& SAVEFREEOP ( OP *op)
1416 \& SAVEFREEPV ( char *pv)
1417 \& SAVEFREERCPV ( char *pv)
1418 \& SAVEFREESV ( SV* sv)
1419 \& SAVEGENERICSV ( char **psv)
1420 \& SAVEINT ( int i)
1421 \& SAVEIV ( IV i)
1422 \& SAVEI8 ( I8 i)
1423 \& SAVEI16 ( I16 i)
1424 \& SAVEI32 ( I32 i)
1425 \& SAVEMORTALIZESV ( SV* sv)
1426 \& SAVEPPTR ( char * p)
1427 \& SAVERCPV ( char *pv)
1428 \& SAVESPTR ( SV * s)
1429 \& SAVESTACK_POS ()
1430 \& SAVESTRLEN ( STRLEN i)
1431 .Ve
1432 .RE
1433 .RS 4
1434 .RE
1435 .ie n .IP """SAVETMPS""" 4
1436 .el .IP \f(CWSAVETMPS\fR 4
1437 .IX Xref "SAVETMPS"
1438 .IX Item "SAVETMPS"
1439 Opening bracket for temporaries on a callback. See \f(CW"FREETMPS"\fR and
1440 perlcall.
1441 .RS 4
1442 .Sp
1443 .Vb 1
1444 \& SAVETMPS;
1445 .Ve
1446 .RE
1447 .RS 4
1448 .RE
1449 .SH Casting
1450 .IX Header "Casting"
1451 .ie n .IP """cBOOL""" 4
1452 .el .IP \f(CWcBOOL\fR 4
1453 .IX Xref "cBOOL"
1454 .IX Item "cBOOL"
1455 Cast\-to\-bool. When Perl was able to be compiled on pre\-C99 compilers, a
1456 \&\f(CW\*(C`(bool)\*(C'\fR cast didn\*(Aqt necessarily do the right thing, so this macro was
1457 created (and made somewhat complicated to work around bugs in old
1458 compilers). Now, many years later, and C99 is used, this is no longer
1459 required, but is kept for backwards compatibility.
1460 .RS 4
1461 .Sp
1462 .Vb 1
1463 \& bool cBOOL(bool expr)
1464 .Ve
1465 .RE
1466 .RS 4
1467 .RE
1468 .ie n .IP """I_V""" 4
1469 .el .IP \f(CWI_V\fR 4
1470 .IX Xref "I_V"
1471 .IX Item "I_V"
1472 Cast an NV to IV while avoiding undefined C behavior
1473 .RS 4
1474 .Sp
1475 .Vb 1
1476 \& IV I_V(NV what)
1477 .Ve
1478 .RE
1479 .RS 4
1480 .RE
1481 .ie n .IP """I_32""" 4
1482 .el .IP \f(CWI_32\fR 4
1483 .IX Xref "I_32"
1484 .IX Item "I_32"
1485 Cast an NV to I32 while avoiding undefined C behavior
1486 .RS 4
1487 .Sp
1488 .Vb 1
1489 \& I32 I_32(NV what)
1490 .Ve
1491 .RE
1492 .RS 4
1493 .RE
1494 .ie n .IP """INT2PTR""" 4
1495 .el .IP \f(CWINT2PTR\fR 4
1496 .IX Item "INT2PTR"
1497 .PD 0
1498 .ie n .IP """PTRV""" 4
1499 .el .IP \f(CWPTRV\fR 4
1500 .IX Item "PTRV"
1501 .ie n .IP """PTR2IV""" 4
1502 .el .IP \f(CWPTR2IV\fR 4
1503 .IX Item "PTR2IV"
1504 .ie n .IP """PTR2nat""" 4
1505 .el .IP \f(CWPTR2nat\fR 4
1506 .IX Item "PTR2nat"
1507 .ie n .IP """PTR2NV""" 4
1508 .el .IP \f(CWPTR2NV\fR 4
1509 .IX Item "PTR2NV"
1510 .ie n .IP """PTR2ul""" 4
1511 .el .IP \f(CWPTR2ul\fR 4
1512 .IX Item "PTR2ul"
1513 .ie n .IP """PTR2UV""" 4
1514 .el .IP \f(CWPTR2UV\fR 4
1515 .IX Item "PTR2UV"
1516 .PD
1517 Described in perlguts.
1518 .RS 4
1519 .Sp
1520 .Vb 6
1521 \& type INT2PTR(type, int value)
1522 \& IV PTR2IV (void * ptr)
1523 \& IV PTR2nat(void *)
1524 \& NV PTR2NV (void * ptr)
1525 \& unsigned long PTR2ul (void *)
1526 \& UV PTR2UV (void * ptr)
1527 .Ve
1528 .RE
1529 .RS 4
1530 .RE
1531 .ie n .IP """U_V""" 4
1532 .el .IP \f(CWU_V\fR 4
1533 .IX Xref "U_V"
1534 .IX Item "U_V"
1535 Cast an NV to UV while avoiding undefined C behavior
1536 .RS 4
1537 .Sp
1538 .Vb 1
1539 \& UV U_V(NV what)
1540 .Ve
1541 .RE
1542 .RS 4
1543 .RE
1544 .ie n .IP """U_32""" 4
1545 .el .IP \f(CWU_32\fR 4
1546 .IX Xref "U_32"
1547 .IX Item "U_32"
1548 Cast an NV to U32 while avoiding undefined C behavior
1549 .RS 4
1550 .Sp
1551 .Vb 1
1552 \& U32 U_32(NV what)
1553 .Ve
1554 .RE
1555 .RS 4
1556 .RE
1557 .SH "Character case changing"
1558 .IX Header "Character case changing"
1559 Perl uses "full" Unicode case mappings. This means that converting a single
1560 character to another case may result in a sequence of more than one character.
1561 For example, the uppercase of \f(CW\*(C`ß\*(C'\fR (LATIN SMALL LETTER SHARP S) is the two
1562 character sequence \f(CW\*(C`SS\*(C'\fR. This presents some complications The lowercase of
1563 all characters in the range 0..255 is a single character, and thus
1564 \&\f(CW"toLOWER_L1"\fR is furnished. But, \f(CW\*(C`toUPPER_L1\*(C'\fR can\*(Aqt exist, as it couldn\*(Aqt
1565 return a valid result for all legal inputs. Instead \f(CW"toUPPER_uvchr"\fR has
1566 an API that does allow every possible legal result to be returned.) Likewise
1567 no other function that is crippled by not being able to give the correct
1568 results for the full range of possible inputs has been implemented here.
1569 .ie n .IP """toFOLD""" 4
1570 .el .IP \f(CWtoFOLD\fR 4
1571 .IX Item "toFOLD"
1572 .PD 0
1573 .ie n .IP """toFOLD_A""" 4
1574 .el .IP \f(CWtoFOLD_A\fR 4
1575 .IX Item "toFOLD_A"
1576 .ie n .IP """toFOLD_utf8""" 4
1577 .el .IP \f(CWtoFOLD_utf8\fR 4
1578 .IX Item "toFOLD_utf8"
1579 .ie n .IP """toFOLD_utf8_safe""" 4
1580 .el .IP \f(CWtoFOLD_utf8_safe\fR 4
1581 .IX Item "toFOLD_utf8_safe"
1582 .ie n .IP """toFOLD_uvchr""" 4
1583 .el .IP \f(CWtoFOLD_uvchr\fR 4
1584 .IX Xref "toFOLD toFOLD_A toFOLD_utf8 toFOLD_utf8_safe toFOLD_uvchr"
1585 .IX Item "toFOLD_uvchr"
1586 .PD
1587 These all return the foldcase of a character. "foldcase" is an internal case
1588 for \f(CW\*(C`/i\*(C'\fR pattern matching. If the foldcase of character A and the foldcase of
1589 character B are the same, they match caselessly; otherwise they don\*(Aqt.
1590 .Sp
1591 The differences in the forms are what domain they operate on, and whether the
1592 input is specified as a code point (those forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a
1593 UTF\-8 string (the others). In the latter case, the code point to use is the
1594 first one in the buffer of UTF\-8 encoded code points, delineated by the
1595 arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
1596 .Sp
1597 \&\f(CW\*(C`toFOLD\*(C'\fR and \f(CW\*(C`toFOLD_A\*(C'\fR are synonyms of each other. They return the
1598 foldcase of any ASCII\-range code point. In this range, the foldcase is
1599 identical to the lowercase. All other inputs are returned unchanged. Since
1600 these are macros, the input type may be any integral one, and the output will
1601 occupy the same number of bits as the input.
1602 .Sp
1603 There is no \f(CW\*(C`toFOLD_L1\*(C'\fR nor \f(CW\*(C`toFOLD_LATIN1\*(C'\fR as the foldcase of some code
1604 points in the 0..255 range is above that range or consists of multiple
1605 characters. Instead use \f(CW\*(C`toFOLD_uvchr\*(C'\fR.
1606 .Sp
1607 \&\f(CW\*(C`toFOLD_uvchr\*(C'\fR returns the foldcase of any Unicode code point. The return
1608 value is identical to that of \f(CW\*(C`toFOLD_A\*(C'\fR for input code points in the ASCII
1609 range. The foldcase of the vast majority of Unicode code points is the same
1610 as the code point itself. For these, and for code points above the legal
1611 Unicode maximum, this returns the input code point unchanged. It additionally
1612 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
1613 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
1614 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
1615 .Sp
1616 NOTE: the foldcase of a code point may be more than one code point. The
1617 return value of this function is only the first of these. The entire foldcase
1618 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
1619 point, you can do something like this:
1620 .Sp
1621 .Vb 3
1622 \& uc = toFOLD_uvchr(cp, s, &len);
1623 \& if (len > UTF8SKIP(s)) { is multiple code points }
1624 \& else { is a single code point }
1625 .Ve
1626 .Sp
1627 \&\f(CW\*(C`toFOLD_utf8\*(C'\fR and \f(CW\*(C`toFOLD_utf8_safe\*(C'\fR are synonyms of each other. The only
1628 difference between these and \f(CW\*(C`toFOLD_uvchr\*(C'\fR is that the source for these is
1629 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
1630 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
1631 buffer may certainly contain more than one code point; but only the first one
1632 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
1633 malformed in some way, the program may croak, or the function may return the
1634 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
1635 change in future releases.
1636 .RS 4
1637 .Sp
1638 .Vb 5
1639 \& UV toFOLD (UV cp)
1640 \& UV toFOLD_A (UV cp)
1641 \& UV toFOLD_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1642 \& UV toFOLD_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1643 \& UV toFOLD_uvchr (UV cp, U8* s, STRLEN* lenp)
1644 .Ve
1645 .RE
1646 .RS 4
1647 .RE
1648 .ie n .IP """toLOWER""" 4
1649 .el .IP \f(CWtoLOWER\fR 4
1650 .IX Item "toLOWER"
1651 .PD 0
1652 .ie n .IP """toLOWER_A""" 4
1653 .el .IP \f(CWtoLOWER_A\fR 4
1654 .IX Item "toLOWER_A"
1655 .ie n .IP """toLOWER_LATIN1""" 4
1656 .el .IP \f(CWtoLOWER_LATIN1\fR 4
1657 .IX Item "toLOWER_LATIN1"
1658 .ie n .IP """toLOWER_LC""" 4
1659 .el .IP \f(CWtoLOWER_LC\fR 4
1660 .IX Item "toLOWER_LC"
1661 .ie n .IP """toLOWER_L1""" 4
1662 .el .IP \f(CWtoLOWER_L1\fR 4
1663 .IX Item "toLOWER_L1"
1664 .ie n .IP """toLOWER_utf8""" 4
1665 .el .IP \f(CWtoLOWER_utf8\fR 4
1666 .IX Item "toLOWER_utf8"
1667 .ie n .IP """toLOWER_utf8_safe""" 4
1668 .el .IP \f(CWtoLOWER_utf8_safe\fR 4
1669 .IX Item "toLOWER_utf8_safe"
1670 .ie n .IP """toLOWER_uvchr""" 4
1671 .el .IP \f(CWtoLOWER_uvchr\fR 4
1672 .IX Xref "toLOWER toLOWER_A toLOWER_LATIN1 toLOWER_LC toLOWER_L1 toLOWER_utf8 toLOWER_utf8_safe toLOWER_uvchr"
1673 .IX Item "toLOWER_uvchr"
1674 .PD
1675 These all return the lowercase of a character. The differences are what domain
1676 they operate on, and whether the input is specified as a code point (those
1677 forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter
1678 case, the code point to use is the first one in the buffer of UTF\-8 encoded
1679 code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
1680 .Sp
1681 \&\f(CW\*(C`toLOWER\*(C'\fR and \f(CW\*(C`toLOWER_A\*(C'\fR are synonyms of each other. They return the
1682 lowercase of any uppercase ASCII\-range code point. All other inputs are
1683 returned unchanged. Since these are macros, the input type may be any integral
1684 one, and the output will occupy the same number of bits as the input.
1685 .Sp
1686 \&\f(CW\*(C`toLOWER_L1\*(C'\fR and \f(CW\*(C`toLOWER_LATIN1\*(C'\fR are synonyms of each other. They behave
1687 identically as \f(CW\*(C`toLOWER\*(C'\fR for ASCII\-range input. But additionally will return
1688 the lowercase of any uppercase code point in the entire 0..255 range, assuming
1689 a Latin\-1 encoding (or the EBCDIC equivalent on such platforms).
1690 .Sp
1691 \&\f(CW\*(C`toLOWER_LC\*(C'\fR returns the lowercase of the input code point according to the
1692 rules of the current POSIX locale. Input code points outside the range 0..255
1693 are returned unchanged.
1694 .Sp
1695 \&\f(CW\*(C`toLOWER_uvchr\*(C'\fR returns the lowercase of any Unicode code point. The return
1696 value is identical to that of \f(CW\*(C`toLOWER_L1\*(C'\fR for input code points in the 0..255
1697 range. The lowercase of the vast majority of Unicode code points is the same
1698 as the code point itself. For these, and for code points above the legal
1699 Unicode maximum, this returns the input code point unchanged. It additionally
1700 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
1701 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
1702 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
1703 .Sp
1704 NOTE: the lowercase of a code point may be more than one code point. The
1705 return value of this function is only the first of these. The entire lowercase
1706 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
1707 point, you can do something like this:
1708 .Sp
1709 .Vb 3
1710 \& uc = toLOWER_uvchr(cp, s, &len);
1711 \& if (len > UTF8SKIP(s)) { is multiple code points }
1712 \& else { is a single code point }
1713 .Ve
1714 .Sp
1715 \&\f(CW\*(C`toLOWER_utf8\*(C'\fR and \f(CW\*(C`toLOWER_utf8_safe\*(C'\fR are synonyms of each other. The only
1716 difference between these and \f(CW\*(C`toLOWER_uvchr\*(C'\fR is that the source for these is
1717 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
1718 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
1719 buffer may certainly contain more than one code point; but only the first one
1720 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
1721 malformed in some way, the program may croak, or the function may return the
1722 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
1723 change in future releases.
1724 .RS 4
1725 .Sp
1726 .Vb 8
1727 \& UV toLOWER (UV cp)
1728 \& UV toLOWER_A (UV cp)
1729 \& UV toLOWER_LATIN1 (UV cp)
1730 \& UV toLOWER_LC (UV cp)
1731 \& UV toLOWER_L1 (UV cp)
1732 \& UV toLOWER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1733 \& UV toLOWER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1734 \& UV toLOWER_uvchr (UV cp, U8* s, STRLEN* lenp)
1735 .Ve
1736 .RE
1737 .RS 4
1738 .RE
1739 .ie n .IP """toTITLE""" 4
1740 .el .IP \f(CWtoTITLE\fR 4
1741 .IX Item "toTITLE"
1742 .PD 0
1743 .ie n .IP """toTITLE_A""" 4
1744 .el .IP \f(CWtoTITLE_A\fR 4
1745 .IX Item "toTITLE_A"
1746 .ie n .IP """toTITLE_utf8""" 4
1747 .el .IP \f(CWtoTITLE_utf8\fR 4
1748 .IX Item "toTITLE_utf8"
1749 .ie n .IP """toTITLE_utf8_safe""" 4
1750 .el .IP \f(CWtoTITLE_utf8_safe\fR 4
1751 .IX Item "toTITLE_utf8_safe"
1752 .ie n .IP """toTITLE_uvchr""" 4
1753 .el .IP \f(CWtoTITLE_uvchr\fR 4
1754 .IX Xref "toTITLE toTITLE_A toTITLE_utf8 toTITLE_utf8_safe toTITLE_uvchr"
1755 .IX Item "toTITLE_uvchr"
1756 .PD
1757 These all return the titlecase of a character. The differences are what domain
1758 they operate on, and whether the input is specified as a code point (those
1759 forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter
1760 case, the code point to use is the first one in the buffer of UTF\-8 encoded
1761 code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
1762 .Sp
1763 \&\f(CW\*(C`toTITLE\*(C'\fR and \f(CW\*(C`toTITLE_A\*(C'\fR are synonyms of each other. They return the
1764 titlecase of any lowercase ASCII\-range code point. In this range, the
1765 titlecase is identical to the uppercase. All other inputs are returned
1766 unchanged. Since these are macros, the input type may be any integral one, and
1767 the output will occupy the same number of bits as the input.
1768 .Sp
1769 There is no \f(CW\*(C`toTITLE_L1\*(C'\fR nor \f(CW\*(C`toTITLE_LATIN1\*(C'\fR as the titlecase of some code
1770 points in the 0..255 range is above that range or consists of multiple
1771 characters. Instead use \f(CW\*(C`toTITLE_uvchr\*(C'\fR.
1772 .Sp
1773 \&\f(CW\*(C`toTITLE_uvchr\*(C'\fR returns the titlecase of any Unicode code point. The return
1774 value is identical to that of \f(CW\*(C`toTITLE_A\*(C'\fR for input code points in the ASCII
1775 range. The titlecase of the vast majority of Unicode code points is the same
1776 as the code point itself. For these, and for code points above the legal
1777 Unicode maximum, this returns the input code point unchanged. It additionally
1778 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
1779 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
1780 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
1781 .Sp
1782 NOTE: the titlecase of a code point may be more than one code point. The
1783 return value of this function is only the first of these. The entire titlecase
1784 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
1785 point, you can do something like this:
1786 .Sp
1787 .Vb 3
1788 \& uc = toTITLE_uvchr(cp, s, &len);
1789 \& if (len > UTF8SKIP(s)) { is multiple code points }
1790 \& else { is a single code point }
1791 .Ve
1792 .Sp
1793 \&\f(CW\*(C`toTITLE_utf8\*(C'\fR and \f(CW\*(C`toTITLE_utf8_safe\*(C'\fR are synonyms of each other. The only
1794 difference between these and \f(CW\*(C`toTITLE_uvchr\*(C'\fR is that the source for these is
1795 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
1796 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
1797 buffer may certainly contain more than one code point; but only the first one
1798 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
1799 malformed in some way, the program may croak, or the function may return the
1800 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
1801 change in future releases.
1802 .RS 4
1803 .Sp
1804 .Vb 5
1805 \& UV toTITLE (UV cp)
1806 \& UV toTITLE_A (UV cp)
1807 \& UV toTITLE_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1808 \& UV toTITLE_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1809 \& UV toTITLE_uvchr (UV cp, U8* s, STRLEN* lenp)
1810 .Ve
1811 .RE
1812 .RS 4
1813 .RE
1814 .ie n .IP """toUPPER""" 4
1815 .el .IP \f(CWtoUPPER\fR 4
1816 .IX Item "toUPPER"
1817 .PD 0
1818 .ie n .IP """toUPPER_A""" 4
1819 .el .IP \f(CWtoUPPER_A\fR 4
1820 .IX Item "toUPPER_A"
1821 .ie n .IP """toUPPER_utf8""" 4
1822 .el .IP \f(CWtoUPPER_utf8\fR 4
1823 .IX Item "toUPPER_utf8"
1824 .ie n .IP """toUPPER_utf8_safe""" 4
1825 .el .IP \f(CWtoUPPER_utf8_safe\fR 4
1826 .IX Item "toUPPER_utf8_safe"
1827 .ie n .IP """toUPPER_uvchr""" 4
1828 .el .IP \f(CWtoUPPER_uvchr\fR 4
1829 .IX Xref "toUPPER toUPPER_A toUPPER_utf8 toUPPER_utf8_safe toUPPER_uvchr"
1830 .IX Item "toUPPER_uvchr"
1831 .PD
1832 These all return the uppercase of a character. The differences are what domain
1833 they operate on, and whether the input is specified as a code point (those
1834 forms with a \f(CW\*(C`cp\*(C'\fR parameter) or as a UTF\-8 string (the others). In the latter
1835 case, the code point to use is the first one in the buffer of UTF\-8 encoded
1836 code points, delineated by the arguments \f(CW\*(C`p\ ..\ e\ \-\ 1\*(C'\fR.
1837 .Sp
1838 \&\f(CW\*(C`toUPPER\*(C'\fR and \f(CW\*(C`toUPPER_A\*(C'\fR are synonyms of each other. They return the
1839 uppercase of any lowercase ASCII\-range code point. All other inputs are
1840 returned unchanged. Since these are macros, the input type may be any integral
1841 one, and the output will occupy the same number of bits as the input.
1842 .Sp
1843 There is no \f(CW\*(C`toUPPER_L1\*(C'\fR nor \f(CW\*(C`toUPPER_LATIN1\*(C'\fR as the uppercase of some code
1844 points in the 0..255 range is above that range or consists of multiple
1845 characters. Instead use \f(CW\*(C`toUPPER_uvchr\*(C'\fR.
1846 .Sp
1847 \&\f(CW\*(C`toUPPER_uvchr\*(C'\fR returns the uppercase of any Unicode code point. The return
1848 value is identical to that of \f(CW\*(C`toUPPER_A\*(C'\fR for input code points in the ASCII
1849 range. The uppercase of the vast majority of Unicode code points is the same
1850 as the code point itself. For these, and for code points above the legal
1851 Unicode maximum, this returns the input code point unchanged. It additionally
1852 stores the UTF\-8 of the result into the buffer beginning at \f(CW\*(C`s\*(C'\fR, and its
1853 length in bytes into \f(CW*lenp\fR. The caller must have made \f(CW\*(C`s\*(C'\fR large enough to
1854 contain at least \f(CW\*(C`UTF8_MAXBYTES_CASE+1\*(C'\fR bytes to avoid possible overflow.
1855 .Sp
1856 NOTE: the uppercase of a code point may be more than one code point. The
1857 return value of this function is only the first of these. The entire uppercase
1858 is returned in \f(CW\*(C`s\*(C'\fR. To determine if the result is more than a single code
1859 point, you can do something like this:
1860 .Sp
1861 .Vb 3
1862 \& uc = toUPPER_uvchr(cp, s, &len);
1863 \& if (len > UTF8SKIP(s)) { is multiple code points }
1864 \& else { is a single code point }
1865 .Ve
1866 .Sp
1867 \&\f(CW\*(C`toUPPER_utf8\*(C'\fR and \f(CW\*(C`toUPPER_utf8_safe\*(C'\fR are synonyms of each other. The only
1868 difference between these and \f(CW\*(C`toUPPER_uvchr\*(C'\fR is that the source for these is
1869 encoded in UTF\-8, instead of being a code point. It is passed as a buffer
1870 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
1871 buffer may certainly contain more than one code point; but only the first one
1872 (up through \f(CW\*(C`e\ \-\ 1\*(C'\fR) is examined. If the UTF\-8 for the input character is
1873 malformed in some way, the program may croak, or the function may return the
1874 REPLACEMENT CHARACTER, at the discretion of the implementation, and subject to
1875 change in future releases.
1876 .RS 4
1877 .Sp
1878 .Vb 5
1879 \& UV toUPPER (UV cp)
1880 \& UV toUPPER_A (UV cp)
1881 \& UV toUPPER_utf8 (U8* p, U8* e, U8* s, STRLEN* lenp)
1882 \& UV toUPPER_utf8_safe(U8* p, U8* e, U8* s, STRLEN* lenp)
1883 \& UV toUPPER_uvchr (UV cp, U8* s, STRLEN* lenp)
1884 .Ve
1885 .RE
1886 .RS 4
1887 .RE
1888 .SH "Character classification"
1889 .IX Header "Character classification"
1890 This section is about functions (really macros) that classify characters
1891 into types, such as punctuation versus alphabetic, etc. Most of these are
1892 analogous to regular expression character classes. (See
1893 "POSIX Character Classes" in perlrecharclass.) There are several variants for
1894 each class. (Not all macros have all variants; each item below lists the
1895 ones valid for it.) None are affected by \f(CW\*(C`use bytes\*(C'\fR, and only the ones
1896 with \f(CW\*(C`LC\*(C'\fR in the name are affected by the current locale.
1897 .PP
1898 The base function, e.g., \f(CWisALPHA()\fR, takes any signed or unsigned value,
1899 treating it as a code point, and returns a boolean as to whether or not the
1900 character represented by it is (or on non\-ASCII platforms, corresponds to) an
1901 ASCII character in the named class based on platform, Unicode, and Perl rules.
1902 If the input is a number that doesn\*(Aqt fit in an octet, FALSE is returned.
1903 .PP
1904 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
1905 with no suffix \f(CW"_A"\fR. This variant is used to emphasize by its name that
1906 only ASCII\-range characters can return TRUE.
1907 .PP
1908 Variant \f(CW\*(C`is\fR\f(CIFOO\fR\f(CW_L1\*(C'\fR imposes the Latin\-1 (or EBCDIC equivalent) character set
1909 onto the platform. That is, the code points that are ASCII are unaffected,
1910 since ASCII is a subset of Latin\-1. But the non\-ASCII code points are treated
1911 as if they are Latin\-1 characters. For example, \f(CWisWORDCHAR_L1()\fR will return
1912 true when called with the code point 0xDF, which is a word character in both
1913 ASCII and EBCDIC (though it represents different characters in each).
1914 If the input is a number that doesn\*(Aqt fit in an octet, FALSE is returned.
1915 (Perl\*(Aqs documentation uses a colloquial definition of Latin\-1, to include all
1916 code points below 256.)
1917 .PP
1918 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
1919 inputs below 256, but if the code point is larger than 255, Unicode rules are
1920 used to determine if it is in the character class. For example,
1921 \&\f(CWisWORDCHAR_uvchr(0x100)\fR returns TRUE, since 0x100 is LATIN CAPITAL LETTER A
1922 WITH MACRON in Unicode, and is a word character.
1923 .PP
1924 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,
1925 but are used for UTF\-8 encoded strings. The two forms are different names for
1926 the same thing. Each call to one of these classifies the first character of
1927 the string starting at \f(CW\*(C`p\*(C'\fR. The second parameter, \f(CW\*(C`e\*(C'\fR, points to anywhere in
1928 the string beyond the first character, up to one byte past the end of the
1929 entire string. Although both variants are identical, the suffix \f(CW\*(C`_safe\*(C'\fR in
1930 one name emphasizes that it will not attempt to read beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR,
1931 provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this is asserted for in
1932 \&\f(CW\*(C`\-DDEBUGGING\*(C'\fR builds). If the UTF\-8 for the input character is malformed in
1933 some way, the program may croak, or the function may return FALSE, at the
1934 discretion of the implementation, and subject to change in future releases.
1935 .PP
1936 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,
1937 but the result is based on the current locale, which is what \f(CW\*(C`LC\*(C'\fR in the name
1938 stands for. If Perl can determine that the current locale is a UTF\-8 locale,
1939 it uses the published Unicode rules; otherwise, it uses the C library function
1940 that gives the named classification. For example, \f(CWisDIGIT_LC()\fR when not in
1941 a UTF\-8 locale returns the result of calling \f(CWisdigit()\fR. FALSE is always
1942 returned if the input won\*(Aqt fit into an octet. On some platforms where the C
1943 library function is known to be defective, Perl changes its result to follow
1944 the POSIX standard\*(Aqs rules.
1945 .PP
1946 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
1947 than 256, but for larger ones it returns the Unicode classification of the code
1948 point.
1949 .PP
1950 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
1951 \&\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
1952 are different names for the same thing. Each call to one of these classifies
1953 the first character of the string starting at \f(CW\*(C`p\*(C'\fR. The second parameter,
1954 \&\f(CW\*(C`e\*(C'\fR, points to anywhere in the string beyond the first character, up to one
1955 byte past the end of the entire string. Although both variants are identical,
1956 the suffix \f(CW\*(C`_safe\*(C'\fR in one name emphasizes that it will not attempt to read
1957 beyond \f(CW\*(C`e\ \-\ 1\*(C'\fR, provided that the constraint \f(CW\*(C`s\ <\ e\*(C'\fR is true (this
1958 is asserted for in \f(CW\*(C`\-DDEBUGGING\*(C'\fR builds). If the UTF\-8 for the input
1959 character is malformed in some way, the program may croak, or the function may
1960 return FALSE, at the discretion of the implementation, and subject to change in
1961 future releases.
1962 .ie n .IP """isALNUM""" 4
1963 .el .IP \f(CWisALNUM\fR 4
1964 .IX Item "isALNUM"
1965 .PD 0
1966 .ie n .IP """isALNUM_A""" 4
1967 .el .IP \f(CWisALNUM_A\fR 4
1968 .IX Item "isALNUM_A"
1969 .ie n .IP """isALNUM_LC""" 4
1970 .el .IP \f(CWisALNUM_LC\fR 4
1971 .IX Item "isALNUM_LC"
1972 .ie n .IP """isALNUM_LC_uvchr""" 4
1973 .el .IP \f(CWisALNUM_LC_uvchr\fR 4
1974 .IX Xref "isALNUM isALNUM_A isALNUM_LC isALNUM_LC_uvchr"
1975 .IX Item "isALNUM_LC_uvchr"
1976 .PD
1977 These are each a synonym for their respectively named "\f(CW\*(C`isWORDCHAR\*(C'\fR"
1978 variant.
1979 .Sp
1980 They are provided for backward compatibility, even though a word character
1981 includes more than the standard C language meaning of alphanumeric.
1982 To get the C language definition, use the corresponding "\f(CW\*(C`isALPHANUMERIC\*(C'\fR"
1983 variant.
1984 .RS 4
1985 .Sp
1986 .Vb 4
1987 \& bool isALNUM (UV ch)
1988 \& bool isALNUM_A (UV ch)
1989 \& bool isALNUM_LC (UV ch)
1990 \& bool isALNUM_LC_uvchr(UV ch)
1991 .Ve
1992 .RE
1993 .RS 4
1994 .RE
1995 .ie n .IP """isALNUMC""" 4
1996 .el .IP \f(CWisALNUMC\fR 4
1997 .IX Item "isALNUMC"
1998 .PD 0
1999 .ie n .IP """isALNUMC_A""" 4
2000 .el .IP \f(CWisALNUMC_A\fR 4
2001 .IX Item "isALNUMC_A"
2002 .ie n .IP """isALNUMC_LC""" 4
2003 .el .IP \f(CWisALNUMC_LC\fR 4
2004 .IX Item "isALNUMC_LC"
2005 .ie n .IP """isALNUMC_LC_uvchr""" 4
2006 .el .IP \f(CWisALNUMC_LC_uvchr\fR 4
2007 .IX Item "isALNUMC_LC_uvchr"
2008 .ie n .IP """isALNUMC_L1""" 4
2009 .el .IP \f(CWisALNUMC_L1\fR 4
2010 .IX Xref "isALNUMC isALNUMC_A isALNUMC_LC isALNUMC_LC_uvchr isALNUMC_L1"
2011 .IX Item "isALNUMC_L1"
2012 .PD
2013 These are discouraged, backward compatibility macros for "\f(CW\*(C`isALPHANUMERIC\*(C'\fR".
2014 That is, each returns a boolean indicating whether the specified character is
2015 one of \f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR.
2016 .Sp
2017 The \f(CW\*(C`C\*(C'\fR suffix in the names was meant to indicate that they correspond to the
2018 C language \f(CW\*(C`\fR\f(CBisalnum\fR\f(CW\|(3)\*(C'\fR.
2019 .RS 4
2020 .Sp
2021 .Vb 5
2022 \& bool isALNUMC (UV ch)
2023 \& bool isALNUMC_A (UV ch)
2024 \& bool isALNUMC_LC (UV ch)
2025 \& bool isALNUMC_LC_uvchr(UV ch)
2026 \& bool isALNUMC_L1 (UV ch)
2027 .Ve
2028 .RE
2029 .RS 4
2030 .RE
2031 .ie n .IP """isALPHA""" 4
2032 .el .IP \f(CWisALPHA\fR 4
2033 .IX Item "isALPHA"
2034 .PD 0
2035 .ie n .IP """isALPHA_A""" 4
2036 .el .IP \f(CWisALPHA_A\fR 4
2037 .IX Item "isALPHA_A"
2038 .ie n .IP """isALPHA_LC""" 4
2039 .el .IP \f(CWisALPHA_LC\fR 4
2040 .IX Item "isALPHA_LC"
2041 .ie n .IP """isALPHA_LC_utf8_safe""" 4
2042 .el .IP \f(CWisALPHA_LC_utf8_safe\fR 4
2043 .IX Item "isALPHA_LC_utf8_safe"
2044 .ie n .IP """isALPHA_LC_uvchr""" 4
2045 .el .IP \f(CWisALPHA_LC_uvchr\fR 4
2046 .IX Item "isALPHA_LC_uvchr"
2047 .ie n .IP """isALPHA_L1""" 4
2048 .el .IP \f(CWisALPHA_L1\fR 4
2049 .IX Item "isALPHA_L1"
2050 .ie n .IP """isALPHA_utf8""" 4
2051 .el .IP \f(CWisALPHA_utf8\fR 4
2052 .IX Item "isALPHA_utf8"
2053 .ie n .IP """isALPHA_utf8_safe""" 4
2054 .el .IP \f(CWisALPHA_utf8_safe\fR 4
2055 .IX Item "isALPHA_utf8_safe"
2056 .ie n .IP """isALPHA_uvchr""" 4
2057 .el .IP \f(CWisALPHA_uvchr\fR 4
2058 .IX Xref "isALPHA isALPHA_A isALPHA_LC isALPHA_LC_utf8_safe isALPHA_LC_uvchr isALPHA_L1 isALPHA_utf8 isALPHA_utf8_safe isALPHA_uvchr"
2059 .IX Item "isALPHA_uvchr"
2060 .PD
2061 Returns a boolean indicating whether the specified input is one of \f(CW\*(C`[A\-Za\-z]\*(C'\fR,
2062 analogous to \f(CW\*(C`m/[[:alpha:]]/\*(C'\fR.
2063 See the top of this section for an explanation of
2064 the variants.
2065 .RS 4
2066 .Sp
2067 .Vb 9
2068 \& bool isALPHA (UV ch)
2069 \& bool isALPHA_A (UV ch)
2070 \& bool isALPHA_LC (UV ch)
2071 \& bool isALPHA_LC_utf8_safe(U8 * s, U8 *end)
2072 \& bool isALPHA_LC_uvchr (UV ch)
2073 \& bool isALPHA_L1 (UV ch)
2074 \& bool isALPHA_utf8 (U8 * s, U8 * end)
2075 \& bool isALPHA_utf8_safe (U8 * s, U8 * end)
2076 \& bool isALPHA_uvchr (UV ch)
2077 .Ve
2078 .RE
2079 .RS 4
2080 .RE
2081 .ie n .IP """isALPHANUMERIC""" 4
2082 .el .IP \f(CWisALPHANUMERIC\fR 4
2083 .IX Item "isALPHANUMERIC"
2084 .PD 0
2085 .ie n .IP """isALPHANUMERIC_A""" 4
2086 .el .IP \f(CWisALPHANUMERIC_A\fR 4
2087 .IX Item "isALPHANUMERIC_A"
2088 .ie n .IP """isALPHANUMERIC_LC""" 4
2089 .el .IP \f(CWisALPHANUMERIC_LC\fR 4
2090 .IX Item "isALPHANUMERIC_LC"
2091 .ie n .IP """isALPHANUMERIC_LC_utf8_safe""" 4
2092 .el .IP \f(CWisALPHANUMERIC_LC_utf8_safe\fR 4
2093 .IX Item "isALPHANUMERIC_LC_utf8_safe"
2094 .ie n .IP """isALPHANUMERIC_LC_uvchr""" 4
2095 .el .IP \f(CWisALPHANUMERIC_LC_uvchr\fR 4
2096 .IX Item "isALPHANUMERIC_LC_uvchr"
2097 .ie n .IP """isALPHANUMERIC_L1""" 4
2098 .el .IP \f(CWisALPHANUMERIC_L1\fR 4
2099 .IX Item "isALPHANUMERIC_L1"
2100 .ie n .IP """isALPHANUMERIC_utf8""" 4
2101 .el .IP \f(CWisALPHANUMERIC_utf8\fR 4
2102 .IX Item "isALPHANUMERIC_utf8"
2103 .ie n .IP """isALPHANUMERIC_utf8_safe""" 4
2104 .el .IP \f(CWisALPHANUMERIC_utf8_safe\fR 4
2105 .IX Item "isALPHANUMERIC_utf8_safe"
2106 .ie n .IP """isALPHANUMERIC_uvchr""" 4
2107 .el .IP \f(CWisALPHANUMERIC_uvchr\fR 4
2108 .IX Xref "isALPHANUMERIC isALPHANUMERIC_A isALPHANUMERIC_LC isALPHANUMERIC_LC_utf8_safe isALPHANUMERIC_LC_uvchr isALPHANUMERIC_L1 isALPHANUMERIC_utf8 isALPHANUMERIC_utf8_safe isALPHANUMERIC_uvchr"
2109 .IX Item "isALPHANUMERIC_uvchr"
2110 .PD
2111 Returns a boolean indicating whether the specified character is one of
2112 \&\f(CW\*(C`[A\-Za\-z0\-9]\*(C'\fR, analogous to \f(CW\*(C`m/[[:alnum:]]/\*(C'\fR.
2113 See the top of this section for an explanation of
2114 the variants.
2115 .RS 4
2116 .Sp
2117 .Vb 9
2118 \& bool isALPHANUMERIC (UV ch)
2119 \& bool isALPHANUMERIC_A (UV ch)
2120 \& bool isALPHANUMERIC_LC (UV ch)
2121 \& bool isALPHANUMERIC_LC_utf8_safe(U8 * s, U8 *end)
2122 \& bool isALPHANUMERIC_LC_uvchr (UV ch)
2123 \& bool isALPHANUMERIC_L1 (UV ch)
2124 \& bool isALPHANUMERIC_utf8 (U8 * s, U8 * end)
2125 \& bool isALPHANUMERIC_utf8_safe (U8 * s, U8 * end)
2126 \& bool isALPHANUMERIC_uvchr (UV ch)
2127 .Ve
2128 .RE
2129 .RS 4
2130 .RE
2131 .ie n .IP """isASCII""" 4
2132 .el .IP \f(CWisASCII\fR 4
2133 .IX Item "isASCII"
2134 .PD 0
2135 .ie n .IP """isASCII_A""" 4
2136 .el .IP \f(CWisASCII_A\fR 4
2137 .IX Item "isASCII_A"
2138 .ie n .IP """isASCII_LC""" 4
2139 .el .IP \f(CWisASCII_LC\fR 4
2140 .IX Item "isASCII_LC"
2141 .ie n .IP """isASCII_LC_utf8_safe""" 4
2142 .el .IP \f(CWisASCII_LC_utf8_safe\fR 4
2143 .IX Item "isASCII_LC_utf8_safe"
2144 .ie n .IP """isASCII_LC_uvchr""" 4
2145 .el .IP \f(CWisASCII_LC_uvchr\fR 4
2146 .IX Item "isASCII_LC_uvchr"
2147 .ie n .IP """isASCII_L1""" 4
2148 .el .IP \f(CWisASCII_L1\fR 4
2149 .IX Item "isASCII_L1"
2150 .ie n .IP """isASCII_utf8""" 4
2151 .el .IP \f(CWisASCII_utf8\fR 4
2152 .IX Item "isASCII_utf8"
2153 .ie n .IP """isASCII_utf8_safe""" 4
2154 .el .IP \f(CWisASCII_utf8_safe\fR 4
2155 .IX Item "isASCII_utf8_safe"
2156 .ie n .IP """isASCII_uvchr""" 4
2157 .el .IP \f(CWisASCII_uvchr\fR 4
2158 .IX Xref "isASCII isASCII_A isASCII_LC isASCII_LC_utf8_safe isASCII_LC_uvchr isASCII_L1 isASCII_utf8 isASCII_utf8_safe isASCII_uvchr"
2159 .IX Item "isASCII_uvchr"
2160 .PD
2161 Returns a boolean indicating whether the specified character is one of the 128
2162 characters in the ASCII character set, analogous to \f(CW\*(C`m/[[:ascii:]]/\*(C'\fR.
2163 On non\-ASCII platforms, it returns TRUE iff this
2164 character corresponds to an ASCII character. Variants \f(CWisASCII_A()\fR and
2165 \&\f(CWisASCII_L1()\fR are identical to \f(CWisASCII()\fR.
2166 See the top of this section for an explanation of
2167 the variants.
2168 Note, however, that some platforms do not have the C library routine
2169 \&\f(CWisascii()\fR. In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are the
2170 same as the corresponding ones without.
2171 .Sp
2172 Also note, that because all ASCII characters are UTF\-8 invariant (meaning they
2173 have the exact same representation (always a single byte) whether encoded in
2174 UTF\-8 or not), \f(CW\*(C`isASCII\*(C'\fR will give the correct results when called with any
2175 byte in any string encoded or not in UTF\-8. And similarly \f(CW\*(C`isASCII_utf8\*(C'\fR and
2176 \&\f(CW\*(C`isASCII_utf8_safe\*(C'\fR will work properly on any string encoded or not in UTF\-8.
2177 .RS 4
2178 .Sp
2179 .Vb 9
2180 \& bool isASCII (UV ch)
2181 \& bool isASCII_A (UV ch)
2182 \& bool isASCII_LC (UV ch)
2183 \& bool isASCII_LC_utf8_safe(U8 * s, U8 *end)
2184 \& bool isASCII_LC_uvchr (UV ch)
2185 \& bool isASCII_L1 (UV ch)
2186 \& bool isASCII_utf8 (U8 * s, U8 * end)
2187 \& bool isASCII_utf8_safe (U8 * s, U8 * end)
2188 \& bool isASCII_uvchr (UV ch)
2189 .Ve
2190 .RE
2191 .RS 4
2192 .RE
2193 .ie n .IP """isBLANK""" 4
2194 .el .IP \f(CWisBLANK\fR 4
2195 .IX Item "isBLANK"
2196 .PD 0
2197 .ie n .IP """isBLANK_A""" 4
2198 .el .IP \f(CWisBLANK_A\fR 4
2199 .IX Item "isBLANK_A"
2200 .ie n .IP """isBLANK_LC""" 4
2201 .el .IP \f(CWisBLANK_LC\fR 4
2202 .IX Item "isBLANK_LC"
2203 .ie n .IP """isBLANK_LC_utf8_safe""" 4
2204 .el .IP \f(CWisBLANK_LC_utf8_safe\fR 4
2205 .IX Item "isBLANK_LC_utf8_safe"
2206 .ie n .IP """isBLANK_LC_uvchr""" 4
2207 .el .IP \f(CWisBLANK_LC_uvchr\fR 4
2208 .IX Item "isBLANK_LC_uvchr"
2209 .ie n .IP """isBLANK_L1""" 4
2210 .el .IP \f(CWisBLANK_L1\fR 4
2211 .IX Item "isBLANK_L1"
2212 .ie n .IP """isBLANK_utf8""" 4
2213 .el .IP \f(CWisBLANK_utf8\fR 4
2214 .IX Item "isBLANK_utf8"
2215 .ie n .IP """isBLANK_utf8_safe""" 4
2216 .el .IP \f(CWisBLANK_utf8_safe\fR 4
2217 .IX Item "isBLANK_utf8_safe"
2218 .ie n .IP """isBLANK_uvchr""" 4
2219 .el .IP \f(CWisBLANK_uvchr\fR 4
2220 .IX Xref "isBLANK isBLANK_A isBLANK_LC isBLANK_LC_utf8_safe isBLANK_LC_uvchr isBLANK_L1 isBLANK_utf8 isBLANK_utf8_safe isBLANK_uvchr"
2221 .IX Item "isBLANK_uvchr"
2222 .PD
2223 Returns a boolean indicating whether the specified character is a
2224 character considered to be a blank, analogous to \f(CW\*(C`m/[[:blank:]]/\*(C'\fR.
2225 See the top of this section for an explanation of
2226 the variants.
2227 Note,
2228 however, that some platforms do not have the C library routine
2229 \&\f(CWisblank()\fR. In these cases, the variants whose names contain \f(CW\*(C`LC\*(C'\fR are
2230 the same as the corresponding ones without.
2231 .RS 4
2232 .Sp
2233 .Vb 9
2234 \& bool isBLANK (UV ch)
2235 \& bool isBLANK_A (UV ch)
2236 \& bool isBLANK_LC (UV ch)
2237 \& bool isBLANK_LC_utf8_safe(U8 * s, U8 *end)
2238 \& bool isBLANK_LC_uvchr (UV ch)
2239 \& bool isBLANK_L1 (UV ch)
2240 \& bool isBLANK_utf8 (U8 * s, U8 * end)
2241 \& bool isBLANK_utf8_safe (U8 * s, U8 * end)
2242 \& bool isBLANK_uvchr (UV ch)
2243 .Ve
2244 .RE
2245 .RS 4
2246 .RE
2247 .ie n .IP """isCNTRL""" 4
2248 .el .IP \f(CWisCNTRL\fR 4
2249 .IX Item "isCNTRL"
2250 .PD 0
2251 .ie n .IP """isCNTRL_A""" 4
2252 .el .IP \f(CWisCNTRL_A\fR 4
2253 .IX Item "isCNTRL_A"
2254 .ie n .IP """isCNTRL_LC""" 4
2255 .el .IP \f(CWisCNTRL_LC\fR 4
2256 .IX Item "isCNTRL_LC"
2257 .ie n .IP """isCNTRL_LC_utf8_safe""" 4
2258 .el .IP \f(CWisCNTRL_LC_utf8_safe\fR 4
2259 .IX Item "isCNTRL_LC_utf8_safe"
2260 .ie n .IP """isCNTRL_LC_uvchr""" 4
2261 .el .IP \f(CWisCNTRL_LC_uvchr\fR 4
2262 .IX Item "isCNTRL_LC_uvchr"
2263 .ie n .IP """isCNTRL_L1""" 4
2264 .el .IP \f(CWisCNTRL_L1\fR 4
2265 .IX Item "isCNTRL_L1"
2266 .ie n .IP """isCNTRL_utf8""" 4
2267 .el .IP \f(CWisCNTRL_utf8\fR 4
2268 .IX Item "isCNTRL_utf8"
2269 .ie n .IP """isCNTRL_utf8_safe""" 4
2270 .el .IP \f(CWisCNTRL_utf8_safe\fR 4
2271 .IX Item "isCNTRL_utf8_safe"
2272 .ie n .IP """isCNTRL_uvchr""" 4
2273 .el .IP \f(CWisCNTRL_uvchr\fR 4
2274 .IX Xref "isCNTRL isCNTRL_A isCNTRL_LC isCNTRL_LC_utf8_safe isCNTRL_LC_uvchr isCNTRL_L1 isCNTRL_utf8 isCNTRL_utf8_safe isCNTRL_uvchr"
2275 .IX Item "isCNTRL_uvchr"
2276 .PD
2277 Returns a boolean indicating whether the specified character is a
2278 control character, analogous to \f(CW\*(C`m/[[:cntrl:]]/\*(C'\fR.
2279 See the top of this section for an explanation of
2280 the variants.
2281 On EBCDIC platforms, you almost always want to use the \f(CW\*(C`isCNTRL_L1\*(C'\fR variant.
2282 .RS 4
2283 .Sp
2284 .Vb 9
2285 \& bool isCNTRL (UV ch)
2286 \& bool isCNTRL_A (UV ch)
2287 \& bool isCNTRL_LC (UV ch)
2288 \& bool isCNTRL_LC_utf8_safe(U8 * s, U8 *end)
2289 \& bool isCNTRL_LC_uvchr (UV ch)
2290 \& bool isCNTRL_L1 (UV ch)
2291 \& bool isCNTRL_utf8 (U8 * s, U8 * end)
2292 \& bool isCNTRL_utf8_safe (U8 * s, U8 * end)
2293 \& bool isCNTRL_uvchr (UV ch)
2294 .Ve
2295 .RE
2296 .RS 4
2297 .RE
2298 .ie n .IP """isDIGIT""" 4
2299 .el .IP \f(CWisDIGIT\fR 4
2300 .IX Item "isDIGIT"
2301 .PD 0
2302 .ie n .IP """isDIGIT_A""" 4
2303 .el .IP \f(CWisDIGIT_A\fR 4
2304 .IX Item "isDIGIT_A"
2305 .ie n .IP """isDIGIT_LC""" 4
2306 .el .IP \f(CWisDIGIT_LC\fR 4
2307 .IX Item "isDIGIT_LC"
2308 .ie n .IP """isDIGIT_LC_utf8_safe""" 4
2309 .el .IP \f(CWisDIGIT_LC_utf8_safe\fR 4
2310 .IX Item "isDIGIT_LC_utf8_safe"
2311 .ie n .IP """isDIGIT_LC_uvchr""" 4
2312 .el .IP \f(CWisDIGIT_LC_uvchr\fR 4
2313 .IX Item "isDIGIT_LC_uvchr"
2314 .ie n .IP """isDIGIT_L1""" 4
2315 .el .IP \f(CWisDIGIT_L1\fR 4
2316 .IX Item "isDIGIT_L1"
2317 .ie n .IP """isDIGIT_utf8""" 4
2318 .el .IP \f(CWisDIGIT_utf8\fR 4
2319 .IX Item "isDIGIT_utf8"
2320 .ie n .IP """isDIGIT_utf8_safe""" 4
2321 .el .IP \f(CWisDIGIT_utf8_safe\fR 4
2322 .IX Item "isDIGIT_utf8_safe"
2323 .ie n .IP """isDIGIT_uvchr""" 4
2324 .el .IP \f(CWisDIGIT_uvchr\fR 4
2325 .IX Xref "isDIGIT isDIGIT_A isDIGIT_LC isDIGIT_LC_utf8_safe isDIGIT_LC_uvchr isDIGIT_L1 isDIGIT_utf8 isDIGIT_utf8_safe isDIGIT_uvchr"
2326 .IX Item "isDIGIT_uvchr"
2327 .PD
2328 Returns a boolean indicating whether the specified character is a
2329 digit, analogous to \f(CW\*(C`m/[[:digit:]]/\*(C'\fR.
2330 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.
2331 See the top of this section for an explanation of
2332 the variants.
2333 .RS 4
2334 .Sp
2335 .Vb 9
2336 \& bool isDIGIT (UV ch)
2337 \& bool isDIGIT_A (UV ch)
2338 \& bool isDIGIT_LC (UV ch)
2339 \& bool isDIGIT_LC_utf8_safe(U8 * s, U8 *end)
2340 \& bool isDIGIT_LC_uvchr (UV ch)
2341 \& bool isDIGIT_L1 (UV ch)
2342 \& bool isDIGIT_utf8 (U8 * s, U8 * end)
2343 \& bool isDIGIT_utf8_safe (U8 * s, U8 * end)
2344 \& bool isDIGIT_uvchr (UV ch)
2345 .Ve
2346 .RE
2347 .RS 4
2348 .RE
2349 .ie n .IP """isGRAPH""" 4
2350 .el .IP \f(CWisGRAPH\fR 4
2351 .IX Item "isGRAPH"
2352 .PD 0
2353 .ie n .IP """isGRAPH_A""" 4
2354 .el .IP \f(CWisGRAPH_A\fR 4
2355 .IX Item "isGRAPH_A"
2356 .ie n .IP """isGRAPH_LC""" 4
2357 .el .IP \f(CWisGRAPH_LC\fR 4
2358 .IX Item "isGRAPH_LC"
2359 .ie n .IP """isGRAPH_LC_utf8_safe""" 4
2360 .el .IP \f(CWisGRAPH_LC_utf8_safe\fR 4
2361 .IX Item "isGRAPH_LC_utf8_safe"
2362 .ie n .IP """isGRAPH_LC_uvchr""" 4
2363 .el .IP \f(CWisGRAPH_LC_uvchr\fR 4
2364 .IX Item "isGRAPH_LC_uvchr"
2365 .ie n .IP """isGRAPH_L1""" 4
2366 .el .IP \f(CWisGRAPH_L1\fR 4
2367 .IX Item "isGRAPH_L1"
2368 .ie n .IP """isGRAPH_utf8""" 4
2369 .el .IP \f(CWisGRAPH_utf8\fR 4
2370 .IX Item "isGRAPH_utf8"
2371 .ie n .IP """isGRAPH_utf8_safe""" 4
2372 .el .IP \f(CWisGRAPH_utf8_safe\fR 4
2373 .IX Item "isGRAPH_utf8_safe"
2374 .ie n .IP """isGRAPH_uvchr""" 4
2375 .el .IP \f(CWisGRAPH_uvchr\fR 4
2376 .IX Xref "isGRAPH isGRAPH_A isGRAPH_LC isGRAPH_LC_utf8_safe isGRAPH_LC_uvchr isGRAPH_L1 isGRAPH_utf8 isGRAPH_utf8_safe isGRAPH_uvchr"
2377 .IX Item "isGRAPH_uvchr"
2378 .PD
2379 Returns a boolean indicating whether the specified character is a
2380 graphic character, analogous to \f(CW\*(C`m/[[:graph:]]/\*(C'\fR.
2381 See the top of this section for an explanation of
2382 the variants.
2383 .RS 4
2384 .Sp
2385 .Vb 9
2386 \& bool isGRAPH (UV ch)
2387 \& bool isGRAPH_A (UV ch)
2388 \& bool isGRAPH_LC (UV ch)
2389 \& bool isGRAPH_LC_utf8_safe(U8 * s, U8 *end)
2390 \& bool isGRAPH_LC_uvchr (UV ch)
2391 \& bool isGRAPH_L1 (UV ch)
2392 \& bool isGRAPH_utf8 (U8 * s, U8 * end)
2393 \& bool isGRAPH_utf8_safe (U8 * s, U8 * end)
2394 \& bool isGRAPH_uvchr (UV ch)
2395 .Ve
2396 .RE
2397 .RS 4
2398 .RE
2399 .ie n .IP """isIDCONT""" 4
2400 .el .IP \f(CWisIDCONT\fR 4
2401 .IX Item "isIDCONT"
2402 .PD 0
2403 .ie n .IP """isIDCONT_A""" 4
2404 .el .IP \f(CWisIDCONT_A\fR 4
2405 .IX Item "isIDCONT_A"
2406 .ie n .IP """isIDCONT_LC""" 4
2407 .el .IP \f(CWisIDCONT_LC\fR 4
2408 .IX Item "isIDCONT_LC"
2409 .ie n .IP """isIDCONT_LC_utf8_safe""" 4
2410 .el .IP \f(CWisIDCONT_LC_utf8_safe\fR 4
2411 .IX Item "isIDCONT_LC_utf8_safe"
2412 .ie n .IP """isIDCONT_LC_uvchr""" 4
2413 .el .IP \f(CWisIDCONT_LC_uvchr\fR 4
2414 .IX Item "isIDCONT_LC_uvchr"
2415 .ie n .IP """isIDCONT_L1""" 4
2416 .el .IP \f(CWisIDCONT_L1\fR 4
2417 .IX Item "isIDCONT_L1"
2418 .ie n .IP """isIDCONT_utf8""" 4
2419 .el .IP \f(CWisIDCONT_utf8\fR 4
2420 .IX Item "isIDCONT_utf8"
2421 .ie n .IP """isIDCONT_utf8_safe""" 4
2422 .el .IP \f(CWisIDCONT_utf8_safe\fR 4
2423 .IX Item "isIDCONT_utf8_safe"
2424 .ie n .IP """isIDCONT_uvchr""" 4
2425 .el .IP \f(CWisIDCONT_uvchr\fR 4
2426 .IX Xref "isIDCONT isIDCONT_A isIDCONT_LC isIDCONT_LC_utf8_safe isIDCONT_LC_uvchr isIDCONT_L1 isIDCONT_utf8 isIDCONT_utf8_safe isIDCONT_uvchr"
2427 .IX Item "isIDCONT_uvchr"
2428 .PD
2429 Returns a boolean indicating whether the specified character can be the
2430 second or succeeding character of an identifier. This is very close to, but
2431 not quite the same as the official Unicode property \f(CW\*(C`XID_Continue\*(C'\fR. The
2432 difference is that this returns true only if the input character also matches
2433 "isWORDCHAR". See the top of this section for
2434 an explanation of the variants.
2435 .RS 4
2436 .Sp
2437 .Vb 9
2438 \& bool isIDCONT (UV ch)
2439 \& bool isIDCONT_A (UV ch)
2440 \& bool isIDCONT_LC (UV ch)
2441 \& bool isIDCONT_LC_utf8_safe(U8 * s, U8 *end)
2442 \& bool isIDCONT_LC_uvchr (UV ch)
2443 \& bool isIDCONT_L1 (UV ch)
2444 \& bool isIDCONT_utf8 (U8 * s, U8 * end)
2445 \& bool isIDCONT_utf8_safe (U8 * s, U8 * end)
2446 \& bool isIDCONT_uvchr (UV ch)
2447 .Ve
2448 .RE
2449 .RS 4
2450 .RE
2451 .ie n .IP """isIDFIRST""" 4
2452 .el .IP \f(CWisIDFIRST\fR 4
2453 .IX Item "isIDFIRST"
2454 .PD 0
2455 .ie n .IP """isIDFIRST_A""" 4
2456 .el .IP \f(CWisIDFIRST_A\fR 4
2457 .IX Item "isIDFIRST_A"
2458 .ie n .IP """isIDFIRST_LC""" 4
2459 .el .IP \f(CWisIDFIRST_LC\fR 4
2460 .IX Item "isIDFIRST_LC"
2461 .ie n .IP """isIDFIRST_LC_utf8_safe""" 4
2462 .el .IP \f(CWisIDFIRST_LC_utf8_safe\fR 4
2463 .IX Item "isIDFIRST_LC_utf8_safe"
2464 .ie n .IP """isIDFIRST_LC_uvchr""" 4
2465 .el .IP \f(CWisIDFIRST_LC_uvchr\fR 4
2466 .IX Item "isIDFIRST_LC_uvchr"
2467 .ie n .IP """isIDFIRST_L1""" 4
2468 .el .IP \f(CWisIDFIRST_L1\fR 4
2469 .IX Item "isIDFIRST_L1"
2470 .ie n .IP """isIDFIRST_utf8""" 4
2471 .el .IP \f(CWisIDFIRST_utf8\fR 4
2472 .IX Item "isIDFIRST_utf8"
2473 .ie n .IP """isIDFIRST_utf8_safe""" 4
2474 .el .IP \f(CWisIDFIRST_utf8_safe\fR 4
2475 .IX Item "isIDFIRST_utf8_safe"
2476 .ie n .IP """isIDFIRST_uvchr""" 4
2477 .el .IP \f(CWisIDFIRST_uvchr\fR 4
2478 .IX Xref "isIDFIRST isIDFIRST_A isIDFIRST_LC isIDFIRST_LC_utf8_safe isIDFIRST_LC_uvchr isIDFIRST_L1 isIDFIRST_utf8 isIDFIRST_utf8_safe isIDFIRST_uvchr"
2479 .IX Item "isIDFIRST_uvchr"
2480 .PD
2481 Returns a boolean indicating whether the specified character can be the first
2482 character of an identifier. This is very close to, but not quite the same as
2483 the official Unicode property \f(CW\*(C`XID_Start\*(C'\fR. The difference is that this
2484 returns true only if the input character also matches "isWORDCHAR".
2485 See the top of this section for an explanation of
2486 the variants.
2487 .RS 4
2488 .Sp
2489 .Vb 9
2490 \& bool isIDFIRST (UV ch)
2491 \& bool isIDFIRST_A (UV ch)
2492 \& bool isIDFIRST_LC (UV ch)
2493 \& bool isIDFIRST_LC_utf8_safe(U8 * s, U8 *end)
2494 \& bool isIDFIRST_LC_uvchr (UV ch)
2495 \& bool isIDFIRST_L1 (UV ch)
2496 \& bool isIDFIRST_utf8 (U8 * s, U8 * end)
2497 \& bool isIDFIRST_utf8_safe (U8 * s, U8 * end)
2498 \& bool isIDFIRST_uvchr (UV ch)
2499 .Ve
2500 .RE
2501 .RS 4
2502 .RE
2503 .ie n .IP """isLOWER""" 4
2504 .el .IP \f(CWisLOWER\fR 4
2505 .IX Item "isLOWER"
2506 .PD 0
2507 .ie n .IP """isLOWER_A""" 4
2508 .el .IP \f(CWisLOWER_A\fR 4
2509 .IX Item "isLOWER_A"
2510 .ie n .IP """isLOWER_LC""" 4
2511 .el .IP \f(CWisLOWER_LC\fR 4
2512 .IX Item "isLOWER_LC"
2513 .ie n .IP """isLOWER_LC_utf8_safe""" 4
2514 .el .IP \f(CWisLOWER_LC_utf8_safe\fR 4
2515 .IX Item "isLOWER_LC_utf8_safe"
2516 .ie n .IP """isLOWER_LC_uvchr""" 4
2517 .el .IP \f(CWisLOWER_LC_uvchr\fR 4
2518 .IX Item "isLOWER_LC_uvchr"
2519 .ie n .IP """isLOWER_L1""" 4
2520 .el .IP \f(CWisLOWER_L1\fR 4
2521 .IX Item "isLOWER_L1"
2522 .ie n .IP """isLOWER_utf8""" 4
2523 .el .IP \f(CWisLOWER_utf8\fR 4
2524 .IX Item "isLOWER_utf8"
2525 .ie n .IP """isLOWER_utf8_safe""" 4
2526 .el .IP \f(CWisLOWER_utf8_safe\fR 4
2527 .IX Item "isLOWER_utf8_safe"
2528 .ie n .IP """isLOWER_uvchr""" 4
2529 .el .IP \f(CWisLOWER_uvchr\fR 4
2530 .IX Xref "isLOWER isLOWER_A isLOWER_LC isLOWER_LC_utf8_safe isLOWER_LC_uvchr isLOWER_L1 isLOWER_utf8 isLOWER_utf8_safe isLOWER_uvchr"
2531 .IX Item "isLOWER_uvchr"
2532 .PD
2533 Returns a boolean indicating whether the specified character is a
2534 lowercase character, analogous to \f(CW\*(C`m/[[:lower:]]/\*(C'\fR.
2535 See the top of this section for an explanation of
2536 the variants
2537 .RS 4
2538 .Sp
2539 .Vb 9
2540 \& bool isLOWER (UV ch)
2541 \& bool isLOWER_A (UV ch)
2542 \& bool isLOWER_LC (UV ch)
2543 \& bool isLOWER_LC_utf8_safe(U8 * s, U8 *end)
2544 \& bool isLOWER_LC_uvchr (UV ch)
2545 \& bool isLOWER_L1 (UV ch)
2546 \& bool isLOWER_utf8 (U8 * s, U8 * end)
2547 \& bool isLOWER_utf8_safe (U8 * s, U8 * end)
2548 \& bool isLOWER_uvchr (UV ch)
2549 .Ve
2550 .RE
2551 .RS 4
2552 .RE
2553 .ie n .IP """isOCTAL""" 4
2554 .el .IP \f(CWisOCTAL\fR 4
2555 .IX Item "isOCTAL"
2556 .PD 0
2557 .ie n .IP """isOCTAL_A""" 4
2558 .el .IP \f(CWisOCTAL_A\fR 4
2559 .IX Item "isOCTAL_A"
2560 .ie n .IP """isOCTAL_L1""" 4
2561 .el .IP \f(CWisOCTAL_L1\fR 4
2562 .IX Xref "isOCTAL isOCTAL_A isOCTAL_L1"
2563 .IX Item "isOCTAL_L1"
2564 .PD
2565 Returns a boolean indicating whether the specified character is an
2566 octal digit, [0\-7].
2567 The only two variants are \f(CW\*(C`isOCTAL_A\*(C'\fR and \f(CW\*(C`isOCTAL_L1\*(C'\fR; each is identical to
2568 \&\f(CW\*(C`isOCTAL\*(C'\fR.
2569 .RS 4
2570 .Sp
2571 .Vb 3
2572 \& bool isOCTAL (UV ch)
2573 \& bool isOCTAL_A (UV ch)
2574 \& bool isOCTAL_L1(UV ch)
2575 .Ve
2576 .RE
2577 .RS 4
2578 .RE
2579 .ie n .IP """isPRINT""" 4
2580 .el .IP \f(CWisPRINT\fR 4
2581 .IX Item "isPRINT"
2582 .PD 0
2583 .ie n .IP """isPRINT_A""" 4
2584 .el .IP \f(CWisPRINT_A\fR 4
2585 .IX Item "isPRINT_A"
2586 .ie n .IP """isPRINT_LC""" 4
2587 .el .IP \f(CWisPRINT_LC\fR 4
2588 .IX Item "isPRINT_LC"
2589 .ie n .IP """isPRINT_LC_utf8_safe""" 4
2590 .el .IP \f(CWisPRINT_LC_utf8_safe\fR 4
2591 .IX Item "isPRINT_LC_utf8_safe"
2592 .ie n .IP """isPRINT_LC_uvchr""" 4
2593 .el .IP \f(CWisPRINT_LC_uvchr\fR 4
2594 .IX Item "isPRINT_LC_uvchr"
2595 .ie n .IP """isPRINT_L1""" 4
2596 .el .IP \f(CWisPRINT_L1\fR 4
2597 .IX Item "isPRINT_L1"
2598 .ie n .IP """isPRINT_utf8""" 4
2599 .el .IP \f(CWisPRINT_utf8\fR 4
2600 .IX Item "isPRINT_utf8"
2601 .ie n .IP """isPRINT_utf8_safe""" 4
2602 .el .IP \f(CWisPRINT_utf8_safe\fR 4
2603 .IX Item "isPRINT_utf8_safe"
2604 .ie n .IP """isPRINT_uvchr""" 4
2605 .el .IP \f(CWisPRINT_uvchr\fR 4
2606 .IX Xref "isPRINT isPRINT_A isPRINT_LC isPRINT_LC_utf8_safe isPRINT_LC_uvchr isPRINT_L1 isPRINT_utf8 isPRINT_utf8_safe isPRINT_uvchr"
2607 .IX Item "isPRINT_uvchr"
2608 .PD
2609 Returns a boolean indicating whether the specified character is a
2610 printable character, analogous to \f(CW\*(C`m/[[:print:]]/\*(C'\fR.
2611 See the top of this section for an explanation of
2612 the variants.
2613 .RS 4
2614 .Sp
2615 .Vb 9
2616 \& bool isPRINT (UV ch)
2617 \& bool isPRINT_A (UV ch)
2618 \& bool isPRINT_LC (UV ch)
2619 \& bool isPRINT_LC_utf8_safe(U8 * s, U8 *end)
2620 \& bool isPRINT_LC_uvchr (UV ch)
2621 \& bool isPRINT_L1 (UV ch)
2622 \& bool isPRINT_utf8 (U8 * s, U8 * end)
2623 \& bool isPRINT_utf8_safe (U8 * s, U8 * end)
2624 \& bool isPRINT_uvchr (UV ch)
2625 .Ve
2626 .RE
2627 .RS 4
2628 .RE
2629 .ie n .IP """isPSXSPC""" 4
2630 .el .IP \f(CWisPSXSPC\fR 4
2631 .IX Item "isPSXSPC"
2632 .PD 0
2633 .ie n .IP """isPSXSPC_A""" 4
2634 .el .IP \f(CWisPSXSPC_A\fR 4
2635 .IX Item "isPSXSPC_A"
2636 .ie n .IP """isPSXSPC_LC""" 4
2637 .el .IP \f(CWisPSXSPC_LC\fR 4
2638 .IX Item "isPSXSPC_LC"
2639 .ie n .IP """isPSXSPC_LC_utf8_safe""" 4
2640 .el .IP \f(CWisPSXSPC_LC_utf8_safe\fR 4
2641 .IX Item "isPSXSPC_LC_utf8_safe"
2642 .ie n .IP """isPSXSPC_LC_uvchr""" 4
2643 .el .IP \f(CWisPSXSPC_LC_uvchr\fR 4
2644 .IX Item "isPSXSPC_LC_uvchr"
2645 .ie n .IP """isPSXSPC_L1""" 4
2646 .el .IP \f(CWisPSXSPC_L1\fR 4
2647 .IX Item "isPSXSPC_L1"
2648 .ie n .IP """isPSXSPC_utf8""" 4
2649 .el .IP \f(CWisPSXSPC_utf8\fR 4
2650 .IX Item "isPSXSPC_utf8"
2651 .ie n .IP """isPSXSPC_utf8_safe""" 4
2652 .el .IP \f(CWisPSXSPC_utf8_safe\fR 4
2653 .IX Item "isPSXSPC_utf8_safe"
2654 .ie n .IP """isPSXSPC_uvchr""" 4
2655 .el .IP \f(CWisPSXSPC_uvchr\fR 4
2656 .IX Xref "isPSXSPC isPSXSPC_A isPSXSPC_LC isPSXSPC_LC_utf8_safe isPSXSPC_LC_uvchr isPSXSPC_L1 isPSXSPC_utf8 isPSXSPC_utf8_safe isPSXSPC_uvchr"
2657 .IX Item "isPSXSPC_uvchr"
2658 .PD
2659 (short for Posix Space)
2660 Starting in 5.18, this is identical in all its forms to the
2661 corresponding \f(CWisSPACE()\fR macros.
2662 The locale forms of this macro are identical to their corresponding
2663 \&\f(CWisSPACE()\fR forms in all Perl releases. In releases prior to 5.18, the
2664 non\-locale forms differ from their \f(CWisSPACE()\fR forms only in that the
2665 \&\f(CWisSPACE()\fR forms don\*(Aqt match a Vertical Tab, and the \f(CWisPSXSPC()\fR forms do.
2666 Otherwise they are identical. Thus this macro is analogous to what
2667 \&\f(CW\*(C`m/[[:space:]]/\*(C'\fR matches in a regular expression.
2668 See the top of this section for an explanation of
2669 the variants.
2670 .RS 4
2671 .Sp
2672 .Vb 9
2673 \& bool isPSXSPC (UV ch)
2674 \& bool isPSXSPC_A (UV ch)
2675 \& bool isPSXSPC_LC (UV ch)
2676 \& bool isPSXSPC_LC_utf8_safe(U8 * s, U8 *end)
2677 \& bool isPSXSPC_LC_uvchr (UV ch)
2678 \& bool isPSXSPC_L1 (UV ch)
2679 \& bool isPSXSPC_utf8 (U8 * s, U8 * end)
2680 \& bool isPSXSPC_utf8_safe (U8 * s, U8 * end)
2681 \& bool isPSXSPC_uvchr (UV ch)
2682 .Ve
2683 .RE
2684 .RS 4
2685 .RE
2686 .ie n .IP """isPUNCT""" 4
2687 .el .IP \f(CWisPUNCT\fR 4
2688 .IX Item "isPUNCT"
2689 .PD 0
2690 .ie n .IP """isPUNCT_A""" 4
2691 .el .IP \f(CWisPUNCT_A\fR 4
2692 .IX Item "isPUNCT_A"
2693 .ie n .IP """isPUNCT_LC""" 4
2694 .el .IP \f(CWisPUNCT_LC\fR 4
2695 .IX Item "isPUNCT_LC"
2696 .ie n .IP """isPUNCT_LC_utf8_safe""" 4
2697 .el .IP \f(CWisPUNCT_LC_utf8_safe\fR 4
2698 .IX Item "isPUNCT_LC_utf8_safe"
2699 .ie n .IP """isPUNCT_LC_uvchr""" 4
2700 .el .IP \f(CWisPUNCT_LC_uvchr\fR 4
2701 .IX Item "isPUNCT_LC_uvchr"
2702 .ie n .IP """isPUNCT_L1""" 4
2703 .el .IP \f(CWisPUNCT_L1\fR 4
2704 .IX Item "isPUNCT_L1"
2705 .ie n .IP """isPUNCT_utf8""" 4
2706 .el .IP \f(CWisPUNCT_utf8\fR 4
2707 .IX Item "isPUNCT_utf8"
2708 .ie n .IP """isPUNCT_utf8_safe""" 4
2709 .el .IP \f(CWisPUNCT_utf8_safe\fR 4
2710 .IX Item "isPUNCT_utf8_safe"
2711 .ie n .IP """isPUNCT_uvchr""" 4
2712 .el .IP \f(CWisPUNCT_uvchr\fR 4
2713 .IX Xref "isPUNCT isPUNCT_A isPUNCT_LC isPUNCT_LC_utf8_safe isPUNCT_LC_uvchr isPUNCT_L1 isPUNCT_utf8 isPUNCT_utf8_safe isPUNCT_uvchr"
2714 .IX Item "isPUNCT_uvchr"
2715 .PD
2716 Returns a boolean indicating whether the specified character is a
2717 punctuation character, analogous to \f(CW\*(C`m/[[:punct:]]/\*(C'\fR.
2718 Note that the definition of what is punctuation isn\*(Aqt as
2719 straightforward as one might desire. See "POSIX Character
2720 Classes" in perlrecharclass for details.
2721 See the top of this section for an explanation of
2722 the variants.
2723 .RS 4
2724 .Sp
2725 .Vb 9
2726 \& bool isPUNCT (UV ch)
2727 \& bool isPUNCT_A (UV ch)
2728 \& bool isPUNCT_LC (UV ch)
2729 \& bool isPUNCT_LC_utf8_safe(U8 * s, U8 *end)
2730 \& bool isPUNCT_LC_uvchr (UV ch)
2731 \& bool isPUNCT_L1 (UV ch)
2732 \& bool isPUNCT_utf8 (U8 * s, U8 * end)
2733 \& bool isPUNCT_utf8_safe (U8 * s, U8 * end)
2734 \& bool isPUNCT_uvchr (UV ch)
2735 .Ve
2736 .RE
2737 .RS 4
2738 .RE
2739 .ie n .IP """isSPACE""" 4
2740 .el .IP \f(CWisSPACE\fR 4
2741 .IX Item "isSPACE"
2742 .PD 0
2743 .ie n .IP """isSPACE_A""" 4
2744 .el .IP \f(CWisSPACE_A\fR 4
2745 .IX Item "isSPACE_A"
2746 .ie n .IP """isSPACE_LC""" 4
2747 .el .IP \f(CWisSPACE_LC\fR 4
2748 .IX Item "isSPACE_LC"
2749 .ie n .IP """isSPACE_LC_utf8_safe""" 4
2750 .el .IP \f(CWisSPACE_LC_utf8_safe\fR 4
2751 .IX Item "isSPACE_LC_utf8_safe"
2752 .ie n .IP """isSPACE_LC_uvchr""" 4
2753 .el .IP \f(CWisSPACE_LC_uvchr\fR 4
2754 .IX Item "isSPACE_LC_uvchr"
2755 .ie n .IP """isSPACE_L1""" 4
2756 .el .IP \f(CWisSPACE_L1\fR 4
2757 .IX Item "isSPACE_L1"
2758 .ie n .IP """isSPACE_utf8""" 4
2759 .el .IP \f(CWisSPACE_utf8\fR 4
2760 .IX Item "isSPACE_utf8"
2761 .ie n .IP """isSPACE_utf8_safe""" 4
2762 .el .IP \f(CWisSPACE_utf8_safe\fR 4
2763 .IX Item "isSPACE_utf8_safe"
2764 .ie n .IP """isSPACE_uvchr""" 4
2765 .el .IP \f(CWisSPACE_uvchr\fR 4
2766 .IX Xref "isSPACE isSPACE_A isSPACE_LC isSPACE_LC_utf8_safe isSPACE_LC_uvchr isSPACE_L1 isSPACE_utf8 isSPACE_utf8_safe isSPACE_uvchr"
2767 .IX Item "isSPACE_uvchr"
2768 .PD
2769 Returns a boolean indicating whether the specified character is a
2770 whitespace character. This is analogous
2771 to what \f(CW\*(C`m/\es/\*(C'\fR matches in a regular expression. Starting in Perl 5.18
2772 this also matches what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does. Prior to 5.18, only the
2773 locale forms of this macro (the ones with \f(CW\*(C`LC\*(C'\fR in their names) matched
2774 precisely what \f(CW\*(C`m/[[:space:]]/\*(C'\fR does. In those releases, the only difference,
2775 in the non\-locale variants, was that \f(CWisSPACE()\fR did not match a vertical tab.
2776 (See "isPSXSPC" for a macro that matches a vertical tab in all releases.)
2777 See the top of this section for an explanation of
2778 the variants.
2779 .RS 4
2780 .Sp
2781 .Vb 9
2782 \& bool isSPACE (UV ch)
2783 \& bool isSPACE_A (UV ch)
2784 \& bool isSPACE_LC (UV ch)
2785 \& bool isSPACE_LC_utf8_safe(U8 * s, U8 *end)
2786 \& bool isSPACE_LC_uvchr (UV ch)
2787 \& bool isSPACE_L1 (UV ch)
2788 \& bool isSPACE_utf8 (U8 * s, U8 * end)
2789 \& bool isSPACE_utf8_safe (U8 * s, U8 * end)
2790 \& bool isSPACE_uvchr (UV ch)
2791 .Ve
2792 .RE
2793 .RS 4
2794 .RE
2795 .ie n .IP """isUPPER""" 4
2796 .el .IP \f(CWisUPPER\fR 4
2797 .IX Item "isUPPER"
2798 .PD 0
2799 .ie n .IP """isUPPER_A""" 4
2800 .el .IP \f(CWisUPPER_A\fR 4
2801 .IX Item "isUPPER_A"
2802 .ie n .IP """isUPPER_LC""" 4
2803 .el .IP \f(CWisUPPER_LC\fR 4
2804 .IX Item "isUPPER_LC"
2805 .ie n .IP """isUPPER_LC_utf8_safe""" 4
2806 .el .IP \f(CWisUPPER_LC_utf8_safe\fR 4
2807 .IX Item "isUPPER_LC_utf8_safe"
2808 .ie n .IP """isUPPER_LC_uvchr""" 4
2809 .el .IP \f(CWisUPPER_LC_uvchr\fR 4
2810 .IX Item "isUPPER_LC_uvchr"
2811 .ie n .IP """isUPPER_L1""" 4
2812 .el .IP \f(CWisUPPER_L1\fR 4
2813 .IX Item "isUPPER_L1"
2814 .ie n .IP """isUPPER_utf8""" 4
2815 .el .IP \f(CWisUPPER_utf8\fR 4
2816 .IX Item "isUPPER_utf8"
2817 .ie n .IP """isUPPER_utf8_safe""" 4
2818 .el .IP \f(CWisUPPER_utf8_safe\fR 4
2819 .IX Item "isUPPER_utf8_safe"
2820 .ie n .IP """isUPPER_uvchr""" 4
2821 .el .IP \f(CWisUPPER_uvchr\fR 4
2822 .IX Xref "isUPPER isUPPER_A isUPPER_LC isUPPER_LC_utf8_safe isUPPER_LC_uvchr isUPPER_L1 isUPPER_utf8 isUPPER_utf8_safe isUPPER_uvchr"
2823 .IX Item "isUPPER_uvchr"
2824 .PD
2825 Returns a boolean indicating whether the specified character is an
2826 uppercase character, analogous to \f(CW\*(C`m/[[:upper:]]/\*(C'\fR.
2827 See the top of this section for an explanation of
2828 the variants.
2829 .RS 4
2830 .Sp
2831 .Vb 9
2832 \& bool isUPPER (UV ch)
2833 \& bool isUPPER_A (UV ch)
2834 \& bool isUPPER_LC (UV ch)
2835 \& bool isUPPER_LC_utf8_safe(U8 * s, U8 *end)
2836 \& bool isUPPER_LC_uvchr (UV ch)
2837 \& bool isUPPER_L1 (UV ch)
2838 \& bool isUPPER_utf8 (U8 * s, U8 * end)
2839 \& bool isUPPER_utf8_safe (U8 * s, U8 * end)
2840 \& bool isUPPER_uvchr (UV ch)
2841 .Ve
2842 .RE
2843 .RS 4
2844 .RE
2845 .ie n .IP """isWORDCHAR""" 4
2846 .el .IP \f(CWisWORDCHAR\fR 4
2847 .IX Item "isWORDCHAR"
2848 .PD 0
2849 .ie n .IP """isWORDCHAR_A""" 4
2850 .el .IP \f(CWisWORDCHAR_A\fR 4
2851 .IX Item "isWORDCHAR_A"
2852 .ie n .IP """isWORDCHAR_LC""" 4
2853 .el .IP \f(CWisWORDCHAR_LC\fR 4
2854 .IX Item "isWORDCHAR_LC"
2855 .ie n .IP """isWORDCHAR_LC_utf8_safe""" 4
2856 .el .IP \f(CWisWORDCHAR_LC_utf8_safe\fR 4
2857 .IX Item "isWORDCHAR_LC_utf8_safe"
2858 .ie n .IP """isWORDCHAR_LC_uvchr""" 4
2859 .el .IP \f(CWisWORDCHAR_LC_uvchr\fR 4
2860 .IX Item "isWORDCHAR_LC_uvchr"
2861 .ie n .IP """isWORDCHAR_L1""" 4
2862 .el .IP \f(CWisWORDCHAR_L1\fR 4
2863 .IX Item "isWORDCHAR_L1"
2864 .ie n .IP """isWORDCHAR_utf8""" 4
2865 .el .IP \f(CWisWORDCHAR_utf8\fR 4
2866 .IX Item "isWORDCHAR_utf8"
2867 .ie n .IP """isWORDCHAR_utf8_safe""" 4
2868 .el .IP \f(CWisWORDCHAR_utf8_safe\fR 4
2869 .IX Item "isWORDCHAR_utf8_safe"
2870 .ie n .IP """isWORDCHAR_uvchr""" 4
2871 .el .IP \f(CWisWORDCHAR_uvchr\fR 4
2872 .IX Xref "isWORDCHAR isWORDCHAR_A isWORDCHAR_LC isWORDCHAR_LC_utf8_safe isWORDCHAR_LC_uvchr isWORDCHAR_L1 isWORDCHAR_utf8 isWORDCHAR_utf8_safe isWORDCHAR_uvchr"
2873 .IX Item "isWORDCHAR_uvchr"
2874 .PD
2875 Returns a boolean indicating whether the specified character is a character
2876 that is a word character, analogous to what \f(CW\*(C`m/\ew/\*(C'\fR and \f(CW\*(C`m/[[:word:]]/\*(C'\fR match
2877 in a regular expression. A word character is an alphabetic character, a
2878 decimal digit, a connecting punctuation character (such as an underscore), or
2879 a "mark" character that attaches to one of those (like some sort of accent).
2880 .Sp
2881 See the top of this section for an explanation of
2882 the variants.
2883 .Sp
2884 \&\f(CW\*(C`isWORDCHAR_A\*(C'\fR, \f(CW\*(C`isWORDCHAR_L1\*(C'\fR, \f(CW\*(C`isWORDCHAR_uvchr\*(C'\fR,
2885 \&\f(CW\*(C`isWORDCHAR_LC\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_uvchr\*(C'\fR, \f(CW\*(C`isWORDCHAR_LC_utf8\*(C'\fR, and
2886 \&\f(CW\*(C`isWORDCHAR_LC_utf8_safe\*(C'\fR are also as described there, but additionally
2887 include the platform\*(Aqs native underscore.
2888 .RS 4
2889 .Sp
2890 .Vb 9
2891 \& bool isWORDCHAR (UV ch)
2892 \& bool isWORDCHAR_A (UV ch)
2893 \& bool isWORDCHAR_LC (UV ch)
2894 \& bool isWORDCHAR_LC_utf8_safe(U8 * s, U8 *end)
2895 \& bool isWORDCHAR_LC_uvchr (UV ch)
2896 \& bool isWORDCHAR_L1 (UV ch)
2897 \& bool isWORDCHAR_utf8 (U8 * s, U8 * end)
2898 \& bool isWORDCHAR_utf8_safe (U8 * s, U8 * end)
2899 \& bool isWORDCHAR_uvchr (UV ch)
2900 .Ve
2901 .RE
2902 .RS 4
2903 .RE
2904 .ie n .IP """isXDIGIT""" 4
2905 .el .IP \f(CWisXDIGIT\fR 4
2906 .IX Item "isXDIGIT"
2907 .PD 0
2908 .ie n .IP """isXDIGIT_A""" 4
2909 .el .IP \f(CWisXDIGIT_A\fR 4
2910 .IX Item "isXDIGIT_A"
2911 .ie n .IP """isXDIGIT_LC""" 4
2912 .el .IP \f(CWisXDIGIT_LC\fR 4
2913 .IX Item "isXDIGIT_LC"
2914 .ie n .IP """isXDIGIT_LC_utf8_safe""" 4
2915 .el .IP \f(CWisXDIGIT_LC_utf8_safe\fR 4
2916 .IX Item "isXDIGIT_LC_utf8_safe"
2917 .ie n .IP """isXDIGIT_LC_uvchr""" 4
2918 .el .IP \f(CWisXDIGIT_LC_uvchr\fR 4
2919 .IX Item "isXDIGIT_LC_uvchr"
2920 .ie n .IP """isXDIGIT_L1""" 4
2921 .el .IP \f(CWisXDIGIT_L1\fR 4
2922 .IX Item "isXDIGIT_L1"
2923 .ie n .IP """isXDIGIT_utf8""" 4
2924 .el .IP \f(CWisXDIGIT_utf8\fR 4
2925 .IX Item "isXDIGIT_utf8"
2926 .ie n .IP """isXDIGIT_utf8_safe""" 4
2927 .el .IP \f(CWisXDIGIT_utf8_safe\fR 4
2928 .IX Item "isXDIGIT_utf8_safe"
2929 .ie n .IP """isXDIGIT_uvchr""" 4
2930 .el .IP \f(CWisXDIGIT_uvchr\fR 4
2931 .IX Xref "isXDIGIT isXDIGIT_A isXDIGIT_LC isXDIGIT_LC_utf8_safe isXDIGIT_LC_uvchr isXDIGIT_L1 isXDIGIT_utf8 isXDIGIT_utf8_safe isXDIGIT_uvchr"
2932 .IX Item "isXDIGIT_uvchr"
2933 .PD
2934 Returns a boolean indicating whether the specified character is a hexadecimal
2935 digit. In the ASCII range these are \f(CW\*(C`[0\-9A\-Fa\-f]\*(C'\fR. Variants \f(CWisXDIGIT_A()\fR
2936 and \f(CWisXDIGIT_L1()\fR are identical to \f(CWisXDIGIT()\fR.
2937 See the top of this section for an explanation of
2938 the variants.
2939 .RS 4
2940 .Sp
2941 .Vb 9
2942 \& bool isXDIGIT (UV ch)
2943 \& bool isXDIGIT_A (UV ch)
2944 \& bool isXDIGIT_LC (UV ch)
2945 \& bool isXDIGIT_LC_utf8_safe(U8 * s, U8 *end)
2946 \& bool isXDIGIT_LC_uvchr (UV ch)
2947 \& bool isXDIGIT_L1 (UV ch)
2948 \& bool isXDIGIT_utf8 (U8 * s, U8 * end)
2949 \& bool isXDIGIT_utf8_safe (U8 * s, U8 * end)
2950 \& bool isXDIGIT_uvchr (UV ch)
2951 .Ve
2952 .RE
2953 .RS 4
2954 .RE
2955 .SH "Compiler and Preprocessor information"
2956 .IX Header "Compiler and Preprocessor information"
2957 .ie n .IP """CPPLAST""" 4
2958 .el .IP \f(CWCPPLAST\fR 4
2959 .IX Xref "CPPLAST"
2960 .IX Item "CPPLAST"
2961 This symbol is intended to be used along with \f(CW\*(C`CPPRUN\*(C'\fR in the same manner
2962 symbol \f(CW\*(C`CPPMINUS\*(C'\fR is used with \f(CW\*(C`CPPSTDIN\*(C'\fR. It contains either "\-" or "".
2963 .ie n .IP """CPPMINUS""" 4
2964 .el .IP \f(CWCPPMINUS\fR 4
2965 .IX Xref "CPPMINUS"
2966 .IX Item "CPPMINUS"
2967 This symbol contains the second part of the string which will invoke
2968 the C preprocessor on the standard input and produce to standard
2969 output. This symbol will have the value "\-" if \f(CW\*(C`CPPSTDIN\*(C'\fR needs a minus
2970 to specify standard input, otherwise the value is "".
2971 .ie n .IP """CPPRUN""" 4
2972 .el .IP \f(CWCPPRUN\fR 4
2973 .IX Xref "CPPRUN"
2974 .IX Item "CPPRUN"
2975 This symbol contains the string which will invoke a C preprocessor on
2976 the standard input and produce to standard output. It needs to end
2977 with \f(CW\*(C`CPPLAST\*(C'\fR, after all other preprocessor flags have been specified.
2978 The main difference with \f(CW\*(C`CPPSTDIN\*(C'\fR is that this program will never be a
2979 pointer to a shell wrapper, i.e. it will be empty if no preprocessor is
2980 available directly to the user. Note that it may well be different from
2981 the preprocessor used to compile the C program.
2982 .ie n .IP """CPPSTDIN""" 4
2983 .el .IP \f(CWCPPSTDIN\fR 4
2984 .IX Xref "CPPSTDIN"
2985 .IX Item "CPPSTDIN"
2986 This symbol contains the first part of the string which will invoke
2987 the C preprocessor on the standard input and produce to standard
2988 output. Typical value of "cc \-E" or "\fI/lib/cpp\fR", but it can also
2989 call a wrapper. See \f(CW"CPPRUN"\fR.
2990 .ie n .IP """HAS_BUILTIN_ADD_OVERFLOW""" 4
2991 .el .IP \f(CWHAS_BUILTIN_ADD_OVERFLOW\fR 4
2992 .IX Xref "HAS_BUILTIN_ADD_OVERFLOW"
2993 .IX Item "HAS_BUILTIN_ADD_OVERFLOW"
2994 This symbol, if defined, indicates that the compiler supports
2995 \&\f(CW\*(C`_\|_builtin_add_overflow\*(C'\fR for adding integers with overflow checks.
2996 .ie n .IP """HAS_BUILTIN_CHOOSE_EXPR""" 4
2997 .el .IP \f(CWHAS_BUILTIN_CHOOSE_EXPR\fR 4
2998 .IX Xref "HAS_BUILTIN_CHOOSE_EXPR"
2999 .IX Item "HAS_BUILTIN_CHOOSE_EXPR"
3000 Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for compile\-time ternary\-like expressions
3001 .ie n .IP """HAS_BUILTIN_EXPECT""" 4
3002 .el .IP \f(CWHAS_BUILTIN_EXPECT\fR 4
3003 .IX Xref "HAS_BUILTIN_EXPECT"
3004 .IX Item "HAS_BUILTIN_EXPECT"
3005 Can we handle \f(CW\*(C`GCC\*(C'\fR builtin for telling that certain values are more
3006 likely
3007 .ie n .IP """HAS_BUILTIN_MUL_OVERFLOW""" 4
3008 .el .IP \f(CWHAS_BUILTIN_MUL_OVERFLOW\fR 4
3009 .IX Xref "HAS_BUILTIN_MUL_OVERFLOW"
3010 .IX Item "HAS_BUILTIN_MUL_OVERFLOW"
3011 This symbol, if defined, indicates that the compiler supports
3012 \&\f(CW\*(C`_\|_builtin_mul_overflow\*(C'\fR for multiplying integers with overflow checks.
3013 .ie n .IP """HAS_BUILTIN_SUB_OVERFLOW""" 4
3014 .el .IP \f(CWHAS_BUILTIN_SUB_OVERFLOW\fR 4
3015 .IX Xref "HAS_BUILTIN_SUB_OVERFLOW"
3016 .IX Item "HAS_BUILTIN_SUB_OVERFLOW"
3017 This symbol, if defined, indicates that the compiler supports
3018 \&\f(CW\*(C`_\|_builtin_sub_overflow\*(C'\fR for subtracting integers with overflow checks.
3019 .ie n .IP """HAS_C99_VARIADIC_MACROS""" 4
3020 .el .IP \f(CWHAS_C99_VARIADIC_MACROS\fR 4
3021 .IX Xref "HAS_C99_VARIADIC_MACROS"
3022 .IX Item "HAS_C99_VARIADIC_MACROS"
3023 If defined, the compiler supports C99 variadic macros.
3024 .ie n .IP """HAS_STATIC_INLINE""" 4
3025 .el .IP \f(CWHAS_STATIC_INLINE\fR 4
3026 .IX Xref "HAS_STATIC_INLINE"
3027 .IX Item "HAS_STATIC_INLINE"
3028 This symbol, if defined, indicates that the C compiler supports
3029 C99\-style static inline. That is, the function can\*(Aqt be called
3030 from another translation unit.
3031 .ie n .IP """HASATTRIBUTE_ALWAYS_INLINE""" 4
3032 .el .IP \f(CWHASATTRIBUTE_ALWAYS_INLINE\fR 4
3033 .IX Xref "HASATTRIBUTE_ALWAYS_INLINE"
3034 .IX Item "HASATTRIBUTE_ALWAYS_INLINE"
3035 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should always be
3036 inlined.
3037 .ie n .IP """HASATTRIBUTE_DEPRECATED""" 4
3038 .el .IP \f(CWHASATTRIBUTE_DEPRECATED\fR 4
3039 .IX Xref "HASATTRIBUTE_DEPRECATED"
3040 .IX Item "HASATTRIBUTE_DEPRECATED"
3041 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for marking deprecated \f(CW\*(C`APIs\*(C'\fR
3042 .ie n .IP """HASATTRIBUTE_FORMAT""" 4
3043 .el .IP \f(CWHASATTRIBUTE_FORMAT\fR 4
3044 .IX Xref "HASATTRIBUTE_FORMAT"
3045 .IX Item "HASATTRIBUTE_FORMAT"
3046 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for checking printf\-style formats
3047 .ie n .IP """HASATTRIBUTE_NONNULL""" 4
3048 .el .IP \f(CWHASATTRIBUTE_NONNULL\fR 4
3049 .IX Xref "HASATTRIBUTE_NONNULL"
3050 .IX Item "HASATTRIBUTE_NONNULL"
3051 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for nonnull function parms.
3052 .ie n .IP """HASATTRIBUTE_NORETURN""" 4
3053 .el .IP \f(CWHASATTRIBUTE_NORETURN\fR 4
3054 .IX Xref "HASATTRIBUTE_NORETURN"
3055 .IX Item "HASATTRIBUTE_NORETURN"
3056 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that do not return
3057 .ie n .IP """HASATTRIBUTE_PURE""" 4
3058 .el .IP \f(CWHASATTRIBUTE_PURE\fR 4
3059 .IX Xref "HASATTRIBUTE_PURE"
3060 .IX Item "HASATTRIBUTE_PURE"
3061 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for pure functions
3062 .ie n .IP """HASATTRIBUTE_UNUSED""" 4
3063 .el .IP \f(CWHASATTRIBUTE_UNUSED\fR 4
3064 .IX Xref "HASATTRIBUTE_UNUSED"
3065 .IX Item "HASATTRIBUTE_UNUSED"
3066 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for unused variables and arguments
3067 .ie n .IP """HASATTRIBUTE_VISIBILITY""" 4
3068 .el .IP \f(CWHASATTRIBUTE_VISIBILITY\fR 4
3069 .IX Xref "HASATTRIBUTE_VISIBILITY"
3070 .IX Item "HASATTRIBUTE_VISIBILITY"
3071 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for functions that should have a
3072 different visibility.
3073 .ie n .IP """HASATTRIBUTE_WARN_UNUSED_RESULT""" 4
3074 .el .IP \f(CWHASATTRIBUTE_WARN_UNUSED_RESULT\fR 4
3075 .IX Xref "HASATTRIBUTE_WARN_UNUSED_RESULT"
3076 .IX Item "HASATTRIBUTE_WARN_UNUSED_RESULT"
3077 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for warning on unused results
3078 .ie n .IP """MEM_ALIGNBYTES""" 4
3079 .el .IP \f(CWMEM_ALIGNBYTES\fR 4
3080 .IX Xref "MEM_ALIGNBYTES"
3081 .IX Item "MEM_ALIGNBYTES"
3082 This symbol contains the number of bytes required to align a
3083 double, or a long double when applicable. Usual values are 2,
3084 4 and 8. The default is eight, for safety. For cross\-compiling
3085 or multiarch support, Configure will set a minimum of 8.
3086 .ie n .IP """PERL_STATIC_INLINE""" 4
3087 .el .IP \f(CWPERL_STATIC_INLINE\fR 4
3088 .IX Xref "PERL_STATIC_INLINE"
3089 .IX Item "PERL_STATIC_INLINE"
3090 This symbol gives the best\-guess incantation to use for static
3091 inline functions. If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is defined, this will
3092 give C99\-style inline. If \f(CW\*(C`HAS_STATIC_INLINE\*(C'\fR is not defined,
3093 this will give a plain \*(Aqstatic\*(Aq. It will always be defined
3094 to something that gives static linkage.
3095 Possibilities include
3096 .Sp
3097 .Vb 5
3098 \& static inline (c99)
3099 \& static _\|_inline_\|_ (gcc \-ansi)
3100 \& static _\|_inline (MSVC)
3101 \& static _inline (older MSVC)
3102 \& static (c89 compilers)
3103 .Ve
3104 .ie n .IP """PERL_THREAD_LOCAL""" 4
3105 .el .IP \f(CWPERL_THREAD_LOCAL\fR 4
3106 .IX Xref "PERL_THREAD_LOCAL"
3107 .IX Item "PERL_THREAD_LOCAL"
3108 This symbol, if defined, gives a linkage specification for thread\-local
3109 storage. For example, for a C11 compiler this will be \f(CW\*(C`_Thread_local\*(C'\fR.
3110 Beware, some compilers are sensitive to the C language standard they are
3111 told to parse. For example, suncc defaults to C11, so our probe will
3112 report that \f(CW\*(C`_Thread_local\*(C'\fR can be used. However, if the \-std=c99 is later
3113 added to the compiler flags, then \f(CW\*(C`_Thread_local\*(C'\fR will become a syntax
3114 error. Hence it is important for these flags to be consistent between
3115 probing and use.
3116 .ie n .IP """U32_ALIGNMENT_REQUIRED""" 4
3117 .el .IP \f(CWU32_ALIGNMENT_REQUIRED\fR 4
3118 .IX Xref "U32_ALIGNMENT_REQUIRED"
3119 .IX Item "U32_ALIGNMENT_REQUIRED"
3120 This symbol, if defined, indicates that you must access
3121 character data through U32\-aligned pointers.
3122 .SH "Compiler directives"
3123 .IX Header "Compiler directives"
3124 .ie n .IP """_\|_ASSERT_""" 4
3125 .el .IP \f(CW_\|_ASSERT_\fR 4
3126 .IX Xref "__ASSERT_"
3127 .IX Item "__ASSERT_"
3128 This is a helper macro to avoid preprocessor issues, replaced by nothing
3129 unless under DEBUGGING, where it expands to an assert of its argument,
3130 followed by a comma (hence the comma operator). If we just used a straight
3131 \&\fBassert()\fR, we would get a comma with nothing before it when not DEBUGGING.
3132 .RS 4
3133 .Sp
3134 .Vb 1
3135 \& _\|_ASSERT_(bool expr)
3136 .Ve
3137 .RE
3138 .RS 4
3139 .RE
3140 .ie n .IP """ASSUME""" 4
3141 .el .IP \f(CWASSUME\fR 4
3142 .IX Xref "ASSUME"
3143 .IX Item "ASSUME"
3144 \&\f(CW\*(C`ASSUME\*(C'\fR is like \f(CWassert()\fR, but it has a benefit in a release build. It is a
3145 hint to a compiler about a statement of fact in a function call free
3146 expression, which allows the compiler to generate better machine code. In a
3147 debug build, \f(CWASSUME(x)\fR is a synonym for \f(CWassert(x)\fR. \f(CWASSUME(0)\fR means the
3148 control path is unreachable. In a for loop, \f(CW\*(C`ASSUME\*(C'\fR can be used to hint that
3149 a loop will run at least X times. \f(CW\*(C`ASSUME\*(C'\fR is based off MSVC\*(Aqs \f(CW\*(C`_\|_assume\*(C'\fR
3150 intrinsic function, see its documents for more details.
3151 .RS 4
3152 .Sp
3153 .Vb 1
3154 \& ASSUME(bool expr)
3155 .Ve
3156 .RE
3157 .RS 4
3158 .RE
3159 .ie n .IP """dNOOP""" 4
3160 .el .IP \f(CWdNOOP\fR 4
3161 .IX Xref "dNOOP"
3162 .IX Item "dNOOP"
3163 Declare nothing; typically used as a placeholder to replace something that used
3164 to declare something. Works on compilers that require declarations before any
3165 code.
3166 .RS 4
3167 .Sp
3168 .Vb 1
3169 \& dNOOP;
3170 .Ve
3171 .RE
3172 .RS 4
3173 .RE
3174 .ie n .IP """END_EXTERN_C""" 4
3175 .el .IP \f(CWEND_EXTERN_C\fR 4
3176 .IX Xref "END_EXTERN_C"
3177 .IX Item "END_EXTERN_C"
3178 When not compiling using C++, expands to nothing.
3179 Otherwise ends a section of code already begun by a \f(CW"START_EXTERN_C"\fR.
3180 .ie n .IP """EXTERN_C""" 4
3181 .el .IP \f(CWEXTERN_C\fR 4
3182 .IX Xref "EXTERN_C"
3183 .IX Item "EXTERN_C"
3184 When not compiling using C++, expands to nothing.
3185 Otherwise is used in a declaration of a function to indicate the function
3186 should have external C linkage. This is required for things to work for just
3187 about all functions with external linkage compiled into perl.
3188 Often, you can use \f(CW"START_EXTERN_C"\fR ... \f(CW"END_EXTERN_C"\fR blocks
3189 surrounding all your code that you need to have this linkage.
3190 .Sp
3191 Example usage:
3192 .Sp
3193 .Vb 1
3194 \& EXTERN_C int flock(int fd, int op);
3195 .Ve
3196 .ie n .IP """LIKELY""" 4
3197 .el .IP \f(CWLIKELY\fR 4
3198 .IX Xref "LIKELY"
3199 .IX Item "LIKELY"
3200 Returns the input unchanged, but at the same time it gives a branch prediction
3201 hint to the compiler that this condition is likely to be true.
3202 .RS 4
3203 .Sp
3204 .Vb 1
3205 \& LIKELY(bool expr)
3206 .Ve
3207 .RE
3208 .RS 4
3209 .RE
3210 .ie n .IP """NOOP""" 4
3211 .el .IP \f(CWNOOP\fR 4
3212 .IX Xref "NOOP"
3213 .IX Item "NOOP"
3214 Do nothing; typically used as a placeholder to replace something that used to
3215 do something.
3216 .RS 4
3217 .Sp
3218 .Vb 1
3219 \& NOOP;
3220 .Ve
3221 .RE
3222 .RS 4
3223 .RE
3224 .ie n .IP """PERL_UNUSED_ARG""" 4
3225 .el .IP \f(CWPERL_UNUSED_ARG\fR 4
3226 .IX Xref "PERL_UNUSED_ARG"
3227 .IX Item "PERL_UNUSED_ARG"
3228 This is used to suppress compiler warnings that a parameter to a function is
3229 not used. This situation can arise, for example, when a parameter is needed
3230 under some configuration conditions, but not others, so that C preprocessor
3231 conditional compilation causes it be used just sometimes.
3232 .RS 4
3233 .Sp
3234 .Vb 1
3235 \& PERL_UNUSED_ARG(void x);
3236 .Ve
3237 .RE
3238 .RS 4
3239 .RE
3240 .ie n .IP """PERL_UNUSED_CONTEXT""" 4
3241 .el .IP \f(CWPERL_UNUSED_CONTEXT\fR 4
3242 .IX Xref "PERL_UNUSED_CONTEXT"
3243 .IX Item "PERL_UNUSED_CONTEXT"
3244 This is used to suppress compiler warnings that the thread context parameter to
3245 a function is not used. This situation can arise, for example, when a
3246 C preprocessor conditional compilation causes it be used just some times.
3247 .RS 4
3248 .Sp
3249 .Vb 1
3250 \& PERL_UNUSED_CONTEXT;
3251 .Ve
3252 .RE
3253 .RS 4
3254 .RE
3255 .ie n .IP """PERL_UNUSED_DECL""" 4
3256 .el .IP \f(CWPERL_UNUSED_DECL\fR 4
3257 .IX Xref "PERL_UNUSED_DECL"
3258 .IX Item "PERL_UNUSED_DECL"
3259 Tells the compiler that the parameter in the function prototype just before it
3260 is not necessarily expected to be used in the function. Not that many
3261 compilers understand this, so this should only be used in cases where
3262 \&\f(CW"PERL_UNUSED_ARG"\fR can\*(Aqt conveniently be used.
3263 .Sp
3264 Example usage:
3265 .RS 4
3266 .Sp
3267 .Vb 3
3268 \& Signal_t
3269 \& Perl_perly_sighandler(int sig, Siginfo_t *sip PERL_UNUSED_DECL,
3270 \& void *uap PERL_UNUSED_DECL, bool safe)
3271 .Ve
3272 .RE
3273 .RS 4
3274 .RE
3275 .ie n .IP """PERL_UNUSED_RESULT""" 4
3276 .el .IP \f(CWPERL_UNUSED_RESULT\fR 4
3277 .IX Xref "PERL_UNUSED_RESULT"
3278 .IX Item "PERL_UNUSED_RESULT"
3279 This macro indicates to discard the return value of the function call inside
3280 it, \fIe.g.\fR,
3281 .Sp
3282 .Vb 1
3283 \& PERL_UNUSED_RESULT(foo(a, b))
3284 .Ve
3285 .Sp
3286 The main reason for this is that the combination of \f(CW\*(C`gcc \-Wunused\-result\*(C'\fR
3287 (part of \f(CW\*(C`\-Wall\*(C'\fR) and the \f(CW\*(C`_\|_attribute_\|_((warn_unused_result))\*(C'\fR cannot
3288 be silenced with casting to \f(CW\*(C`void\*(C'\fR. This causes trouble when the system
3289 header files use the attribute.
3290 .Sp
3291 Use \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR sparingly, though, since usually the warning
3292 is there for a good reason: you might lose success/failure information,
3293 or leak resources, or changes in resources.
3294 .Sp
3295 But sometimes you just want to ignore the return value, \fIe.g.\fR, on
3296 codepaths soon ending up in abort, or in "best effort" attempts,
3297 or in situations where there is no good way to handle failures.
3298 .Sp
3299 Sometimes \f(CW\*(C`PERL_UNUSED_RESULT\*(C'\fR might not be the most natural way:
3300 another possibility is that you can capture the return value
3301 and use \f(CW"PERL_UNUSED_VAR"\fR on that.
3302 .RS 4
3303 .Sp
3304 .Vb 1
3305 \& PERL_UNUSED_RESULT(void x)
3306 .Ve
3307 .RE
3308 .RS 4
3309 .RE
3310 .ie n .IP """PERL_UNUSED_VAR""" 4
3311 .el .IP \f(CWPERL_UNUSED_VAR\fR 4
3312 .IX Xref "PERL_UNUSED_VAR"
3313 .IX Item "PERL_UNUSED_VAR"
3314 This is used to suppress compiler warnings that the variable \fIx\fR is not used.
3315 This situation can arise, for example, when a C preprocessor conditional
3316 compilation causes it be used just some times.
3317 .RS 4
3318 .Sp
3319 .Vb 1
3320 \& PERL_UNUSED_VAR(void x);
3321 .Ve
3322 .RE
3323 .RS 4
3324 .RE
3325 .ie n .IP """START_EXTERN_C""" 4
3326 .el .IP \f(CWSTART_EXTERN_C\fR 4
3327 .IX Xref "START_EXTERN_C"
3328 .IX Item "START_EXTERN_C"
3329 When not compiling using C++, expands to nothing.
3330 Otherwise begins a section of code in which every function will effectively
3331 have \f(CW"EXTERN_C"\fR applied to it, that is to have external C linkage. The
3332 section is ended by a \f(CW"END_EXTERN_C"\fR.
3333 .ie n .IP """STATIC""" 4
3334 .el .IP \f(CWSTATIC\fR 4
3335 .IX Item "STATIC"
3336 Described in perlguts.
3337 .ie n .IP """STMT_START""" 4
3338 .el .IP \f(CWSTMT_START\fR 4
3339 .IX Item "STMT_START"
3340 .PD 0
3341 .ie n .IP """STMT_END""" 4
3342 .el .IP \f(CWSTMT_END\fR 4
3343 .IX Xref "STMT_END STMT_START"
3344 .IX Item "STMT_END"
3345 .PD
3346 These allow a series of statements in a macro to be used as a single statement,
3347 as in
3348 .Sp
3349 .Vb 1
3350 \& if (x) STMT_START { ... } STMT_END else ...
3351 .Ve
3352 .Sp
3353 Note that you can\*(Aqt return a value out of this construct and cannot use it as
3354 an operand to the comma operator. These limit its utility.
3355 .Sp
3356 But, a value could be returned by constructing the API so that a pointer is
3357 passed and the macro dereferences this to set the return. If the value can be
3358 any of various types, depending on context, you can handle that situation in
3359 some situations by adding the type of the return as an extra accompanying
3360 parameter:
3361 .Sp
3362 .Vb 3
3363 \& #define foo(param, type) STMT_START {
3364 \& type * param; *param = do_calc; ...
3365 \& } STMT_END
3366 .Ve
3367 .Sp
3368 This could be awkward, so consider instead using a C language \f(CW\*(C`static inline\*(C'\fR
3369 function.
3370 .Sp
3371 If you do use this construct, it is easy to forget that it is a macro and not a
3372 function, and hence fall into traps that might not show up until someone
3373 someday writes code which contains names that clash with the ones you chose
3374 here, or calls it with a parameter which is an expression with side effects,
3375 the consequences of which you didn\*(Aqt think about. See "Writing
3376 safer macros" in perlhacktips for how to avoid these.
3377 .ie n .IP """UNLIKELY""" 4
3378 .el .IP \f(CWUNLIKELY\fR 4
3379 .IX Xref "UNLIKELY"
3380 .IX Item "UNLIKELY"
3381 Returns the input unchanged, but at the same time it gives a branch prediction
3382 hint to the compiler that this condition is likely to be false.
3383 .RS 4
3384 .Sp
3385 .Vb 1
3386 \& UNLIKELY(bool expr)
3387 .Ve
3388 .RE
3389 .RS 4
3390 .RE
3391 .SH "Compile\-time scope hooks"
3392 .IX Header "Compile-time scope hooks"
3393 .ie n .IP """BhkDISABLE""" 4
3394 .el .IP \f(CWBhkDISABLE\fR 4
3395 .IX Xref "BhkDISABLE"
3396 .IX Item "BhkDISABLE"
3397 NOTE: \f(CW\*(C`BhkDISABLE\*(C'\fR is \fBexperimental\fR and may change or be
3398 removed without notice.
3399 .Sp
3400 Temporarily disable an entry in this BHK structure, by clearing the
3401 appropriate flag. \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which
3402 entry to disable.
3403 .RS 4
3404 .Sp
3405 .Vb 1
3406 \& void BhkDISABLE(BHK *hk, token which)
3407 .Ve
3408 .RE
3409 .RS 4
3410 .RE
3411 .ie n .IP """BhkENABLE""" 4
3412 .el .IP \f(CWBhkENABLE\fR 4
3413 .IX Xref "BhkENABLE"
3414 .IX Item "BhkENABLE"
3415 NOTE: \f(CW\*(C`BhkENABLE\*(C'\fR is \fBexperimental\fR and may change or be
3416 removed without notice.
3417 .Sp
3418 Re\-enable an entry in this BHK structure, by setting the appropriate
3419 flag. \f(CW\*(C`which\*(C'\fR is a preprocessor token indicating which entry to enable.
3420 This will assert (under \-DDEBUGGING) if the entry doesn\*(Aqt contain a valid
3421 pointer.
3422 .RS 4
3423 .Sp
3424 .Vb 1
3425 \& void BhkENABLE(BHK *hk, token which)
3426 .Ve
3427 .RE
3428 .RS 4
3429 .RE
3430 .ie n .IP """BhkENTRY_set""" 4
3431 .el .IP \f(CWBhkENTRY_set\fR 4
3432 .IX Xref "BhkENTRY_set"
3433 .IX Item "BhkENTRY_set"
3434 NOTE: \f(CW\*(C`BhkENTRY_set\*(C'\fR is \fBexperimental\fR and may change or be
3435 removed without notice.
3436 .Sp
3437 Set an entry in the BHK structure, and set the flags to indicate it is
3438 valid. \f(CW\*(C`which\*(C'\fR is a preprocessing token indicating which entry to set.
3439 The type of \f(CW\*(C`ptr\*(C'\fR depends on the entry.
3440 .RS 4
3441 .Sp
3442 .Vb 1
3443 \& void BhkENTRY_set(BHK *hk, token which, void *ptr)
3444 .Ve
3445 .RE
3446 .RS 4
3447 .RE
3448 .ie n .IP """blockhook_register""" 4
3449 .el .IP \f(CWblockhook_register\fR 4
3450 .IX Xref "blockhook_register"
3451 .IX Item "blockhook_register"
3452 NOTE: \f(CW\*(C`blockhook_register\*(C'\fR is \fBexperimental\fR and may change or be
3453 removed without notice.
3454 .Sp
3455 Register a set of hooks to be called when the Perl lexical scope changes
3456 at compile time. See "Compile\-time scope hooks" in perlguts.
3457 .RS 4
3458 .Sp
3459 .Vb 1
3460 \& void Perl_blockhook_register(pTHX_ BHK *hk)
3461 .Ve
3462 .RE
3463 .RS 4
3464 .RE
3465 .SH Concurrency
3466 .IX Header "Concurrency"
3467 .ie n .IP """aTHX""" 4
3468 .el .IP \f(CWaTHX\fR 4
3469 .IX Item "aTHX"
3470 .PD 0
3471 .ie n .IP """aTHX_""" 4
3472 .el .IP \f(CWaTHX_\fR 4
3473 .IX Item "aTHX_"
3474 .PD
3475 Described in perlguts.
3476 .ie n .IP """CPERLscope""" 4
3477 .el .IP \f(CWCPERLscope\fR 4
3478 .IX Xref "CPERLscope"
3479 .IX Item "CPERLscope"
3480 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`CPERLscope\*(C'\fR
3481 from a future release of Perl. Do not use it for
3482 new code; remove it from existing code.
3483 .Sp
3484 Now a no\-op.
3485 .RS 4
3486 .Sp
3487 .Vb 1
3488 \& void CPERLscope(void x)
3489 .Ve
3490 .RE
3491 .RS 4
3492 .RE
3493 .ie n .IP """dTHR""" 4
3494 .el .IP \f(CWdTHR\fR 4
3495 .IX Item "dTHR"
3496 .PD 0
3497 .ie n .IP """dTHX""" 4
3498 .el .IP \f(CWdTHX\fR 4
3499 .IX Item "dTHX"
3500 .PD
3501 Described in perlguts.
3502 .ie n .IP """dTHXa""" 4
3503 .el .IP \f(CWdTHXa\fR 4
3504 .IX Xref "dTHXa"
3505 .IX Item "dTHXa"
3506 On threaded perls, set \f(CW\*(C`pTHX\*(C'\fR to \f(CW\*(C`a\*(C'\fR; on unthreaded perls, do nothing
3507 .ie n .IP """dTHXoa""" 4
3508 .el .IP \f(CWdTHXoa\fR 4
3509 .IX Xref "dTHXoa"
3510 .IX Item "dTHXoa"
3511 Now a synonym for \f(CW"dTHXa"\fR.
3512 .ie n .IP """dVAR""" 4
3513 .el .IP \f(CWdVAR\fR 4
3514 .IX Xref "dVAR"
3515 .IX Item "dVAR"
3516 This is now a synonym for dNOOP: declare nothing
3517 .ie n .IP """GETENV_PRESERVES_OTHER_THREAD""" 4
3518 .el .IP \f(CWGETENV_PRESERVES_OTHER_THREAD\fR 4
3519 .IX Xref "GETENV_PRESERVES_OTHER_THREAD"
3520 .IX Item "GETENV_PRESERVES_OTHER_THREAD"
3521 This symbol, if defined, indicates that the getenv system call doesn\*(Aqt
3522 zap the static buffer of \f(CWgetenv()\fR in a different thread.
3523 The typical \f(CWgetenv()\fR implementation will return a pointer to the proper
3524 position in **environ. But some may instead copy them to a static
3525 buffer in \f(CWgetenv()\fR. If there is a per\-thread instance of that buffer,
3526 or the return points to **environ, then a many\-reader/1\-writer mutex
3527 will work; otherwise an exclusive locking mutex is required to prevent
3528 races.
3529 .ie n .IP """HAS_PTHREAD_ATFORK""" 4
3530 .el .IP \f(CWHAS_PTHREAD_ATFORK\fR 4
3531 .IX Xref "HAS_PTHREAD_ATFORK"
3532 .IX Item "HAS_PTHREAD_ATFORK"
3533 This symbol, if defined, indicates that the \f(CW\*(C`pthread_atfork\*(C'\fR routine
3534 is available to setup fork handlers.
3535 .ie n .IP """HAS_PTHREAD_ATTR_SETSCOPE""" 4
3536 .el .IP \f(CWHAS_PTHREAD_ATTR_SETSCOPE\fR 4
3537 .IX Xref "HAS_PTHREAD_ATTR_SETSCOPE"
3538 .IX Item "HAS_PTHREAD_ATTR_SETSCOPE"
3539 This symbol, if defined, indicates that the \f(CW\*(C`pthread_attr_setscope\*(C'\fR
3540 system call is available to set the contention scope attribute of
3541 a thread attribute object.
3542 .ie n .IP """HAS_PTHREAD_YIELD""" 4
3543 .el .IP \f(CWHAS_PTHREAD_YIELD\fR 4
3544 .IX Xref "HAS_PTHREAD_YIELD"
3545 .IX Item "HAS_PTHREAD_YIELD"
3546 This symbol, if defined, indicates that the \f(CW\*(C`pthread_yield\*(C'\fR
3547 routine is available to yield the execution of the current
3548 thread. \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR.
3549 .ie n .IP """HAS_SCHED_YIELD""" 4
3550 .el .IP \f(CWHAS_SCHED_YIELD\fR 4
3551 .IX Xref "HAS_SCHED_YIELD"
3552 .IX Item "HAS_SCHED_YIELD"
3553 This symbol, if defined, indicates that the \f(CW\*(C`sched_yield\*(C'\fR
3554 routine is available to yield the execution of the current
3555 thread. \f(CW\*(C`sched_yield\*(C'\fR is preferable to \f(CW\*(C`pthread_yield\*(C'\fR.
3556 .ie n .IP """I_MACH_CTHREADS""" 4
3557 .el .IP \f(CWI_MACH_CTHREADS\fR 4
3558 .IX Xref "I_MACH_CTHREADS"
3559 .IX Item "I_MACH_CTHREADS"
3560 This symbol, if defined, indicates to the C program that it should
3561 include \fImach/cthreads.h\fR.
3562 .RS 4
3563 .Sp
3564 .Vb 3
3565 \& #ifdef I_MACH_CTHREADS
3566 \& #include <mach_cthreads.h>
3567 \& #endif
3568 .Ve
3569 .RE
3570 .RS 4
3571 .RE
3572 .ie n .IP """I_PTHREAD""" 4
3573 .el .IP \f(CWI_PTHREAD\fR 4
3574 .IX Xref "I_PTHREAD"
3575 .IX Item "I_PTHREAD"
3576 This symbol, if defined, indicates to the C program that it should
3577 include \fIpthread.h\fR.
3578 .RS 4
3579 .Sp
3580 .Vb 3
3581 \& #ifdef I_PTHREAD
3582 \& #include <pthread.h>
3583 \& #endif
3584 .Ve
3585 .RE
3586 .RS 4
3587 .RE
3588 .ie n .IP """MULTIPLICITY""" 4
3589 .el .IP \f(CWMULTIPLICITY\fR 4
3590 .IX Item "MULTIPLICITY"
3591 This symbol, if defined, indicates that Perl should
3592 be built to use multiplicity.
3593 .ie n .IP """OLD_PTHREAD_CREATE_JOINABLE""" 4
3594 .el .IP \f(CWOLD_PTHREAD_CREATE_JOINABLE\fR 4
3595 .IX Xref "OLD_PTHREAD_CREATE_JOINABLE"
3596 .IX Item "OLD_PTHREAD_CREATE_JOINABLE"
3597 This symbol, if defined, indicates how to create pthread
3598 in joinable (aka undetached) state. \f(CW\*(C`NOTE\*(C'\fR: not defined
3599 if \fIpthread.h\fR already has defined \f(CW\*(C`PTHREAD_CREATE_JOINABLE\*(C'\fR
3600 (the new version of the constant).
3601 If defined, known values are \f(CW\*(C`PTHREAD_CREATE_UNDETACHED\*(C'\fR
3602 and \f(CW\*(C`_\|_UNDETACHED\*(C'\fR.
3603 .ie n .IP """OLD_PTHREADS_API""" 4
3604 .el .IP \f(CWOLD_PTHREADS_API\fR 4
3605 .IX Xref "OLD_PTHREADS_API"
3606 .IX Item "OLD_PTHREADS_API"
3607 This symbol, if defined, indicates that Perl should
3608 be built to use the old draft \f(CW\*(C`POSIX\*(C'\fR threads \f(CW\*(C`API\*(C'\fR.
3609 .ie n .IP """PERL_IMPLICIT_CONTEXT""" 4
3610 .el .IP \f(CWPERL_IMPLICIT_CONTEXT\fR 4
3611 .IX Item "PERL_IMPLICIT_CONTEXT"
3612 .PD 0
3613 .ie n .IP """PERL_NO_GET_CONTEXT""" 4
3614 .el .IP \f(CWPERL_NO_GET_CONTEXT\fR 4
3615 .IX Item "PERL_NO_GET_CONTEXT"
3616 .ie n .IP """pTHX""" 4
3617 .el .IP \f(CWpTHX\fR 4
3618 .IX Item "pTHX"
3619 .ie n .IP """pTHX_""" 4
3620 .el .IP \f(CWpTHX_\fR 4
3621 .IX Item "pTHX_"
3622 .PD
3623 Described in perlguts.
3624 .ie n .IP """SCHED_YIELD""" 4
3625 .el .IP \f(CWSCHED_YIELD\fR 4
3626 .IX Xref "SCHED_YIELD"
3627 .IX Item "SCHED_YIELD"
3628 This symbol defines the way to yield the execution of
3629 the current thread. Known ways are \f(CW\*(C`sched_yield\*(C'\fR,
3630 \&\f(CW\*(C`pthread_yield\*(C'\fR, and \f(CW\*(C`pthread_yield\*(C'\fR with \f(CW\*(C`NULL\*(C'\fR.
3631 .SH "COPs and Hint Hashes"
3632 .IX Xref "COPHH_KEY_UTF8"
3633 .IX Header "COPs and Hint Hashes"
3634 .ie n .IP """cop_fetch_label""" 4
3635 .el .IP \f(CWcop_fetch_label\fR 4
3636 .IX Xref "cop_fetch_label"
3637 .IX Item "cop_fetch_label"
3638 NOTE: \f(CW\*(C`cop_fetch_label\*(C'\fR is \fBexperimental\fR and may change or be
3639 removed without notice.
3640 .Sp
3641 Returns the label attached to a cop, and stores its length in bytes into
3642 \&\f(CW*len\fR.
3643 Upon return, \f(CW*flags\fR will be set to either \f(CW\*(C`SVf_UTF8\*(C'\fR or 0.
3644 .Sp
3645 Alternatively, use the macro \f(CW"CopLABEL_len_flags"\fR;
3646 or if you don\*(Aqt need to know if the label is UTF\-8 or not, the macro
3647 \&\f(CW"CopLABEL_len"\fR;
3648 or if you additionally don\*(Aqt need to know the length, \f(CW"CopLABEL"\fR.
3649 .RS 4
3650 .Sp
3651 .Vb 4
3652 \& const char * cop_fetch_label( COP * const cop,
3653 \& STRLEN *len, U32 *flags)
3654 \& const char * Perl_cop_fetch_label(pTHX_ COP * const cop,
3655 \& STRLEN *len, U32 *flags)
3656 .Ve
3657 .RE
3658 .RS 4
3659 .RE
3660 .ie n .IP """cop_hints_exists_pv""" 4
3661 .el .IP \f(CWcop_hints_exists_pv\fR 4
3662 .IX Item "cop_hints_exists_pv"
3663 .PD 0
3664 .ie n .IP """cop_hints_exists_pvn""" 4
3665 .el .IP \f(CWcop_hints_exists_pvn\fR 4
3666 .IX Item "cop_hints_exists_pvn"
3667 .ie n .IP """cop_hints_exists_pvs""" 4
3668 .el .IP \f(CWcop_hints_exists_pvs\fR 4
3669 .IX Item "cop_hints_exists_pvs"
3670 .ie n .IP """cop_hints_exists_sv""" 4
3671 .el .IP \f(CWcop_hints_exists_sv\fR 4
3672 .IX Xref "cop_hints_exists_pv cop_hints_exists_pvn cop_hints_exists_pvs cop_hints_exists_sv"
3673 .IX Item "cop_hints_exists_sv"
3674 .PD
3675 These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
3676 \&\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,
3677 and false otherwise.
3678 .Sp
3679 The forms differ in how the key is specified. In all forms, the key is pointed
3680 to by \f(CW\*(C`key\*(C'\fR.
3681 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL\-terminated string.
3682 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
3683 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
3684 the string, which hence, may contain embedded\-NUL characters.
3685 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.
3686 using \f(CW"SvPV_const"\fR.
3687 .Sp
3688 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
3689 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
3690 automatically at compile time.
3691 .Sp
3692 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
3693 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
3694 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
3695 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
3696 the octets.
3697 .RS 4
3698 .Sp
3699 .Vb 7
3700 \& bool cop_hints_exists_pv (const COP *cop, const char *key,
3701 \& U32 hash, U32 flags)
3702 \& bool cop_hints_exists_pvn(const COP *cop, const char *key,
3703 \& STRLEN keylen, U32 hash, U32 flags)
3704 \& bool cop_hints_exists_pvs(const COP *cop, "key", U32 flags)
3705 \& bool cop_hints_exists_sv (const COP *cop, SV *key, U32 hash,
3706 \& U32 flags)
3707 .Ve
3708 .RE
3709 .RS 4
3710 .RE
3711 .ie n .IP """cop_hints_fetch_pv""" 4
3712 .el .IP \f(CWcop_hints_fetch_pv\fR 4
3713 .IX Item "cop_hints_fetch_pv"
3714 .PD 0
3715 .ie n .IP """cop_hints_fetch_pvn""" 4
3716 .el .IP \f(CWcop_hints_fetch_pvn\fR 4
3717 .IX Item "cop_hints_fetch_pvn"
3718 .ie n .IP """cop_hints_fetch_pvs""" 4
3719 .el .IP \f(CWcop_hints_fetch_pvs\fR 4
3720 .IX Item "cop_hints_fetch_pvs"
3721 .ie n .IP """cop_hints_fetch_sv""" 4
3722 .el .IP \f(CWcop_hints_fetch_sv\fR 4
3723 .IX Xref "cop_hints_fetch_pv cop_hints_fetch_pvn cop_hints_fetch_pvs cop_hints_fetch_sv"
3724 .IX Item "cop_hints_fetch_sv"
3725 .PD
3726 These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
3727 \&\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
3728 scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the
3729 key.
3730 .Sp
3731 The forms differ in how the key is specified.
3732 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL\-terminated string.
3733 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
3734 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
3735 the string, which hence, may contain embedded\-NUL characters.
3736 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.
3737 using \f(CW"SvPV_const"\fR.
3738 .Sp
3739 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
3740 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
3741 automatically at compile time.
3742 .Sp
3743 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
3744 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
3745 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
3746 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
3747 the octets.
3748 .RS 4
3749 .Sp
3750 .Vb 7
3751 \& SV * cop_hints_fetch_pv (const COP *cop, const char *key,
3752 \& U32 hash, U32 flags)
3753 \& SV * cop_hints_fetch_pvn(const COP *cop, const char *key,
3754 \& STRLEN keylen, U32 hash, U32 flags)
3755 \& SV * cop_hints_fetch_pvs(const COP *cop, "key", U32 flags)
3756 \& SV * cop_hints_fetch_sv (const COP *cop, SV *key, U32 hash,
3757 \& U32 flags)
3758 .Ve
3759 .RE
3760 .RS 4
3761 .RE
3762 .ie n .IP """cop_hints_2hv""" 4
3763 .el .IP \f(CWcop_hints_2hv\fR 4
3764 .IX Xref "cop_hints_2hv"
3765 .IX Item "cop_hints_2hv"
3766 Generates and returns a standard Perl hash representing the full set of
3767 hint entries in the cop \f(CW\*(C`cop\*(C'\fR. \f(CW\*(C`flags\*(C'\fR is currently unused and must
3768 be zero.
3769 .RS 4
3770 .Sp
3771 .Vb 1
3772 \& HV * cop_hints_2hv(const COP *cop, U32 flags)
3773 .Ve
3774 .RE
3775 .RS 4
3776 .RE
3777 .ie n .IP """cop_store_label""" 4
3778 .el .IP \f(CWcop_store_label\fR 4
3779 .IX Xref "cop_store_label"
3780 .IX Item "cop_store_label"
3781 NOTE: \f(CW\*(C`cop_store_label\*(C'\fR is \fBexperimental\fR and may change or be
3782 removed without notice.
3783 .Sp
3784 Save a label into a \f(CW\*(C`cop_hints_hash\*(C'\fR.
3785 You need to set flags to \f(CW\*(C`SVf_UTF8\*(C'\fR
3786 for a UTF\-8 label. Any other flag is ignored.
3787 .RS 4
3788 .Sp
3789 .Vb 6
3790 \& void cop_store_label( COP * const cop,
3791 \& const char *label, STRLEN len,
3792 \& U32 flags)
3793 \& void Perl_cop_store_label(pTHX_ COP * const cop,
3794 \& const char *label, STRLEN len,
3795 \& U32 flags)
3796 .Ve
3797 .RE
3798 .RS 4
3799 .RE
3800 .ie n .IP """CopFILE""" 4
3801 .el .IP \f(CWCopFILE\fR 4
3802 .IX Xref "CopFILE"
3803 .IX Item "CopFILE"
3804 Returns the name of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3805 .RS 4
3806 .Sp
3807 .Vb 1
3808 \& const char * CopFILE(const COP * c)
3809 .Ve
3810 .RE
3811 .RS 4
3812 .RE
3813 .ie n .IP """CopFILE_copy""" 4
3814 .el .IP \f(CWCopFILE_copy\fR 4
3815 .IX Xref "CopFILE_copy"
3816 .IX Item "CopFILE_copy"
3817 Efficiently copies the cop file name from one COP to another. Wraps
3818 the required logic to do a refcounted copy under threads or not.
3819 .RS 4
3820 .Sp
3821 .Vb 1
3822 \& void CopFILE_copy(COP * dst, COP * src)
3823 .Ve
3824 .RE
3825 .RS 4
3826 .RE
3827 .ie n .IP """CopFILE_free""" 4
3828 .el .IP \f(CWCopFILE_free\fR 4
3829 .IX Xref "CopFILE_free"
3830 .IX Item "CopFILE_free"
3831 Frees the file data in a cop. Under the hood this is a refcounting
3832 operation.
3833 .RS 4
3834 .Sp
3835 .Vb 1
3836 \& void CopFILE_free(COP * c)
3837 .Ve
3838 .RE
3839 .RS 4
3840 .RE
3841 .ie n .IP """CopFILE_LEN""" 4
3842 .el .IP \f(CWCopFILE_LEN\fR 4
3843 .IX Xref "CopFILE_LEN"
3844 .IX Item "CopFILE_LEN"
3845 Returns the length of the file associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3846 .RS 4
3847 .Sp
3848 .Vb 1
3849 \& const char * CopFILE_LEN(const COP * c)
3850 .Ve
3851 .RE
3852 .RS 4
3853 .RE
3854 .ie n .IP """CopFILE_set""" 4
3855 .el .IP \f(CWCopFILE_set\fR 4
3856 .IX Item "CopFILE_set"
3857 .PD 0
3858 .ie n .IP """CopFILE_setn""" 4
3859 .el .IP \f(CWCopFILE_setn\fR 4
3860 .IX Xref "CopFILE_set CopFILE_setn"
3861 .IX Item "CopFILE_setn"
3862 .PD
3863 These each make \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.
3864 In the plain \f(CW\*(C`CopFILE_set\*(C'\fR form, \f(CW\*(C`pv\*(C'\fR is a C language NUL\-terminated string.
3865 In \f(CW\*(C`CopFILE_setn\*(C'\fR, \f(CW\*(C`len\*(C'\fR is the length of \f(CW\*(C`pv\*(C'\fR, which hence may contain
3866 embedded NUL characters.
3867 .RS 4
3868 .Sp
3869 .Vb 2
3870 \& void CopFILE_set (COP * c, const char * pv)
3871 \& void CopFILE_setn(COP * c, const char * pv, STRLEN len)
3872 .Ve
3873 .RE
3874 .RS 4
3875 .RE
3876 .ie n .IP """CopFILEAV""" 4
3877 .el .IP \f(CWCopFILEAV\fR 4
3878 .IX Xref "CopFILEAV"
3879 .IX Item "CopFILEAV"
3880 Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, creating it if necessary.
3881 .RS 4
3882 .Sp
3883 .Vb 1
3884 \& AV * CopFILEAV(const COP * c)
3885 .Ve
3886 .RE
3887 .RS 4
3888 .RE
3889 .ie n .IP """CopFILEAVn""" 4
3890 .el .IP \f(CWCopFILEAVn\fR 4
3891 .IX Xref "CopFILEAVn"
3892 .IX Item "CopFILEAVn"
3893 Returns the AV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR, returning NULL if it
3894 doesn\*(Aqt already exist.
3895 .RS 4
3896 .Sp
3897 .Vb 1
3898 \& AV * CopFILEAVn(const COP * c)
3899 .Ve
3900 .RE
3901 .RS 4
3902 .RE
3903 .ie n .IP """CopFILEGV""" 4
3904 .el .IP \f(CWCopFILEGV\fR 4
3905 .IX Xref "CopFILEGV"
3906 .IX Item "CopFILEGV"
3907 Returns the GV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3908 .RS 4
3909 .Sp
3910 .Vb 1
3911 \& GV * CopFILEGV(const COP * c)
3912 .Ve
3913 .RE
3914 .RS 4
3915 .RE
3916 .ie n .IP """CopFILEGV_set""" 4
3917 .el .IP \f(CWCopFILEGV_set\fR 4
3918 .IX Xref "CopFILEGV_set"
3919 .IX Item "CopFILEGV_set"
3920 Available only on unthreaded perls. Makes \f(CW\*(C`pv\*(C'\fR the name of the file
3921 associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3922 .RS 4
3923 .Sp
3924 .Vb 1
3925 \& void CopFILEGV_set(COP *c, GV *gv)
3926 .Ve
3927 .RE
3928 .RS 4
3929 .RE
3930 .ie n .IP """CopFILESV""" 4
3931 .el .IP \f(CWCopFILESV\fR 4
3932 .IX Xref "CopFILESV"
3933 .IX Item "CopFILESV"
3934 Returns the SV associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
3935 .RS 4
3936 .Sp
3937 .Vb 1
3938 \& SV * CopFILESV(const COP * c)
3939 .Ve
3940 .RE
3941 .RS 4
3942 .RE
3943 .ie n .IP """cophh_copy""" 4
3944 .el .IP \f(CWcophh_copy\fR 4
3945 .IX Xref "cophh_copy"
3946 .IX Item "cophh_copy"
3947 NOTE: \f(CW\*(C`cophh_copy\*(C'\fR is \fBexperimental\fR and may change or be
3948 removed without notice.
3949 .Sp
3950 Make and return a complete copy of the cop hints hash \f(CW\*(C`cophh\*(C'\fR.
3951 .RS 4
3952 .Sp
3953 .Vb 1
3954 \& COPHH * cophh_copy(COPHH *cophh)
3955 .Ve
3956 .RE
3957 .RS 4
3958 .RE
3959 .ie n .IP """cophh_delete_pv""" 4
3960 .el .IP \f(CWcophh_delete_pv\fR 4
3961 .IX Item "cophh_delete_pv"
3962 .PD 0
3963 .ie n .IP """cophh_delete_pvn""" 4
3964 .el .IP \f(CWcophh_delete_pvn\fR 4
3965 .IX Item "cophh_delete_pvn"
3966 .ie n .IP """cophh_delete_pvs""" 4
3967 .el .IP \f(CWcophh_delete_pvs\fR 4
3968 .IX Item "cophh_delete_pvs"
3969 .ie n .IP """cophh_delete_sv""" 4
3970 .el .IP \f(CWcophh_delete_sv\fR 4
3971 .IX Xref "cophh_delete_pv cophh_delete_pvn cophh_delete_pvs cophh_delete_sv"
3972 .IX Item "cophh_delete_sv"
3973 .PD
3974 NOTE: all these forms are \fBexperimental\fR and may change or be
3975 removed without notice.
3976 .Sp
3977 These delete a key and its associated value from the cop hints hash \f(CW\*(C`cophh\*(C'\fR,
3978 and return the modified hash. The returned hash pointer is in general
3979 not the same as the hash pointer that was passed in. The input hash is
3980 consumed by the function, and the pointer to it must not be subsequently
3981 used. Use "cophh_copy" if you need both hashes.
3982 .Sp
3983 The forms differ in how the key is specified. In all forms, the key is pointed
3984 to by \f(CW\*(C`key\*(C'\fR.
3985 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL\-terminated string.
3986 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
3987 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
3988 the string, which hence, may contain embedded\-NUL characters.
3989 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.
3990 using \f(CW"SvPV_const"\fR.
3991 .Sp
3992 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
3993 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
3994 automatically at compile time.
3995 .Sp
3996 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
3997 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
3998 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
3999 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4000 the octets.
4001 .RS 4
4002 .Sp
4003 .Vb 7
4004 \& COPHH * cophh_delete_pv (COPHH *cophh, const char *key,
4005 \& U32 hash, U32 flags)
4006 \& COPHH * cophh_delete_pvn(COPHH *cophh, const char *key,
4007 \& STRLEN keylen, U32 hash, U32 flags)
4008 \& COPHH * cophh_delete_pvs(COPHH *cophh, "key", U32 flags)
4009 \& COPHH * cophh_delete_sv (COPHH *cophh, SV *key, U32 hash,
4010 \& U32 flags)
4011 .Ve
4012 .RE
4013 .RS 4
4014 .RE
4015 .ie n .IP """cophh_exists_pvn""" 4
4016 .el .IP \f(CWcophh_exists_pvn\fR 4
4017 .IX Xref "cophh_exists_pvn"
4018 .IX Item "cophh_exists_pvn"
4019 NOTE: \f(CW\*(C`cophh_exists_pvn\*(C'\fR is \fBexperimental\fR and may change or be
4020 removed without notice.
4021 .Sp
4022 These look up the hint entry in the cop \f(CW\*(C`cop\*(C'\fR with the key specified by
4023 \&\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,
4024 and false otherwise.
4025 .Sp
4026 The forms differ in how the key is specified.
4027 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL\-terminated string.
4028 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4029 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4030 the string, which hence, may contain embedded\-NUL characters.
4031 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.
4032 using \f(CW"SvPV_const"\fR.
4033 .Sp
4034 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4035 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4036 automatically at compile time.
4037 .Sp
4038 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4039 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
4040 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4041 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4042 the octets.
4043 .RS 4
4044 .Sp
4045 .Vb 2
4046 \& bool cophh_exists_pvn(const COPHH *cophh, const char *key,
4047 \& STRLEN keylen, U32 hash, U32 flags)
4048 .Ve
4049 .RE
4050 .RS 4
4051 .RE
4052 .ie n .IP """cophh_fetch_pv""" 4
4053 .el .IP \f(CWcophh_fetch_pv\fR 4
4054 .IX Item "cophh_fetch_pv"
4055 .PD 0
4056 .ie n .IP """cophh_fetch_pvn""" 4
4057 .el .IP \f(CWcophh_fetch_pvn\fR 4
4058 .IX Item "cophh_fetch_pvn"
4059 .ie n .IP """cophh_fetch_pvs""" 4
4060 .el .IP \f(CWcophh_fetch_pvs\fR 4
4061 .IX Item "cophh_fetch_pvs"
4062 .ie n .IP """cophh_fetch_sv""" 4
4063 .el .IP \f(CWcophh_fetch_sv\fR 4
4064 .IX Xref "cophh_fetch_pv cophh_fetch_pvn cophh_fetch_pvs cophh_fetch_sv"
4065 .IX Item "cophh_fetch_sv"
4066 .PD
4067 NOTE: all these forms are \fBexperimental\fR and may change or be
4068 removed without notice.
4069 .Sp
4070 These look up the entry in the cop hints hash \f(CW\*(C`cophh\*(C'\fR with the key specified by
4071 \&\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
4072 scalar copy, or \f(CW&PL_sv_placeholder\fR if there is no value associated with the
4073 key.
4074 .Sp
4075 The forms differ in how the key is specified.
4076 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL\-terminated string.
4077 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4078 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4079 the string, which hence, may contain embedded\-NUL characters.
4080 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.
4081 using \f(CW"SvPV_const"\fR.
4082 .Sp
4083 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4084 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4085 automatically at compile time.
4086 .Sp
4087 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4088 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
4089 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4090 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4091 the octets.
4092 .RS 4
4093 .Sp
4094 .Vb 7
4095 \& SV * cophh_fetch_pv (const COPHH *cophh, const char *key,
4096 \& U32 hash, U32 flags)
4097 \& SV * cophh_fetch_pvn(const COPHH *cophh, const char *key,
4098 \& STRLEN keylen, U32 hash, U32 flags)
4099 \& SV * cophh_fetch_pvs(const COPHH *cophh, "key", U32 flags)
4100 \& SV * cophh_fetch_sv (const COPHH *cophh, SV *key, U32 hash,
4101 \& U32 flags)
4102 .Ve
4103 .RE
4104 .RS 4
4105 .RE
4106 .ie n .IP """cophh_free""" 4
4107 .el .IP \f(CWcophh_free\fR 4
4108 .IX Xref "cophh_free"
4109 .IX Item "cophh_free"
4110 NOTE: \f(CW\*(C`cophh_free\*(C'\fR is \fBexperimental\fR and may change or be
4111 removed without notice.
4112 .Sp
4113 Discard the cop hints hash \f(CW\*(C`cophh\*(C'\fR, freeing all resources associated
4114 with it.
4115 .RS 4
4116 .Sp
4117 .Vb 1
4118 \& void cophh_free(COPHH *cophh)
4119 .Ve
4120 .RE
4121 .RS 4
4122 .RE
4123 .ie n .IP """cophh_new_empty""" 4
4124 .el .IP \f(CWcophh_new_empty\fR 4
4125 .IX Xref "cophh_new_empty"
4126 .IX Item "cophh_new_empty"
4127 NOTE: \f(CW\*(C`cophh_new_empty\*(C'\fR is \fBexperimental\fR and may change or be
4128 removed without notice.
4129 .Sp
4130 Generate and return a fresh cop hints hash containing no entries.
4131 .RS 4
4132 .Sp
4133 .Vb 1
4134 \& COPHH * cophh_new_empty()
4135 .Ve
4136 .RE
4137 .RS 4
4138 .RE
4139 .ie n .IP """cophh_store_pv""" 4
4140 .el .IP \f(CWcophh_store_pv\fR 4
4141 .IX Item "cophh_store_pv"
4142 .PD 0
4143 .ie n .IP """cophh_store_pvn""" 4
4144 .el .IP \f(CWcophh_store_pvn\fR 4
4145 .IX Item "cophh_store_pvn"
4146 .ie n .IP """cophh_store_pvs""" 4
4147 .el .IP \f(CWcophh_store_pvs\fR 4
4148 .IX Item "cophh_store_pvs"
4149 .ie n .IP """cophh_store_sv""" 4
4150 .el .IP \f(CWcophh_store_sv\fR 4
4151 .IX Xref "cophh_store_pv cophh_store_pvn cophh_store_pvs cophh_store_sv"
4152 .IX Item "cophh_store_sv"
4153 .PD
4154 NOTE: all these forms are \fBexperimental\fR and may change or be
4155 removed without notice.
4156 .Sp
4157 These store a value, associated with a key, in the cop hints hash \f(CW\*(C`cophh\*(C'\fR,
4158 and return the modified hash. The returned hash pointer is in general
4159 not the same as the hash pointer that was passed in. The input hash is
4160 consumed by the function, and the pointer to it must not be subsequently
4161 used. Use "cophh_copy" if you need both hashes.
4162 .Sp
4163 \&\f(CW\*(C`value\*(C'\fR is the scalar value to store for this key. \f(CW\*(C`value\*(C'\fR is copied
4164 by these functions, which thus do not take ownership of any reference
4165 to it, and hence later changes to the scalar will not be reflected in the value
4166 visible in the cop hints hash. Complex types of scalar will not be stored with
4167 referential integrity, but will be coerced to strings.
4168 .Sp
4169 The forms differ in how the key is specified. In all forms, the key is pointed
4170 to by \f(CW\*(C`key\*(C'\fR.
4171 In the plain \f(CW\*(C`pv\*(C'\fR form, the key is a C language NUL\-terminated string.
4172 In the \f(CW\*(C`pvs\*(C'\fR form, the key is a C language string literal.
4173 In the \f(CW\*(C`pvn\*(C'\fR form, an additional parameter, \f(CW\*(C`keylen\*(C'\fR, specifies the length of
4174 the string, which hence, may contain embedded\-NUL characters.
4175 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.
4176 using \f(CW"SvPV_const"\fR.
4177 .Sp
4178 \&\f(CW\*(C`hash\*(C'\fR is a precomputed hash of the key string, or zero if it has not been
4179 precomputed. This parameter is omitted from the \f(CW\*(C`pvs\*(C'\fR form, as it is computed
4180 automatically at compile time.
4181 .Sp
4182 The only flag currently used from the \f(CW\*(C`flags\*(C'\fR parameter is \f(CW\*(C`COPHH_KEY_UTF8\*(C'\fR.
4183 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
4184 whether the key octets are interpreted as UTF\-8 (if set) or as Latin\-1 (if
4185 cleared). The \f(CW\*(C`sv\*(C'\fR form uses the underlying SV to determine the UTF\-8ness of
4186 the octets.
4187 .RS 4
4188 .Sp
4189 .Vb 9
4190 \& COPHH * cophh_store_pv (COPHH *cophh, const char *key, U32 hash,
4191 \& SV *value, U32 flags)
4192 \& COPHH * cophh_store_pvn(COPHH *cophh, const char *key,
4193 \& STRLEN keylen, U32 hash, SV *value,
4194 \& U32 flags)
4195 \& COPHH * cophh_store_pvs(COPHH *cophh, "key", SV *value,
4196 \& U32 flags)
4197 \& COPHH * cophh_store_sv (COPHH *cophh, SV *key, U32 hash,
4198 \& SV *value, U32 flags)
4199 .Ve
4200 .RE
4201 .RS 4
4202 .RE
4203 .ie n .IP """cophh_2hv""" 4
4204 .el .IP \f(CWcophh_2hv\fR 4
4205 .IX Xref "cophh_2hv"
4206 .IX Item "cophh_2hv"
4207 NOTE: \f(CW\*(C`cophh_2hv\*(C'\fR is \fBexperimental\fR and may change or be
4208 removed without notice.
4209 .Sp
4210 Generates and returns a standard Perl hash representing the full set of
4211 key/value pairs in the cop hints hash \f(CW\*(C`cophh\*(C'\fR. \f(CW\*(C`flags\*(C'\fR is currently
4212 unused and must be zero.
4213 .RS 4
4214 .Sp
4215 .Vb 1
4216 \& HV * cophh_2hv(const COPHH *cophh, U32 flags)
4217 .Ve
4218 .RE
4219 .RS 4
4220 .RE
4221 .ie n .IP """CopLABEL""" 4
4222 .el .IP \f(CWCopLABEL\fR 4
4223 .IX Item "CopLABEL"
4224 .PD 0
4225 .ie n .IP """CopLABEL_len""" 4
4226 .el .IP \f(CWCopLABEL_len\fR 4
4227 .IX Item "CopLABEL_len"
4228 .ie n .IP """CopLABEL_len_flags""" 4
4229 .el .IP \f(CWCopLABEL_len_flags\fR 4
4230 .IX Xref "CopLABEL CopLABEL_len CopLABEL_len_flags"
4231 .IX Item "CopLABEL_len_flags"
4232 .PD
4233 These return the label attached to a cop.
4234 .Sp
4235 \&\f(CW\*(C`CopLABEL_len\*(C'\fR and \f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally store the number of
4236 bytes comprising the returned label into \f(CW*len\fR.
4237 .Sp
4238 \&\f(CW\*(C`CopLABEL_len_flags\*(C'\fR additionally returns the UTF\-8ness of the returned label,
4239 by setting \f(CW*flags\fR to 0 or \f(CW\*(C`SVf_UTF8\*(C'\fR.
4240 .RS 4
4241 .Sp
4242 .Vb 4
4243 \& const char * CopLABEL (COP *const cop)
4244 \& const char * CopLABEL_len (COP *const cop, STRLEN *len)
4245 \& const char * CopLABEL_len_flags(COP *const cop, STRLEN *len,
4246 \& U32 *flags)
4247 .Ve
4248 .RE
4249 .RS 4
4250 .RE
4251 .ie n .IP """CopLINE""" 4
4252 .el .IP \f(CWCopLINE\fR 4
4253 .IX Xref "CopLINE"
4254 .IX Item "CopLINE"
4255 Returns the line number in the source code associated with the \f(CW\*(C`COP\*(C'\fR \f(CW\*(C`c\*(C'\fR
4256 .RS 4
4257 .Sp
4258 .Vb 1
4259 \& line_t CopLINE(const COP * c)
4260 .Ve
4261 .RE
4262 .RS 4
4263 .RE
4264 .ie n .IP """CopSTASH""" 4
4265 .el .IP \f(CWCopSTASH\fR 4
4266 .IX Xref "CopSTASH"
4267 .IX Item "CopSTASH"
4268 Returns the stash associated with \f(CW\*(C`c\*(C'\fR.
4269 .RS 4
4270 .Sp
4271 .Vb 1
4272 \& HV * CopSTASH(const COP * c)
4273 .Ve
4274 .RE
4275 .RS 4
4276 .RE
4277 .ie n .IP """CopSTASH_eq""" 4
4278 .el .IP \f(CWCopSTASH_eq\fR 4
4279 .IX Xref "CopSTASH_eq"
4280 .IX Item "CopSTASH_eq"
4281 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.
4282 .RS 4
4283 .Sp
4284 .Vb 1
4285 \& bool CopSTASH_eq(const COP * c, const HV * hv)
4286 .Ve
4287 .RE
4288 .RS 4
4289 .RE
4290 .ie n .IP """CopSTASH_set""" 4
4291 .el .IP \f(CWCopSTASH_set\fR 4
4292 .IX Xref "CopSTASH_set"
4293 .IX Item "CopSTASH_set"
4294 Set the stash associated with \f(CW\*(C`c\*(C'\fR to \f(CW\*(C`hv\*(C'\fR.
4295 .RS 4
4296 .Sp
4297 .Vb 1
4298 \& bool CopSTASH_set(COP * c, HV * hv)
4299 .Ve
4300 .RE
4301 .RS 4
4302 .RE
4303 .ie n .IP """CopSTASHPV""" 4
4304 .el .IP \f(CWCopSTASHPV\fR 4
4305 .IX Xref "CopSTASHPV"
4306 .IX Item "CopSTASHPV"
4307 Returns the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if no
4308 associated stash
4309 .RS 4
4310 .Sp
4311 .Vb 1
4312 \& char * CopSTASHPV(const COP * c)
4313 .Ve
4314 .RE
4315 .RS 4
4316 .RE
4317 .ie n .IP """CopSTASHPV_set""" 4
4318 .el .IP \f(CWCopSTASHPV_set\fR 4
4319 .IX Xref "CopSTASHPV_set"
4320 .IX Item "CopSTASHPV_set"
4321 Set the package name of the stash associated with \f(CW\*(C`c\*(C'\fR, to the NUL\-terminated C
4322 string \f(CW\*(C`p\*(C'\fR, creating the package if necessary.
4323 .RS 4
4324 .Sp
4325 .Vb 1
4326 \& void CopSTASHPV_set(COP * c, const char * pv)
4327 .Ve
4328 .RE
4329 .RS 4
4330 .RE
4331 .ie n .IP """PERL_SI""" 4
4332 .el .IP \f(CWPERL_SI\fR 4
4333 .IX Xref "PERL_SI"
4334 .IX Item "PERL_SI"
4335 Use this typedef to declare variables that are to hold \f(CW\*(C`struct stackinfo\*(C'\fR.
4336 .ie n .IP """PL_curcop""" 4
4337 .el .IP \f(CWPL_curcop\fR 4
4338 .IX Xref "PL_curcop"
4339 .IX Item "PL_curcop"
4340 The currently active COP (control op) roughly representing the current
4341 statement in the source.
4342 .Sp
4343 On threaded perls, each thread has an independent copy of this variable;
4344 each initialized at creation time with the current value of the creating
4345 thread\*(Aqs copy.
4346 .RS 4
4347 .Sp
4348 .Vb 1
4349 \& COP* PL_curcop
4350 .Ve
4351 .RE
4352 .RS 4
4353 .RE
4354 .ie n .IP """RCPV_LEN""" 4
4355 .el .IP \f(CWRCPV_LEN\fR 4
4356 .IX Xref "RCPV_LEN"
4357 .IX Item "RCPV_LEN"
4358 Returns the length of a pv created with \f(CWrcpv_new()\fR.
4359 Note that this reflects the length of the string from the callers
4360 point of view, it does not include the mandatory null which is
4361 always injected at the end of the string by \fBrcpv_new()\fR.
4362 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4363 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4364 this is the case.
4365 .RS 4
4366 .Sp
4367 .Vb 1
4368 \& RCPV * RCPV_LEN(char *pv)
4369 .Ve
4370 .RE
4371 .RS 4
4372 .RE
4373 .ie n .IP """RCPV_REFCNT_dec""" 4
4374 .el .IP \f(CWRCPV_REFCNT_dec\fR 4
4375 .IX Xref "RCPV_REFCNT_dec"
4376 .IX Item "RCPV_REFCNT_dec"
4377 Decrements the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created
4378 with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_free()\fR.
4379 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4380 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4381 this is the case.
4382 .RS 4
4383 .Sp
4384 .Vb 1
4385 \& RCPV * RCPV_REFCNT_dec(char *pv)
4386 .Ve
4387 .RE
4388 .RS 4
4389 .RE
4390 .ie n .IP """RCPV_REFCNT_inc""" 4
4391 .el .IP \f(CWRCPV_REFCNT_inc\fR 4
4392 .IX Xref "RCPV_REFCNT_inc"
4393 .IX Item "RCPV_REFCNT_inc"
4394 Increments the refcount for a \f(CW\*(C`char *\*(C'\fR pointer which was created
4395 with a call to \f(CWrcpv_new()\fR. Same as calling \fBrcpv_copy()\fR.
4396 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4397 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4398 this is the case.
4399 .RS 4
4400 .Sp
4401 .Vb 1
4402 \& RCPV * RCPV_REFCNT_inc(char *pv)
4403 .Ve
4404 .RE
4405 .RS 4
4406 .RE
4407 .ie n .IP """RCPV_REFCOUNT""" 4
4408 .el .IP \f(CWRCPV_REFCOUNT\fR 4
4409 .IX Xref "RCPV_REFCOUNT"
4410 .IX Item "RCPV_REFCOUNT"
4411 Returns the refcount for a pv created with \f(CWrcpv_new()\fR.
4412 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4413 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4414 this is the case.
4415 .RS 4
4416 .Sp
4417 .Vb 1
4418 \& RCPV * RCPV_REFCOUNT(char *pv)
4419 .Ve
4420 .RE
4421 .RS 4
4422 .RE
4423 .ie n .IP """RCPVx""" 4
4424 .el .IP \f(CWRCPVx\fR 4
4425 .IX Xref "RCPVx"
4426 .IX Item "RCPVx"
4427 Returns the RCPV structure (struct rcpv) for a refcounted
4428 string pv created with \f(CWrcpv_new()\fR.
4429 No checks are performed to ensure that \f(CW\*(C`pv\*(C'\fR was actually allocated
4430 with \f(CWrcpv_new()\fR, it is the callers responsibility to ensure that
4431 this is the case.
4432 .RS 4
4433 .Sp
4434 .Vb 1
4435 \& RCPV * RCPVx(char *pv)
4436 .Ve
4437 .RE
4438 .RS 4
4439 .RE
4440 .SH "Custom Operators"
4441 .IX Header "Custom Operators"
4442 .ie n .IP """custom_op_register""" 4
4443 .el .IP \f(CWcustom_op_register\fR 4
4444 .IX Xref "custom_op_register"
4445 .IX Item "custom_op_register"
4446 Register a custom op. See "Custom Operators" in perlguts.
4447 .RS 4
4448 .Sp
4449 .Vb 2
4450 \& void Perl_custom_op_register(pTHX_ Perl_ppaddr_t ppaddr,
4451 \& const XOP *xop)
4452 .Ve
4453 .RE
4454 .RS 4
4455 .RE
4456 .ie n .IP """Perl_custom_op_xop""" 4
4457 .el .IP \f(CWPerl_custom_op_xop\fR 4
4458 .IX Xref "Perl_custom_op_xop"
4459 .IX Item "Perl_custom_op_xop"
4460 Return the XOP structure for a given custom op. This macro should be
4461 considered internal to \f(CW\*(C`OP_NAME\*(C'\fR and the other access macros: use them instead.
4462 This macro does call a function. Prior
4463 to 5.19.6, this was implemented as a
4464 function.
4465 .RS 4
4466 .Sp
4467 .Vb 1
4468 \& const XOP * Perl_custom_op_xop(const OP *o)
4469 .Ve
4470 .RE
4471 .RS 4
4472 .RE
4473 .ie n .IP """XopDISABLE""" 4
4474 .el .IP \f(CWXopDISABLE\fR 4
4475 .IX Xref "XopDISABLE"
4476 .IX Item "XopDISABLE"
4477 Temporarily disable a member of the XOP, by clearing the appropriate flag.
4478 .RS 4
4479 .Sp
4480 .Vb 1
4481 \& void XopDISABLE(XOP *xop, token which)
4482 .Ve
4483 .RE
4484 .RS 4
4485 .RE
4486 .ie n .IP """XopENABLE""" 4
4487 .el .IP \f(CWXopENABLE\fR 4
4488 .IX Xref "XopENABLE"
4489 .IX Item "XopENABLE"
4490 Reenable a member of the XOP which has been disabled.
4491 .RS 4
4492 .Sp
4493 .Vb 1
4494 \& void XopENABLE(XOP *xop, token which)
4495 .Ve
4496 .RE
4497 .RS 4
4498 .RE
4499 .ie n .IP """XopENTRY""" 4
4500 .el .IP \f(CWXopENTRY\fR 4
4501 .IX Xref "XopENTRY"
4502 .IX Item "XopENTRY"
4503 Return a member of the XOP structure. \f(CW\*(C`which\*(C'\fR is a cpp token
4504 indicating which entry to return. If the member is not set
4505 this will return a default value. The return type depends
4506 on \f(CW\*(C`which\*(C'\fR. This macro evaluates its arguments more than
4507 once. If you are using \f(CW\*(C`Perl_custom_op_xop\*(C'\fR to retrieve a
4508 \&\f(CW\*(C`XOP *\*(C'\fR from a \f(CW\*(C`OP *\*(C'\fR, use the more efficient "XopENTRYCUSTOM" instead.
4509 .RS 4
4510 .Sp
4511 .Vb 1
4512 \& XopENTRY(XOP *xop, token which)
4513 .Ve
4514 .RE
4515 .RS 4
4516 .RE
4517 .ie n .IP """XopENTRY_set""" 4
4518 .el .IP \f(CWXopENTRY_set\fR 4
4519 .IX Xref "XopENTRY_set"
4520 .IX Item "XopENTRY_set"
4521 Set a member of the XOP structure. \f(CW\*(C`which\*(C'\fR is a cpp token
4522 indicating which entry to set. See "Custom Operators" in perlguts
4523 for details about the available members and how
4524 they are used. This macro evaluates its argument
4525 more than once.
4526 .RS 4
4527 .Sp
4528 .Vb 1
4529 \& void XopENTRY_set(XOP *xop, token which, value)
4530 .Ve
4531 .RE
4532 .RS 4
4533 .RE
4534 .ie n .IP """XopENTRYCUSTOM""" 4
4535 .el .IP \f(CWXopENTRYCUSTOM\fR 4
4536 .IX Xref "XopENTRYCUSTOM"
4537 .IX Item "XopENTRYCUSTOM"
4538 Exactly like \f(CW\*(C`XopENTRY(XopENTRY(Perl_custom_op_xop(aTHX_ o), which)\*(C'\fR but more
4539 efficient. The \f(CW\*(C`which\*(C'\fR parameter is identical to "XopENTRY".
4540 .RS 4
4541 .Sp
4542 .Vb 1
4543 \& XopENTRYCUSTOM(const OP *o, token which)
4544 .Ve
4545 .RE
4546 .RS 4
4547 .RE
4548 .ie n .IP """XopFLAGS""" 4
4549 .el .IP \f(CWXopFLAGS\fR 4
4550 .IX Xref "XopFLAGS"
4551 .IX Item "XopFLAGS"
4552 Return the XOP\*(Aqs flags.
4553 .RS 4
4554 .Sp
4555 .Vb 1
4556 \& U32 XopFLAGS(XOP *xop)
4557 .Ve
4558 .RE
4559 .RS 4
4560 .RE
4561 .SH "CV Handling"
4562 .IX Xref "CV GV_ADD"
4563 .IX Header "CV Handling"
4564 This section documents functions to manipulate CVs which are
4565 code\-values, meaning subroutines. For more information, see
4566 perlguts.
4567 .ie n .IP """caller_cx""" 4
4568 .el .IP \f(CWcaller_cx\fR 4
4569 .IX Xref "caller_cx"
4570 .IX Item "caller_cx"
4571 The XSUB\-writer\*(Aqs equivalent of \fBcaller()\fR. The
4572 returned \f(CW\*(C`PERL_CONTEXT\*(C'\fR structure can be interrogated to find all the
4573 information returned to Perl by \f(CW\*(C`caller\*(C'\fR. Note that XSUBs don\*(Aqt get a
4574 stack frame, so \f(CW\*(C`caller_cx(0, NULL)\*(C'\fR will return information for the
4575 immediately\-surrounding Perl code.
4576 .Sp
4577 This function skips over the automatic calls to \f(CW&DB::sub\fR made on the
4578 behalf of the debugger. If the stack frame requested was a sub called by
4579 \&\f(CW\*(C`DB::sub\*(C'\fR, the return value will be the frame for the call to
4580 \&\f(CW\*(C`DB::sub\*(C'\fR, since that has the correct line number/etc. for the call
4581 site. If \fIdbcxp\fR is non\-\f(CW\*(C`NULL\*(C'\fR, it will be set to a pointer to the
4582 frame for the sub call itself.
4583 .RS 4
4584 .Sp
4585 .Vb 4
4586 \& const PERL_CONTEXT * caller_cx(I32 level,
4587 \& const PERL_CONTEXT **dbcxp)
4588 \& const PERL_CONTEXT * Perl_caller_cx(pTHX_ I32 level,
4589 \& const PERL_CONTEXT **dbcxp)
4590 .Ve
4591 .RE
4592 .RS 4
4593 .RE
4594 .ie n .IP """CvDEPTH""" 4
4595 .el .IP \f(CWCvDEPTH\fR 4
4596 .IX Xref "CvDEPTH"
4597 .IX Item "CvDEPTH"
4598 Returns the recursion level of the CV \f(CW\*(C`sv\*(C'\fR. Hence >= 2 indicates we are in a
4599 recursive call.
4600 .RS 4
4601 .Sp
4602 .Vb 2
4603 \& I32 * CvDEPTH(const CV * const sv)
4604 \& I32 * Perl_CvDEPTH(const CV * const sv)
4605 .Ve
4606 .RE
4607 .RS 4
4608 .RE
4609 .ie n .IP """CvGV""" 4
4610 .el .IP \f(CWCvGV\fR 4
4611 .IX Xref "CvGV"
4612 .IX Item "CvGV"
4613 Returns the GV associated with the CV \f(CW\*(C`sv\*(C'\fR, reifying it if necessary.
4614 .RS 4
4615 .Sp
4616 .Vb 2
4617 \& GV * CvGV( CV *sv)
4618 \& GV * Perl_CvGV(pTHX_ CV *sv)
4619 .Ve
4620 .RE
4621 .RS 4
4622 .RE
4623 .ie n .IP """CvREFCNT_inc""" 4
4624 .el .IP \f(CWCvREFCNT_inc\fR 4
4625 .IX Item "CvREFCNT_inc"
4626 .PD 0
4627 .ie n .IP """CvREFCNT_inc_simple""" 4
4628 .el .IP \f(CWCvREFCNT_inc_simple\fR 4
4629 .IX Item "CvREFCNT_inc_simple"
4630 .ie n .IP """CvREFCNT_inc_simple_NN""" 4
4631 .el .IP \f(CWCvREFCNT_inc_simple_NN\fR 4
4632 .IX Xref "CvREFCNT_inc CvREFCNT_inc_simple CvREFCNT_inc_simple_NN"
4633 .IX Item "CvREFCNT_inc_simple_NN"
4634 .PD
4635 These all increment the reference count of the given SV, which must be a CV.
4636 They are useful when assigning the result into a typed pointer as they avoid
4637 the need to cast the result to the appropriate type.
4638 .RS 4
4639 .Sp
4640 .Vb 3
4641 \& CV * CvREFCNT_inc (CV *cv)
4642 \& CV * CvREFCNT_inc_simple (CV *cv)
4643 \& CV * CvREFCNT_inc_simple_NN(CV *cv)
4644 .Ve
4645 .RE
4646 .RS 4
4647 .RE
4648 .ie n .IP """CvSTASH""" 4
4649 .el .IP \f(CWCvSTASH\fR 4
4650 .IX Xref "CvSTASH"
4651 .IX Item "CvSTASH"
4652 Returns the stash of the CV. A stash is the symbol table hash, containing
4653 the package\-scoped variables in the package where the subroutine was defined.
4654 For more information, see perlguts.
4655 .Sp
4656 This also has a special use with XS AUTOLOAD subs.
4657 See "Autoloading with XSUBs" in perlguts.
4658 .RS 4
4659 .Sp
4660 .Vb 1
4661 \& HV* CvSTASH(CV* cv)
4662 .Ve
4663 .RE
4664 .RS 4
4665 .RE
4666 .ie n .IP """find_runcv""" 4
4667 .el .IP \f(CWfind_runcv\fR 4
4668 .IX Xref "find_runcv"
4669 .IX Item "find_runcv"
4670 Locate the CV corresponding to the currently executing sub or eval.
4671 If \f(CW\*(C`db_seqp\*(C'\fR is non_null, skip CVs that are in the DB package and populate
4672 \&\f(CW*db_seqp\fR with the cop sequence number at the point that the DB:: code was
4673 entered. (This allows debuggers to eval in the scope of the breakpoint
4674 rather than in the scope of the debugger itself.)
4675 .RS 4
4676 .Sp
4677 .Vb 2
4678 \& CV * find_runcv( U32 *db_seqp)
4679 \& CV * Perl_find_runcv(pTHX_ U32 *db_seqp)
4680 .Ve
4681 .RE
4682 .RS 4
4683 .RE
4684 .ie n .IP """get_cv""" 4
4685 .el .IP \f(CWget_cv\fR 4
4686 .IX Item "get_cv"
4687 .PD 0
4688 .ie n .IP """get_cvn_flags""" 4
4689 .el .IP \f(CWget_cvn_flags\fR 4
4690 .IX Item "get_cvn_flags"
4691 .ie n .IP """get_cvs""" 4
4692 .el .IP \f(CWget_cvs\fR 4
4693 .IX Xref "get_cv get_cvn_flags get_cvs"
4694 .IX Item "get_cvs"
4695 .PD
4696 These return the CV of the specified Perl subroutine. \f(CW\*(C`flags\*(C'\fR are passed to
4697 \&\f(CW\*(C`gv_fetchpvn_flags\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the Perl subroutine does not
4698 exist then it will be declared (which has the same effect as saying
4699 \&\f(CW\*(C`sub name;\*(C'\fR). If \f(CW\*(C`GV_ADD\*(C'\fR is not set and the subroutine does not exist,
4700 then NULL is returned.
4701 .Sp
4702 The forms differ only in how the subroutine is specified.. With \f(CW\*(C`get_cvs\*(C'\fR,
4703 the name is a literal C string, enclosed in double quotes. With \f(CW\*(C`get_cv\*(C'\fR, the
4704 name is given by the \f(CW\*(C`name\*(C'\fR parameter, which must be a NUL\-terminated C
4705 string. With \f(CW\*(C`get_cvn_flags\*(C'\fR, the name is also given by the \f(CW\*(C`name\*(C'\fR
4706 parameter, but it is a Perl string (possibly containing embedded NUL bytes),
4707 and its length in bytes is contained in the \f(CW\*(C`len\*(C'\fR parameter.
4708 .Sp
4709 NOTE: the \f(CWperl_get_cv()\fR form is \fBdeprecated\fR.
4710 .RS 4
4711 .Sp
4712 .Vb 7
4713 \& CV * get_cv ( const char *name, I32 flags)
4714 \& CV * Perl_get_cv (pTHX_ const char *name, I32 flags)
4715 \& CV * get_cvn_flags( const char *name, STRLEN len,
4716 \& I32 flags)
4717 \& CV * Perl_get_cvn_flags(pTHX_ const char *name, STRLEN len,
4718 \& I32 flags)
4719 \& CV * get_cvs ( "name", I32 flags)
4720 .Ve
4721 .RE
4722 .RS 4
4723 .RE
4724 .ie n .IP """Nullcv""" 4
4725 .el .IP \f(CWNullcv\fR 4
4726 .IX Xref "Nullcv"
4727 .IX Item "Nullcv"
4728 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullcv\*(C'\fR
4729 from a future release of Perl. Do not use it for
4730 new code; remove it from existing code.
4731 .Sp
4732 Null CV pointer.
4733 .Sp
4734 (deprecated \- use \f(CW\*(C`(CV *)NULL\*(C'\fR instead)
4735 .SH Debugging
4736 .IX Header "Debugging"
4737 .ie n .IP """av_dump""" 4
4738 .el .IP \f(CWav_dump\fR 4
4739 .IX Xref "av_dump"
4740 .IX Item "av_dump"
4741 Dumps the contents of an AV to the \f(CW\*(C`STDERR\*(C'\fR filehandle,
4742 Similar to using Devel::Peek on an arrayref but does not
4743 expect an RV wrapper. Dumps contents to a depth of 3 levels
4744 deep.
4745 .RS 4
4746 .Sp
4747 .Vb 2
4748 \& void av_dump( AV *av)
4749 \& void Perl_av_dump(pTHX_ AV *av)
4750 .Ve
4751 .RE
4752 .RS 4
4753 .RE
4754 .ie n .IP """deb""" 4
4755 .el .IP \f(CWdeb\fR 4
4756 .IX Item "deb"
4757 .PD 0
4758 .ie n .IP """deb_nocontext""" 4
4759 .el .IP \f(CWdeb_nocontext\fR 4
4760 .IX Item "deb_nocontext"
4761 .ie n .IP """vdeb""" 4
4762 .el .IP \f(CWvdeb\fR 4
4763 .IX Xref "deb deb_nocontext vdeb"
4764 .IX Item "vdeb"
4765 .PD
4766 When perl is compiled with \f(CW\*(C`\-DDEBUGGING\*(C'\fR, these each print to STDERR the
4767 information given by the arguments, prefaced by the name of the file containing
4768 the script causing the call, and the line number within that file.
4769 .Sp
4770 If the \f(CW\*(C`v\*(C'\fR (verbose) debugging option is in effect, the process id is also
4771 printed.
4772 .Sp
4773 \&\f(CW\*(C`deb\*(C'\fR and \f(CW\*(C`deb_nocontext\*(C'\fR differ only in that \f(CW\*(C`deb_nocontext\*(C'\fR does not take
4774 a thread context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller
4775 doesn\*(Aqt already have the thread context.
4776 .Sp
4777 \&\f(CW\*(C`vdeb\*(C'\fR is the same as \f(CW\*(C`deb\*(C'\fR except \f(CW\*(C`args\*(C'\fR are an encapsulated argument list.
4778 .RS 4
4779 .Sp
4780 .Vb 5
4781 \& void Perl_deb (pTHX_ const char *pat, ...)
4782 \& void deb_nocontext( const char *pat, ...)
4783 \& void Perl_deb_nocontext( const char *pat, ...)
4784 \& void vdeb ( const char *pat, va_list *args)
4785 \& void Perl_vdeb (pTHX_ const char *pat, va_list *args)
4786 .Ve
4787 .RE
4788 .RS 4
4789 .RE
4790 .ie n .IP """debstack""" 4
4791 .el .IP \f(CWdebstack\fR 4
4792 .IX Xref "debstack"
4793 .IX Item "debstack"
4794 Dump the current stack
4795 .RS 4
4796 .Sp
4797 .Vb 2
4798 \& I32 debstack()
4799 \& I32 Perl_debstack(pTHX)
4800 .Ve
4801 .RE
4802 .RS 4
4803 .RE
4804 .ie n .IP """dump_all""" 4
4805 .el .IP \f(CWdump_all\fR 4
4806 .IX Xref "dump_all"
4807 .IX Item "dump_all"
4808 Dumps the entire optree of the current program starting at \f(CW\*(C`PL_main_root\*(C'\fR to
4809 \&\f(CW\*(C`STDERR\*(C'\fR. Also dumps the optrees for all visible subroutines in
4810 \&\f(CW\*(C`PL_defstash\*(C'\fR.
4811 .RS 4
4812 .Sp
4813 .Vb 2
4814 \& void dump_all()
4815 \& void Perl_dump_all(pTHX)
4816 .Ve
4817 .RE
4818 .RS 4
4819 .RE
4820 .ie n .IP """dump_c_backtrace""" 4
4821 .el .IP \f(CWdump_c_backtrace\fR 4
4822 .IX Xref "dump_c_backtrace"
4823 .IX Item "dump_c_backtrace"
4824 Dumps the C backtrace to the given \f(CW\*(C`fp\*(C'\fR.
4825 .Sp
4826 Returns true if a backtrace could be retrieved, false if not.
4827 .RS 4
4828 .Sp
4829 .Vb 4
4830 \& bool dump_c_backtrace( PerlIO *fp, int max_depth,
4831 \& int skip)
4832 \& bool Perl_dump_c_backtrace(pTHX_ PerlIO *fp, int max_depth,
4833 \& int skip)
4834 .Ve
4835 .RE
4836 .RS 4
4837 .RE
4838 .ie n .IP """dump_eval""" 4
4839 .el .IP \f(CWdump_eval\fR 4
4840 .IX Item "dump_eval"
4841 Described in perlguts.
4842 .RS 4
4843 .Sp
4844 .Vb 2
4845 \& void dump_eval()
4846 \& void Perl_dump_eval(pTHX)
4847 .Ve
4848 .RE
4849 .RS 4
4850 .RE
4851 .ie n .IP """dump_form""" 4
4852 .el .IP \f(CWdump_form\fR 4
4853 .IX Xref "dump_form"
4854 .IX Item "dump_form"
4855 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
4856 message that one doesn\*(Aqt exist.
4857 .RS 4
4858 .Sp
4859 .Vb 2
4860 \& void dump_form( const GV *gv)
4861 \& void Perl_dump_form(pTHX_ const GV *gv)
4862 .Ve
4863 .RE
4864 .RS 4
4865 .RE
4866 .ie n .IP """dump_packsubs""" 4
4867 .el .IP \f(CWdump_packsubs\fR 4
4868 .IX Xref "dump_packsubs"
4869 .IX Item "dump_packsubs"
4870 Dumps the optrees for all visible subroutines in \f(CW\*(C`stash\*(C'\fR.
4871 .RS 4
4872 .Sp
4873 .Vb 2
4874 \& void dump_packsubs( const HV *stash)
4875 \& void Perl_dump_packsubs(pTHX_ const HV *stash)
4876 .Ve
4877 .RE
4878 .RS 4
4879 .RE
4880 .ie n .IP """dump_sub""" 4
4881 .el .IP \f(CWdump_sub\fR 4
4882 .IX Item "dump_sub"
4883 Described in perlguts.
4884 .RS 4
4885 .Sp
4886 .Vb 2
4887 \& void dump_sub( const GV *gv)
4888 \& void Perl_dump_sub(pTHX_ const GV *gv)
4889 .Ve
4890 .RE
4891 .RS 4
4892 .RE
4893 .ie n .IP """get_c_backtrace_dump""" 4
4894 .el .IP \f(CWget_c_backtrace_dump\fR 4
4895 .IX Xref "get_c_backtrace_dump"
4896 .IX Item "get_c_backtrace_dump"
4897 Returns a SV containing a dump of \f(CW\*(C`depth\*(C'\fR frames of the call stack, skipping
4898 the \f(CW\*(C`skip\*(C'\fR innermost ones. \f(CW\*(C`depth\*(C'\fR of 20 is usually enough.
4899 .Sp
4900 The appended output looks like:
4901 .Sp
4902 .Vb 4
4903 \& ...
4904 \& 1 10e004812:0082 Perl_croak util.c:1716 /usr/bin/perl
4905 \& 2 10df8d6d2:1d72 perl_parse perl.c:3975 /usr/bin/perl
4906 \& ...
4907 .Ve
4908 .Sp
4909 The fields are tab\-separated. The first column is the depth (zero
4910 being the innermost non\-skipped frame). In the hex:offset, the hex is
4911 where the program counter was in \f(CW\*(C`S_parse_body\*(C'\fR, and the :offset (might
4912 be missing) tells how much inside the \f(CW\*(C`S_parse_body\*(C'\fR the program counter was.
4913 .Sp
4914 The \f(CW\*(C`util.c:1716\*(C'\fR is the source code file and line number.
4915 .Sp
4916 The \fI/usr/bin/perl\fR is obvious (hopefully).
4917 .Sp
4918 Unknowns are \f(CW"\-"\fR. Unknowns can happen unfortunately quite easily:
4919 if the platform doesn\*(Aqt support retrieving the information;
4920 if the binary is missing the debug information;
4921 if the optimizer has transformed the code by for example inlining.
4922 .RS 4
4923 .Sp
4924 .Vb 2
4925 \& SV * get_c_backtrace_dump( int max_depth, int skip)
4926 \& SV * Perl_get_c_backtrace_dump(pTHX_ int max_depth, int skip)
4927 .Ve
4928 .RE
4929 .RS 4
4930 .RE
4931 .ie n .IP """gv_dump""" 4
4932 .el .IP \f(CWgv_dump\fR 4
4933 .IX Xref "gv_dump"
4934 .IX Item "gv_dump"
4935 Dump the name and, if they differ, the effective name of the GV \f(CW\*(C`gv\*(C'\fR to
4936 \&\f(CW\*(C`STDERR\*(C'\fR.
4937 .RS 4
4938 .Sp
4939 .Vb 2
4940 \& void gv_dump( GV *gv)
4941 \& void Perl_gv_dump(pTHX_ GV *gv)
4942 .Ve
4943 .RE
4944 .RS 4
4945 .RE
4946 .ie n .IP """HAS_BACKTRACE""" 4
4947 .el .IP \f(CWHAS_BACKTRACE\fR 4
4948 .IX Xref "HAS_BACKTRACE"
4949 .IX Item "HAS_BACKTRACE"
4950 This symbol, if defined, indicates that the \f(CWbacktrace()\fR routine is
4951 available to get a stack trace. The \fIexecinfo.h\fR header must be
4952 included to use this routine.
4953 .ie n .IP """hv_dump""" 4
4954 .el .IP \f(CWhv_dump\fR 4
4955 .IX Xref "hv_dump"
4956 .IX Item "hv_dump"
4957 Dumps the contents of an HV to the \f(CW\*(C`STDERR\*(C'\fR filehandle.
4958 Similar to using Devel::Peek on an hashref but does not
4959 expect an RV wrapper. Dumps contents to a depth of 3 levels
4960 deep.
4961 .RS 4
4962 .Sp
4963 .Vb 2
4964 \& void hv_dump( HV *hv)
4965 \& void Perl_hv_dump(pTHX_ HV *hv)
4966 .Ve
4967 .RE
4968 .RS 4
4969 .RE
4970 .ie n .IP """magic_dump""" 4
4971 .el .IP \f(CWmagic_dump\fR 4
4972 .IX Xref "magic_dump"
4973 .IX Item "magic_dump"
4974 Dumps the contents of the MAGIC \f(CW\*(C`mg\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR.
4975 .RS 4
4976 .Sp
4977 .Vb 2
4978 \& void magic_dump( const MAGIC *mg)
4979 \& void Perl_magic_dump(pTHX_ const MAGIC *mg)
4980 .Ve
4981 .RE
4982 .RS 4
4983 .RE
4984 .ie n .IP """op_class""" 4
4985 .el .IP \f(CWop_class\fR 4
4986 .IX Xref "op_class"
4987 .IX Item "op_class"
4988 Given an op, determine what type of struct it has been allocated as.
4989 Returns one of the OPclass enums, such as OPclass_LISTOP.
4990 .RS 4
4991 .Sp
4992 .Vb 2
4993 \& OPclass op_class( const OP *o)
4994 \& OPclass Perl_op_class(pTHX_ const OP *o)
4995 .Ve
4996 .RE
4997 .RS 4
4998 .RE
4999 .ie n .IP """op_dump""" 4
5000 .el .IP \f(CWop_dump\fR 4
5001 .IX Xref "op_dump"
5002 .IX Item "op_dump"
5003 Dumps the optree starting at OP \f(CW\*(C`o\*(C'\fR to \f(CW\*(C`STDERR\*(C'\fR.
5004 .RS 4
5005 .Sp
5006 .Vb 2
5007 \& void op_dump( const OP *o)
5008 \& void Perl_op_dump(pTHX_ const OP *o)
5009 .Ve
5010 .RE
5011 .RS 4
5012 .RE
5013 .ie n .IP """opdump_printf""" 4
5014 .el .IP \f(CWopdump_printf\fR 4
5015 .IX Xref "opdump_printf"
5016 .IX Item "opdump_printf"
5017 Prints formatted output to \f(CW\*(C`STDERR\*(C'\fR according to the pattern and subsequent
5018 arguments, in the style of \f(CWprintf()\fR et.al. This should only be called by
5019 a function invoked by the \f(CW\*(C`xop_dump\*(C'\fR field of a custom operator, where the
5020 \&\f(CW\*(C`ctx\*(C'\fR opaque structure pointer should be passed in from the argument given
5021 to the \f(CW\*(C`xop_dump\*(C'\fR callback.
5022 .Sp
5023 This function handles indentation after linefeeds, so message strings passed
5024 in should not account for it themselves. Multiple lines may be passed to this
5025 function at once, or a single line may be split across multiple calls.
5026 .RS 4
5027 .Sp
5028 .Vb 2
5029 \& void Perl_opdump_printf(pTHX_ struct Perl_OpDumpContext *ctx,
5030 \& const char *pat, ...)
5031 .Ve
5032 .RE
5033 .RS 4
5034 .RE
5035 .ie n .IP """PL_op""" 4
5036 .el .IP \f(CWPL_op\fR 4
5037 .IX Item "PL_op"
5038 Described in perlhacktips.
5039 .ie n .IP """PL_runops""" 4
5040 .el .IP \f(CWPL_runops\fR 4
5041 .IX Item "PL_runops"
5042 Described in perlguts.
5043 .RS 4
5044 .Sp
5045 .Vb 1
5046 \& runops_proc_t PL_runops
5047 .Ve
5048 .RE
5049 .RS 4
5050 .RE
5051 .ie n .IP """PL_sv_serial""" 4
5052 .el .IP \f(CWPL_sv_serial\fR 4
5053 .IX Item "PL_sv_serial"
5054 Described in perlhacktips.
5055 .ie n .IP """pmop_dump""" 4
5056 .el .IP \f(CWpmop_dump\fR 4
5057 .IX Xref "pmop_dump"
5058 .IX Item "pmop_dump"
5059 Dump an OP that is related to Pattern Matching, such as \f(CW\*(C`s/foo/bar/\*(C'\fR; these require
5060 special handling.
5061 .RS 4
5062 .Sp
5063 .Vb 2
5064 \& void pmop_dump( PMOP *pm)
5065 \& void Perl_pmop_dump(pTHX_ PMOP *pm)
5066 .Ve
5067 .RE
5068 .RS 4
5069 .RE
5070 .ie n .IP """sv_dump""" 4
5071 .el .IP \f(CWsv_dump\fR 4
5072 .IX Item "sv_dump"
5073 .PD 0
5074 .ie n .IP """sv_dump_depth""" 4
5075 .el .IP \f(CWsv_dump_depth\fR 4
5076 .IX Xref "sv_dump sv_dump_depth"
5077 .IX Item "sv_dump_depth"
5078 .PD
5079 These each dump the contents of an SV to the \f(CW\*(C`STDERR\*(C'\fR filehandle.
5080 .Sp
5081 \&\f(CW\*(C`sv_dump_depth\*(C'\fR is a more flexible variant of \f(CW\*(C`sv_dump\*(C'\fR, taking an extra
5082 parameter giving the maximum depth to dump.
5083 .Sp
5084 \&\f(CW\*(C`sv_dump\*(C'\fR is limited to dumping items to a depth of 4 if the item is an SvROK,
5085 and dumping only the top level item otherwise. This means that it will not
5086 dump the contents of an \f(CW\*(C`AV\ *\*(C'\fR or \f(CW\*(C`HV\ *\*(C'\fR. For that use \f(CW"av_dump"\fR
5087 or \f(CW"hv_dump"\fR.
5088 .Sp
5089 For an example of its output, see Devel::Peek.
5090 .Sp
5091 In contrast, \f(CW\*(C`sv_dump_depth\*(C'\fR can be used on any SV derived type (GV, HV, AV)
5092 with an appropriate cast:
5093 .Sp
5094 .Vb 2
5095 \& HV *hv = ...;
5096 \& sv_dump_depth((SV*)hv, 2);
5097 .Ve
5098 .Sp
5099 would dump the hv, its keys and values, but would not recurse
5100 into any RV values.
5101 .RS 4
5102 .Sp
5103 .Vb 4
5104 \& void sv_dump ( SV *sv)
5105 \& void Perl_sv_dump (pTHX_ SV *sv)
5106 \& void sv_dump_depth( SV *sv, I32 depth)
5107 \& void Perl_sv_dump_depth(pTHX_ SV *sv, I32 depth)
5108 .Ve
5109 .RE
5110 .RS 4
5111 .RE
5112 .ie n .IP """vdeb*""" 4
5113 .el .IP \f(CWvdeb*\fR 4
5114 .IX Item "vdeb*"
5115 Described under \f(CW"deb"\fR
5116 .SH "Display functions"
5117 .IX Xref "PERL_PV_ESCAPE_ALL PERL_PV_ESCAPE_FIRSTCHAR PERL_PV_ESCAPE_NOBACKSLASH PERL_PV_ESCAPE_NOCLEAR PERL_PV_ESCAPE_NON_WC PERL_PV_ESCAPE_NONASCII 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"
5118 .IX Header "Display functions"
5119 .ie n .IP """form""" 4
5120 .el .IP \f(CWform\fR 4
5121 .IX Item "form"
5122 .PD 0
5123 .ie n .IP """form_nocontext""" 4
5124 .el .IP \f(CWform_nocontext\fR 4
5125 .IX Item "form_nocontext"
5126 .ie n .IP """vform""" 4
5127 .el .IP \f(CWvform\fR 4
5128 .IX Xref "form form_nocontext vform"
5129 .IX Item "vform"
5130 .PD
5131 These each take a sprintf\-style format pattern and conventional
5132 (non\-SV) arguments and return the formatted string.
5133 .Sp
5134 .Vb 1
5135 \& (char *) form(const char* pat, ...)
5136 .Ve
5137 .Sp
5138 They can be used any place a string (char *) is required:
5139 .Sp
5140 .Vb 1
5141 \& char * s = form_nocontext("%d.%d", major, minor);
5142 .Ve
5143 .Sp
5144 They each return a temporary that will be freed "soon", automatically by the
5145 system, at the same time that SVs operated on by \f(CW"sv_2mortal"\fR are freed.
5146 .Sp
5147 Use the result immediately, or copy to a stable place for longer retention.
5148 This is contrary to the incorrect previous documentation of these that claimed
5149 that the return was a single per\-thread buffer. That was (and is) actually
5150 true only when these are called during global destruction.
5151 .Sp
5152 \&\f(CW\*(C`form\*(C'\fR and \f(CW\*(C`form_nocontext\*(C'\fR differ only in that \f(CW\*(C`form_nocontext\*(C'\fR does
5153 not take a thread context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where
5154 the caller doesn\*(Aqt already have the thread context (and can be called without
5155 the \f(CW\*(C`Perl_\*(C'\fR prefix.
5156 .Sp
5157 \&\f(CW\*(C`vform\*(C'\fR is the same as \f(CW\*(C`form\*(C'\fR except the arguments are an encapsulated
5158 argument list. It does need a thread context parameter, but that is supplied
5159 automatically when called without the \f(CW\*(C`Perl_\*(C'\fR prefix.
5160 .RS 4
5161 .Sp
5162 .Vb 5
5163 \& char * Perl_form (pTHX_ const char *pat, ...)
5164 \& char * form_nocontext( const char *pat, ...)
5165 \& char * Perl_form_nocontext( const char *pat, ...)
5166 \& char * vform ( const char *pat, va_list *args)
5167 \& char * Perl_vform (pTHX_ const char *pat, va_list *args)
5168 .Ve
5169 .RE
5170 .RS 4
5171 .RE
5172 .ie n .IP """mess""" 4
5173 .el .IP \f(CWmess\fR 4
5174 .IX Item "mess"
5175 .PD 0
5176 .ie n .IP """mess_nocontext""" 4
5177 .el .IP \f(CWmess_nocontext\fR 4
5178 .IX Item "mess_nocontext"
5179 .ie n .IP """vmess""" 4
5180 .el .IP \f(CWvmess\fR 4
5181 .IX Xref "mess mess_nocontext vmess"
5182 .IX Item "vmess"
5183 .PD
5184 These each take a sprintf\-style format pattern and argument list, which are
5185 used to generate a string message. If the message does not end with a newline,
5186 then it will be extended with some indication of the current location in the
5187 code, as described for \f(CW"mess_sv"\fR.
5188 .Sp
5189 \&\f(CW\*(C`mess\*(C'\fR and \f(CW\*(C`mess_nocontext\*(C'\fR differ only in that \f(CW\*(C`mess_nocontext\*(C'\fR does
5190 not take a thread context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where
5191 the caller doesn\*(Aqt already have the thread context.
5192 .Sp
5193 \&\f(CW\*(C`vmess\*(C'\fR is the same as \f(CW\*(C`mess\*(C'\fR except the arguments are an encapsulated
5194 argument list. It needs a thread context parameter only when called with the
5195 \&\f(CW\*(C`Perl_\*(C'\fR prefix.
5196 .Sp
5197 Normally, the resulting message is returned in a new mortal SV.
5198 But during global destruction a single SV may be shared between uses of
5199 this function.
5200 .RS 4
5201 .Sp
5202 .Vb 5
5203 \& SV * Perl_mess (pTHX_ const char *pat, ...)
5204 \& SV * mess_nocontext( const char *pat, ...)
5205 \& SV * Perl_mess_nocontext( const char *pat, ...)
5206 \& SV * vmess ( const char *pat, va_list *args)
5207 \& SV * Perl_vmess (pTHX_ const char *pat, va_list *args)
5208 .Ve
5209 .RE
5210 .RS 4
5211 .RE
5212 .ie n .IP """mess_sv""" 4
5213 .el .IP \f(CWmess_sv\fR 4
5214 .IX Xref "mess_sv"
5215 .IX Item "mess_sv"
5216 Expands a message, intended for the user, to include an indication of
5217 the current location in the code, if the message does not already appear
5218 to be complete.
5219 .Sp
5220 \&\f(CW\*(C`basemsg\*(C'\fR is the initial message or object. If it is a reference, it
5221 will be used as\-is and will be the result of this function. Otherwise it
5222 is used as a string, and if it already ends with a newline, it is taken
5223 to be complete, and the result of this function will be the same string.
5224 If the message does not end with a newline, then a segment such as \f(CW\*(C`at
5225 foo.pl line 37\*(C'\fR will be appended, and possibly other clauses indicating
5226 the current state of execution. The resulting message will end with a
5227 dot and a newline.
5228 .Sp
5229 Normally, the resulting message is returned in a new mortal SV.
5230 During global destruction a single SV may be shared between uses of this
5231 function. If \f(CW\*(C`consume\*(C'\fR is true, then the function is permitted (but not
5232 required) to modify and return \f(CW\*(C`basemsg\*(C'\fR instead of allocating a new SV.
5233 .RS 4
5234 .Sp
5235 .Vb 2
5236 \& SV * mess_sv( SV *basemsg, bool consume)
5237 \& SV * Perl_mess_sv(pTHX_ SV *basemsg, bool consume)
5238 .Ve
5239 .RE
5240 .RS 4
5241 .RE
5242 .ie n .IP """pv_display""" 4
5243 .el .IP \f(CWpv_display\fR 4
5244 .IX Xref "pv_display"
5245 .IX Item "pv_display"
5246 Similar to
5247 .Sp
5248 .Vb 1
5249 \& pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
5250 .Ve
5251 .Sp
5252 except that an additional "\e0" will be appended to the string when
5253 len > cur and pv[cur] is "\e0".
5254 .Sp
5255 Note that the final string may be up to 7 chars longer than pvlim.
5256 .RS 4
5257 .Sp
5258 .Vb 6
5259 \& char * pv_display( SV *dsv, const char *pv,
5260 \& STRLEN cur, STRLEN len,
5261 \& STRLEN pvlim)
5262 \& char * Perl_pv_display(pTHX_ SV *dsv, const char *pv,
5263 \& STRLEN cur, STRLEN len,
5264 \& STRLEN pvlim)
5265 .Ve
5266 .RE
5267 .RS 4
5268 .RE
5269 .ie n .IP """pv_escape""" 4
5270 .el .IP \f(CWpv_escape\fR 4
5271 .IX Xref "pv_escape"
5272 .IX Item "pv_escape"
5273 Escapes at most the first \f(CW\*(C`count\*(C'\fR chars of \f(CW\*(C`pv\*(C'\fR and puts the results into
5274 \&\f(CW\*(C`dsv\*(C'\fR such that the size of the escaped string will not exceed \f(CW\*(C`max\*(C'\fR chars
5275 and will not contain any incomplete escape sequences. The number of bytes
5276 escaped will be returned in the \f(CW\*(C`STRLEN *escaped\*(C'\fR parameter if it is not null.
5277 When the \f(CW\*(C`dsv\*(C'\fR parameter is null no escaping actually occurs, but the number
5278 of bytes that would be escaped were it not null will be calculated.
5279 .Sp
5280 If flags contains \f(CW\*(C`PERL_PV_ESCAPE_QUOTE\*(C'\fR then any double quotes in the string
5281 will also be escaped.
5282 .Sp
5283 Normally the SV will be cleared before the escaped string is prepared,
5284 but when \f(CW\*(C`PERL_PV_ESCAPE_NOCLEAR\*(C'\fR is set this will not occur.
5285 .Sp
5286 If \f(CW\*(C`PERL_PV_ESCAPE_UNI\*(C'\fR is set then the input string is treated as UTF\-8.
5287 If \f(CW\*(C`PERL_PV_ESCAPE_UNI_DETECT\*(C'\fR is set then the input string is scanned
5288 using \f(CWis_utf8_string()\fR to determine if it is UTF\-8.
5289 .Sp
5290 If \f(CW\*(C`PERL_PV_ESCAPE_ALL\*(C'\fR is set then all input chars will be output
5291 using \f(CW\*(C`\ex01F1\*(C'\fR style escapes, otherwise if \f(CW\*(C`PERL_PV_ESCAPE_NONASCII\*(C'\fR
5292 is set, only non\-ASCII chars will be escaped using this style;
5293 otherwise, only chars above 255 will be so escaped; other non printable
5294 chars will use octal or common escaped patterns like \f(CW\*(C`\en\*(C'\fR. Otherwise,
5295 if \f(CW\*(C`PERL_PV_ESCAPE_NOBACKSLASH\*(C'\fR then all chars below 255 will be
5296 treated as printable and will be output as literals. The
5297 \&\f(CW\*(C`PERL_PV_ESCAPE_NON_WC\*(C'\fR modifies the previous rules to cause word
5298 chars, unicode or otherwise, to be output as literals, note this uses
5299 the *unicode* rules for deciding on word characters.
5300 .Sp
5301 If \f(CW\*(C`PERL_PV_ESCAPE_FIRSTCHAR\*(C'\fR is set then only the first char of the
5302 string will be escaped, regardless of max. If the output is to be in
5303 hex, then it will be returned as a plain hex sequence. Thus the output
5304 will either be a single char, an octal escape sequence, a special escape
5305 like \f(CW\*(C`\en\*(C'\fR or a hex value.
5306 .Sp
5307 If \f(CW\*(C`PERL_PV_ESCAPE_RE\*(C'\fR is set then the escape char used will be a
5308 \&\f(CW"%"\fR and not a \f(CW"\e\e"\fR. This is because regexes very often contain
5309 backslashed sequences, whereas \f(CW"%"\fR is not a particularly common
5310 character in patterns.
5311 .Sp
5312 Returns a pointer to the escaped text as held by \f(CW\*(C`dsv\*(C'\fR.
5313 .RS 4
5314 .Sp
5315 .Vb 6
5316 \& char * pv_escape( SV *dsv, char const * const str,
5317 \& const STRLEN count, STRLEN max,
5318 \& STRLEN * const escaped, U32 flags)
5319 \& char * Perl_pv_escape(pTHX_ SV *dsv, char const * const str,
5320 \& const STRLEN count, STRLEN max,
5321 \& STRLEN * const escaped, U32 flags)
5322 .Ve
5323 .RE
5324 .RS 4
5325 .RE
5326 .ie n .IP """pv_pretty""" 4
5327 .el .IP \f(CWpv_pretty\fR 4
5328 .IX Xref "pv_pretty"
5329 .IX Item "pv_pretty"
5330 Converts a string into something presentable, handling escaping via
5331 \&\f(CWpv_escape()\fR and supporting quoting and ellipses.
5332 .Sp
5333 If the \f(CW\*(C`PERL_PV_PRETTY_QUOTE\*(C'\fR flag is set then the result will be
5334 double quoted with any double quotes in the string escaped. Otherwise
5335 if the \f(CW\*(C`PERL_PV_PRETTY_LTGT\*(C'\fR flag is set then the result be wrapped in
5336 angle brackets.
5337 .Sp
5338 If the \f(CW\*(C`PERL_PV_PRETTY_ELLIPSES\*(C'\fR flag is set and not all characters in
5339 string were output then an ellipsis \f(CW\*(C`...\*(C'\fR will be appended to the
5340 string. Note that this happens AFTER it has been quoted.
5341 .Sp
5342 If \f(CW\*(C`start_color\*(C'\fR is non\-null then it will be inserted after the opening
5343 quote (if there is one) but before the escaped text. If \f(CW\*(C`end_color\*(C'\fR
5344 is non\-null then it will be inserted after the escaped text but before
5345 any quotes or ellipses.
5346 .Sp
5347 Returns a pointer to the prettified text as held by \f(CW\*(C`dsv\*(C'\fR.
5348 .RS 4
5349 .Sp
5350 .Vb 12
5351 \& char * pv_pretty( SV *dsv, char const * const str,
5352 \& const STRLEN count,
5353 \& const STRLEN max,
5354 \& char const * const start_color,
5355 \& char const * const end_color,
5356 \& const U32 flags)
5357 \& char * Perl_pv_pretty(pTHX_ SV *dsv, char const * const str,
5358 \& const STRLEN count,
5359 \& const STRLEN max,
5360 \& char const * const start_color,
5361 \& char const * const end_color,
5362 \& const U32 flags)
5363 .Ve
5364 .RE
5365 .RS 4
5366 .RE
5367 .ie n .IP """vform*""" 4
5368 .el .IP \f(CWvform*\fR 4
5369 .IX Item "vform*"
5370 Described under \f(CW"form"\fR
5371 .ie n .IP """vmess*""" 4
5372 .el .IP \f(CWvmess*\fR 4
5373 .IX Item "vmess*"
5374 Described under \f(CW"mess"\fR
5375 .SH "Embedding, Threads, and Interpreter Cloning"
5376 .IX Xref "CV_NAME_NOTQUAL NOT_IN_PAD 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"
5377 .IX Header "Embedding, Threads, and Interpreter Cloning"
5378 .ie n .IP """call_atexit""" 4
5379 .el .IP \f(CWcall_atexit\fR 4
5380 .IX Xref "call_atexit"
5381 .IX Item "call_atexit"
5382 Add a function \f(CW\*(C`fn\*(C'\fR to the list of functions to be called at global
5383 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
5384 \&\f(CW\*(C`struct\*(C'\fR so that you can pass anything you want.
5385 .Sp
5386 Note that under threads, \f(CW\*(C`fn\*(C'\fR may run multiple times. This is because the
5387 list is executed each time the current or any descendent thread terminates.
5388 .RS 4
5389 .Sp
5390 .Vb 2
5391 \& void call_atexit( ATEXIT_t fn, void *ptr)
5392 \& void Perl_call_atexit(pTHX_ ATEXIT_t fn, void *ptr)
5393 .Ve
5394 .RE
5395 .RS 4
5396 .RE
5397 .ie n .IP """cv_clone""" 4
5398 .el .IP \f(CWcv_clone\fR 4
5399 .IX Xref "cv_clone"
5400 .IX Item "cv_clone"
5401 Clone a CV, making a lexical closure. \f(CW\*(C`proto\*(C'\fR supplies the prototype
5402 of the function: its code, pad structure, and other attributes.
5403 The prototype is combined with a capture of outer lexicals to which the
5404 code refers, which are taken from the currently\-executing instance of
5405 the immediately surrounding code.
5406 .RS 4
5407 .Sp
5408 .Vb 2
5409 \& CV * cv_clone( CV *proto)
5410 \& CV * Perl_cv_clone(pTHX_ CV *proto)
5411 .Ve
5412 .RE
5413 .RS 4
5414 .RE
5415 .ie n .IP """cv_name""" 4
5416 .el .IP \f(CWcv_name\fR 4
5417 .IX Xref "cv_name"
5418 .IX Item "cv_name"
5419 Returns an SV containing the name of the CV, mainly for use in error
5420 reporting. The CV may actually be a GV instead, in which case the returned
5421 SV holds the GV\*(Aqs name. Anything other than a GV or CV is treated as a
5422 string already holding the sub name, but this could change in the future.
5423 .Sp
5424 An SV may be passed as a second argument. If so, the name will be assigned
5425 to it and it will be returned. Otherwise the returned SV will be a new
5426 mortal.
5427 .Sp
5428 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
5429 included. If the first argument is neither a CV nor a GV, this flag is
5430 ignored (subject to change).
5431 .RS 4
5432 .Sp
5433 .Vb 2
5434 \& SV * cv_name( NOCHECK CV *cv, SV *sv, U32 flags)
5435 \& SV * Perl_cv_name(pTHX_ NOCHECK CV *cv, SV *sv, U32 flags)
5436 .Ve
5437 .RE
5438 .RS 4
5439 .RE
5440 .ie n .IP """cv_undef""" 4
5441 .el .IP \f(CWcv_undef\fR 4
5442 .IX Xref "cv_undef"
5443 .IX Item "cv_undef"
5444 Clear out all the active components of a CV. This can happen either
5445 by an explicit \f(CW\*(C`undef &foo\*(C'\fR, or by the reference count going to zero.
5446 In the former case, we keep the \f(CW\*(C`CvOUTSIDE\*(C'\fR pointer, so that any anonymous
5447 children can still follow the full lexical scope chain.
5448 .RS 4
5449 .Sp
5450 .Vb 2
5451 \& void cv_undef( CV *cv)
5452 \& void Perl_cv_undef(pTHX_ CV *cv)
5453 .Ve
5454 .RE
5455 .RS 4
5456 .RE
5457 .ie n .IP """find_rundefsv""" 4
5458 .el .IP \f(CWfind_rundefsv\fR 4
5459 .IX Xref "find_rundefsv"
5460 .IX Item "find_rundefsv"
5461 Returns the global variable \f(CW$_\fR.
5462 .RS 4
5463 .Sp
5464 .Vb 2
5465 \& SV * find_rundefsv()
5466 \& SV * Perl_find_rundefsv(pTHX)
5467 .Ve
5468 .RE
5469 .RS 4
5470 .RE
5471 .ie n .IP """get_op_descs""" 4
5472 .el .IP \f(CWget_op_descs\fR 4
5473 .IX Xref "get_op_descs"
5474 .IX Item "get_op_descs"
5475 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`get_op_descs\*(C'\fR
5476 from a future release of Perl. Do not use it for
5477 new code; remove it from existing code.
5478 .Sp
5479 Return a pointer to the array of all the descriptions of the various OPs
5480 Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_desc[opcode]\*(C'\fR returns a
5481 pointer to a C language string giving its description.
5482 .RS 4
5483 .Sp
5484 .Vb 2
5485 \& char ** get_op_descs()
5486 \& char ** Perl_get_op_descs(pTHX)
5487 .Ve
5488 .RE
5489 .RS 4
5490 .RE
5491 .ie n .IP """get_op_names""" 4
5492 .el .IP \f(CWget_op_names\fR 4
5493 .IX Xref "get_op_names"
5494 .IX Item "get_op_names"
5495 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`get_op_names\*(C'\fR
5496 from a future release of Perl. Do not use it for
5497 new code; remove it from existing code.
5498 .Sp
5499 Return a pointer to the array of all the names of the various OPs
5500 Given an opcode from the enum in \fIopcodes.h\fR, \f(CW\*(C`PL_op_name[opcode]\*(C'\fR returns a
5501 pointer to a C language string giving its name.
5502 .RS 4
5503 .Sp
5504 .Vb 2
5505 \& char ** get_op_names()
5506 \& char ** Perl_get_op_names(pTHX)
5507 .Ve
5508 .RE
5509 .RS 4
5510 .RE
5511 .ie n .IP """HAS_SKIP_LOCALE_INIT""" 4
5512 .el .IP \f(CWHAS_SKIP_LOCALE_INIT\fR 4
5513 .IX Item "HAS_SKIP_LOCALE_INIT"
5514 Described in perlembed.
5515 .ie n .IP """intro_my""" 4
5516 .el .IP \f(CWintro_my\fR 4
5517 .IX Xref "intro_my"
5518 .IX Item "intro_my"
5519 "Introduce" \f(CW\*(C`my\*(C'\fR variables to visible status. This is called during parsing
5520 at the end of each statement to make lexical variables visible to subsequent
5521 statements.
5522 .RS 4
5523 .Sp
5524 .Vb 2
5525 \& U32 intro_my()
5526 \& U32 Perl_intro_my(pTHX)
5527 .Ve
5528 .RE
5529 .RS 4
5530 .RE
5531 .ie n .IP """load_module""" 4
5532 .el .IP \f(CWload_module\fR 4
5533 .IX Item "load_module"
5534 .PD 0
5535 .ie n .IP """load_module_nocontext""" 4
5536 .el .IP \f(CWload_module_nocontext\fR 4
5537 .IX Xref "load_module load_module_nocontext"
5538 .IX Item "load_module_nocontext"
5539 .PD
5540 These load the module whose name is pointed to by the string part of \f(CW\*(C`name\*(C'\fR.
5541 Note that the actual module name, not its filename, should be given.
5542 Eg, "Foo::Bar" instead of "Foo/Bar.pm". ver, if specified and not NULL,
5543 provides version semantics similar to \f(CW\*(C`use Foo::Bar VERSION\*(C'\fR. The optional
5544 trailing arguments can be used to specify arguments to the module\*(Aqs \f(CWimport()\fR
5545 method, similar to \f(CW\*(C`use Foo::Bar VERSION LIST\*(C'\fR; their precise handling depends
5546 on the flags. The flags argument is a bitwise\-ORed collection of any of
5547 \&\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
5548 (or 0 for no flags).
5549 .Sp
5550 If \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR is set, the module is loaded as if with an empty
5551 import list, as in \f(CW\*(C`use Foo::Bar ()\*(C'\fR; this is the only circumstance in which
5552 the trailing optional arguments may be omitted entirely. Otherwise, if
5553 \&\f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is set, the trailing arguments must consist of
5554 exactly one \f(CW\*(C`OP*\*(C'\fR, containing the op tree that produces the relevant import
5555 arguments. Otherwise, the trailing arguments must all be \f(CW\*(C`SV*\*(C'\fR values that
5556 will be used as import arguments; and the list must be terminated with \f(CW\*(C`(SV*)
5557 NULL\*(C'\fR. If neither \f(CW\*(C`PERL_LOADMOD_NOIMPORT\*(C'\fR nor \f(CW\*(C`PERL_LOADMOD_IMPORT_OPS\*(C'\fR is
5558 set, the trailing \f(CW\*(C`NULL\*(C'\fR pointer is needed even if no import arguments are
5559 desired. The reference count for each specified \f(CW\*(C`SV*\*(C'\fR argument is
5560 decremented. In addition, the \f(CW\*(C`name\*(C'\fR argument is modified.
5561 .Sp
5562 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
5563 than \f(CW\*(C`use\*(C'\fR.
5564 .Sp
5565 \&\f(CW\*(C`load_module\*(C'\fR and \f(CW\*(C`load_module_nocontext\*(C'\fR have the same apparent signature,
5566 but the former hides the fact that it is accessing a thread context parameter.
5567 So use the latter when you get a compilation error about \f(CW\*(C`pTHX\*(C'\fR.
5568 .RS 4
5569 .Sp
5570 .Vb 8
5571 \& void load_module ( U32 flags, SV *name,
5572 \& SV *ver, ...)
5573 \& void Perl_load_module (pTHX_ U32 flags, SV *name,
5574 \& SV *ver, ...)
5575 \& void load_module_nocontext( U32 flags, SV *name,
5576 \& SV *ver, ...)
5577 \& void Perl_load_module_nocontext( U32 flags, SV *name,
5578 \& SV *ver, ...)
5579 .Ve
5580 .RE
5581 .RS 4
5582 .RE
5583 .ie n .IP """my_exit""" 4
5584 .el .IP \f(CWmy_exit\fR 4
5585 .IX Xref "my_exit"
5586 .IX Item "my_exit"
5587 A wrapper for the C library \fBexit\fR\|(3), honoring what "PL_exit_flags" in perlapi
5588 say to do.
5589 .RS 4
5590 .Sp
5591 .Vb 2
5592 \& void my_exit( U32 status)
5593 \& void Perl_my_exit(pTHX_ U32 status)
5594 .Ve
5595 .RE
5596 .RS 4
5597 .RE
5598 .ie n .IP """my_failure_exit""" 4
5599 .el .IP \f(CWmy_failure_exit\fR 4
5600 .IX Xref "my_failure_exit"
5601 .IX Item "my_failure_exit"
5602 Exit the running Perl process with an error.
5603 .Sp
5604 On non\-VMS platforms, this is essentially equivalent to "\f(CW\*(C`my_exit\*(C'\fR", using
5605 \&\f(CW\*(C`errno\*(C'\fR, but forces an en error code of 255 if \f(CW\*(C`errno\*(C'\fR is 0.
5606 .Sp
5607 On VMS, it takes care to set the appropriate severity bits in the exit status.
5608 .RS 4
5609 .Sp
5610 .Vb 2
5611 \& void my_failure_exit()
5612 \& void Perl_my_failure_exit(pTHX)
5613 .Ve
5614 .RE
5615 .RS 4
5616 .RE
5617 .ie n .IP """newPADNAMELIST""" 4
5618 .el .IP \f(CWnewPADNAMELIST\fR 4
5619 .IX Xref "newPADNAMELIST"
5620 .IX Item "newPADNAMELIST"
5621 NOTE: \f(CW\*(C`newPADNAMELIST\*(C'\fR is \fBexperimental\fR and may change or be
5622 removed without notice.
5623 .Sp
5624 Creates a new pad name list. \f(CW\*(C`max\*(C'\fR is the highest index for which space
5625 is allocated.
5626 .RS 4
5627 .Sp
5628 .Vb 2
5629 \& PADNAMELIST * newPADNAMELIST(size_t max)
5630 \& PADNAMELIST * Perl_newPADNAMELIST(size_t max)
5631 .Ve
5632 .RE
5633 .RS 4
5634 .RE
5635 .ie n .IP """newPADNAMEouter""" 4
5636 .el .IP \f(CWnewPADNAMEouter\fR 4
5637 .IX Xref "newPADNAMEouter"
5638 .IX Item "newPADNAMEouter"
5639 NOTE: \f(CW\*(C`newPADNAMEouter\*(C'\fR is \fBexperimental\fR and may change or be
5640 removed without notice.
5641 .Sp
5642 Constructs and returns a new pad name. Only use this function for names
5643 that refer to outer lexicals. (See also "newPADNAMEpvn".) \f(CW\*(C`outer\*(C'\fR is
5644 the outer pad name that this one mirrors. The returned pad name has the
5645 \&\f(CW\*(C`PADNAMEf_OUTER\*(C'\fR flag already set.
5646 .RS 4
5647 .Sp
5648 .Vb 2
5649 \& PADNAME * newPADNAMEouter(PADNAME *outer)
5650 \& PADNAME * Perl_newPADNAMEouter(PADNAME *outer)
5651 .Ve
5652 .RE
5653 .RS 4
5654 .RE
5655 .ie n .IP """newPADNAMEpvn""" 4
5656 .el .IP \f(CWnewPADNAMEpvn\fR 4
5657 .IX Xref "newPADNAMEpvn"
5658 .IX Item "newPADNAMEpvn"
5659 NOTE: \f(CW\*(C`newPADNAMEpvn\*(C'\fR is \fBexperimental\fR and may change or be
5660 removed without notice.
5661 .Sp
5662 Constructs and returns a new pad name. \f(CW\*(C`s\*(C'\fR must be a UTF\-8 string. Do not
5663 use this for pad names that point to outer lexicals. See
5664 \&\f(CW"newPADNAMEouter"\fR.
5665 .RS 4
5666 .Sp
5667 .Vb 2
5668 \& PADNAME * newPADNAMEpvn(const char *s, STRLEN len)
5669 \& PADNAME * Perl_newPADNAMEpvn(const char *s, STRLEN len)
5670 .Ve
5671 .RE
5672 .RS 4
5673 .RE
5674 .ie n .IP """nothreadhook""" 4
5675 .el .IP \f(CWnothreadhook\fR 4
5676 .IX Xref "nothreadhook"
5677 .IX Item "nothreadhook"
5678 Stub that provides thread hook for perl_destruct when there are
5679 no threads.
5680 .RS 4
5681 .Sp
5682 .Vb 2
5683 \& int nothreadhook()
5684 \& int Perl_nothreadhook(pTHX)
5685 .Ve
5686 .RE
5687 .RS 4
5688 .RE
5689 .ie n .IP """pad_add_anon""" 4
5690 .el .IP \f(CWpad_add_anon\fR 4
5691 .IX Xref "pad_add_anon"
5692 .IX Item "pad_add_anon"
5693 Allocates a place in the currently\-compiling pad (via "pad_alloc")
5694 for an anonymous function that is lexically scoped inside the
5695 currently\-compiling function.
5696 The function \f(CW\*(C`func\*(C'\fR is linked into the pad, and its \f(CW\*(C`CvOUTSIDE\*(C'\fR link
5697 to the outer scope is weakened to avoid a reference loop.
5698 .Sp
5699 One reference count is stolen, so you may need to do \f(CWSvREFCNT_inc(func)\fR.
5700 .Sp
5701 \&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the
5702 pad entry is to support. This doesn\*(Aqt affect operational semantics,
5703 but is used for debugging.
5704 .RS 4
5705 .Sp
5706 .Vb 2
5707 \& PADOFFSET pad_add_anon( CV *func, I32 optype)
5708 \& PADOFFSET Perl_pad_add_anon(pTHX_ CV *func, I32 optype)
5709 .Ve
5710 .RE
5711 .RS 4
5712 .RE
5713 .ie n .IP """pad_add_name_pv""" 4
5714 .el .IP \f(CWpad_add_name_pv\fR 4
5715 .IX Item "pad_add_name_pv"
5716 .PD 0
5717 .ie n .IP """pad_add_name_pvn""" 4
5718 .el .IP \f(CWpad_add_name_pvn\fR 4
5719 .IX Item "pad_add_name_pvn"
5720 .ie n .IP """pad_add_name_sv""" 4
5721 .el .IP \f(CWpad_add_name_sv\fR 4
5722 .IX Xref "pad_add_name_pv pad_add_name_pvn pad_add_name_sv"
5723 .IX Item "pad_add_name_sv"
5724 .PD
5725 These each allocate a place in the currently\-compiling pad for a named lexical
5726 variable. They store the name and other metadata in the name part of the
5727 pad, and make preparations to manage the variable\*(Aqs lexical scoping.
5728 They return the offset of the allocated pad slot.
5729 .Sp
5730 They differ only in how the input variable\*(Aqs name is specified.
5731 .Sp
5732 If \f(CW\*(C`typestash\*(C'\fR is non\-null, the name is for a typed lexical, and this
5733 identifies the type. If \f(CW\*(C`ourstash\*(C'\fR is non\-null, it\*(Aqs a lexical reference
5734 to a package variable, and this identifies the package. The following
5735 flags can be OR\*(Aqed together:
5736 .Sp
5737 .Vb 4
5738 \& padadd_OUR redundantly specifies if it\*(Aqs a package var
5739 \& padadd_STATE variable will retain value persistently
5740 \& padadd_NO_DUP_CHECK skip check for lexical shadowing
5741 \& padadd_FIELD specifies that the lexical is a field for a class
5742 .Ve
5743 .Sp
5744 In all forms, the variable name must include the leading sigil.
5745 .Sp
5746 In \f(CW\*(C`pad_add_name_sv\*(C'\fR, the input name is taken from the SV parameter using
5747 \&\f(CW\*(C`"SvPVutf8"()\*(C'\fR.
5748 .Sp
5749 In \f(CW\*(C`pad_add_name_pv\*(C'\fR, the input name is a NUL\-terminated string, which must be
5750 encoded in UTF\-8.
5751 .Sp
5752 In \f(CW\*(C`pad_add_name_pvn\*(C'\fR, \f(CW\*(C`namelen\*(C'\fR gives the length of the input name in bytes,
5753 which means it may contain embedded NUL characters. Again, it must be encoded
5754 in UTF\-8.
5755 .RS 4
5756 .Sp
5757 .Vb 10
5758 \& PADOFFSET pad_add_name_pv ( const char *name,
5759 \& const U32 flags,
5760 \& HV *typestash,
5761 \& HV *ourstash)
5762 \& PADOFFSET Perl_pad_add_name_pv (pTHX_ const char *name,
5763 \& const U32 flags,
5764 \& HV *typestash,
5765 \& HV *ourstash)
5766 \& PADOFFSET pad_add_name_pvn( const char *namepv,
5767 \& STRLEN namelen, U32 flags,
5768 \& HV *typestash,
5769 \& HV *ourstash)
5770 \& PADOFFSET Perl_pad_add_name_pvn(pTHX_ const char *namepv,
5771 \& STRLEN namelen, U32 flags,
5772 \& HV *typestash,
5773 \& HV *ourstash)
5774 \& PADOFFSET pad_add_name_sv ( SV *name, U32 flags,
5775 \& HV *typestash,
5776 \& HV *ourstash)
5777 \& PADOFFSET Perl_pad_add_name_sv (pTHX_ SV *name, U32 flags,
5778 \& HV *typestash,
5779 \& HV *ourstash)
5780 .Ve
5781 .RE
5782 .RS 4
5783 .RE
5784 .ie n .IP """pad_alloc""" 4
5785 .el .IP \f(CWpad_alloc\fR 4
5786 .IX Xref "pad_alloc"
5787 .IX Item "pad_alloc"
5788 NOTE: \f(CW\*(C`pad_alloc\*(C'\fR is \fBexperimental\fR and may change or be
5789 removed without notice.
5790 .Sp
5791 Allocates a place in the currently\-compiling pad,
5792 returning the offset of the allocated pad slot.
5793 No name is initially attached to the pad slot.
5794 \&\f(CW\*(C`tmptype\*(C'\fR is a set of flags indicating the kind of pad entry required,
5795 which will be set in the value SV for the allocated pad entry:
5796 .Sp
5797 .Vb 3
5798 \& SVs_PADMY named lexical variable ("my", "our", "state")
5799 \& SVs_PADTMP unnamed temporary store
5800 \& SVf_READONLY constant shared between recursion levels
5801 .Ve
5802 .Sp
5803 \&\f(CW\*(C`SVf_READONLY\*(C'\fR has been supported here only since perl 5.20. To work with
5804 earlier versions as well, use \f(CW\*(C`SVf_READONLY|SVs_PADTMP\*(C'\fR. \f(CW\*(C`SVf_READONLY\*(C'\fR
5805 does not cause the SV in the pad slot to be marked read\-only, but simply
5806 tells \f(CW\*(C`pad_alloc\*(C'\fR that it \fIwill\fR be made read\-only (by the caller), or at
5807 least should be treated as such.
5808 .Sp
5809 \&\f(CW\*(C`optype\*(C'\fR should be an opcode indicating the type of operation that the
5810 pad entry is to support. This doesn\*(Aqt affect operational semantics,
5811 but is used for debugging.
5812 .RS 4
5813 .Sp
5814 .Vb 2
5815 \& PADOFFSET pad_alloc( I32 optype, U32 tmptype)
5816 \& PADOFFSET Perl_pad_alloc(pTHX_ I32 optype, U32 tmptype)
5817 .Ve
5818 .RE
5819 .RS 4
5820 .RE
5821 .ie n .IP """pad_findmy_pv""" 4
5822 .el .IP \f(CWpad_findmy_pv\fR 4
5823 .IX Item "pad_findmy_pv"
5824 .PD 0
5825 .ie n .IP """pad_findmy_pvn""" 4
5826 .el .IP \f(CWpad_findmy_pvn\fR 4
5827 .IX Item "pad_findmy_pvn"
5828 .ie n .IP """pad_findmy_pvs""" 4
5829 .el .IP \f(CWpad_findmy_pvs\fR 4
5830 .IX Item "pad_findmy_pvs"
5831 .ie n .IP """pad_findmy_sv""" 4
5832 .el .IP \f(CWpad_findmy_sv\fR 4
5833 .IX Xref "pad_findmy_pv pad_findmy_pvn pad_findmy_pvs pad_findmy_sv"
5834 .IX Item "pad_findmy_sv"
5835 .PD
5836 Given the name of a lexical variable, including its leading sigil, find its
5837 position in the currently\-compiling pad.
5838 .Sp
5839 If it is not in the current pad but appears in the pad of any lexically
5840 enclosing scope, then a pseudo\-entry for it is added in the current pad.
5841 .Sp
5842 These each return the offset in the current pad, or \f(CW\*(C`NOT_IN_PAD\*(C'\fR if no such
5843 lexical is in scope.
5844 .Sp
5845 The forms differ only in how the variable\*(Aqs name is specified.
5846 .Sp
5847 In \f(CW\*(C`pad_findmy_pvs\*(C'\fR, the variable name is a C language string literal,
5848 enclosed in double quotes.
5849 .Sp
5850 In plain \f(CW\*(C`pad_findmy_pv\*(C'\fR, the variable name is a C language NUL\-terminated
5851 string.
5852 .Sp
5853 In \f(CW\*(C`pad_findmy_pvn\*(C'\fR, \f(CW\*(C`len\*(C'\fR gives the length of the variable name in bytes,
5854 so it may contain embedded\-NUL characters. The caller must make sure \f(CW\*(C`namepv\*(C'\fR
5855 contains at least \f(CW\*(C`len\*(C'\fR bytes.
5856 .Sp
5857 In \f(CW\*(C`pad_findmy_sv\*(C'\fR, the variable name is taken from the SV parameter using
5858 \&\f(CW\*(C`"SvPVutf8"()\*(C'\fR.
5859 .Sp
5860 \&\f(CW\*(C`flags\*(C'\fR is reserved and must be zero.
5861 .RS 4
5862 .Sp
5863 .Vb 9
5864 \& PADOFFSET pad_findmy_pv ( const char *name, U32 flags)
5865 \& PADOFFSET Perl_pad_findmy_pv (pTHX_ const char *name, U32 flags)
5866 \& PADOFFSET pad_findmy_pvn( const char *namepv,
5867 \& STRLEN namelen, U32 flags)
5868 \& PADOFFSET Perl_pad_findmy_pvn(pTHX_ const char *namepv,
5869 \& STRLEN namelen, U32 flags)
5870 \& PADOFFSET pad_findmy_pvs( "name", U32 flags)
5871 \& PADOFFSET pad_findmy_sv ( SV *name, U32 flags)
5872 \& PADOFFSET Perl_pad_findmy_sv (pTHX_ SV *name, U32 flags)
5873 .Ve
5874 .RE
5875 .RS 4
5876 .RE
5877 .ie n .IP """pad_tidy""" 4
5878 .el .IP \f(CWpad_tidy\fR 4
5879 .IX Xref "pad_tidy"
5880 .IX Item "pad_tidy"
5881 NOTE: \f(CW\*(C`pad_tidy\*(C'\fR is \fBexperimental\fR and may change or be
5882 removed without notice.
5883 .Sp
5884 Tidy up a pad at the end of compilation of the code to which it belongs.
5885 Jobs performed here are: remove most stuff from the pads of anonsub
5886 prototypes; give it a \f(CW@_\fR; mark temporaries as such. \f(CW\*(C`type\*(C'\fR indicates
5887 the kind of subroutine:
5888 .Sp
5889 .Vb 3
5890 \& padtidy_SUB ordinary subroutine
5891 \& padtidy_SUBCLONE prototype for lexical closure
5892 \& padtidy_FORMAT format
5893 .Ve
5894 .RS 4
5895 .Sp
5896 .Vb 2
5897 \& void pad_tidy( padtidy_type type)
5898 \& void Perl_pad_tidy(pTHX_ padtidy_type type)
5899 .Ve
5900 .RE
5901 .RS 4
5902 .RE
5903 .ie n .IP """padnamelist_fetch""" 4
5904 .el .IP \f(CWpadnamelist_fetch\fR 4
5905 .IX Xref "padnamelist_fetch"
5906 .IX Item "padnamelist_fetch"
5907 NOTE: \f(CW\*(C`padnamelist_fetch\*(C'\fR is \fBexperimental\fR and may change or be
5908 removed without notice.
5909 .Sp
5910 Fetches the pad name from the given index.
5911 .RS 4
5912 .Sp
5913 .Vb 2
5914 \& PADNAME * padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
5915 \& PADNAME * Perl_padnamelist_fetch(PADNAMELIST *pnl, SSize_t key)
5916 .Ve
5917 .RE
5918 .RS 4
5919 .RE
5920 .ie n .IP """padnamelist_store""" 4
5921 .el .IP \f(CWpadnamelist_store\fR 4
5922 .IX Xref "padnamelist_store"
5923 .IX Item "padnamelist_store"
5924 NOTE: \f(CW\*(C`padnamelist_store\*(C'\fR is \fBexperimental\fR and may change or be
5925 removed without notice.
5926 .Sp
5927 Stores the pad name (which may be null) at the given index, freeing any
5928 existing pad name in that slot.
5929 .RS 4
5930 .Sp
5931 .Vb 6
5932 \& PADNAME ** padnamelist_store( PADNAMELIST *pnl,
5933 \& SSize_t key,
5934 \& PADNAME *val)
5935 \& PADNAME ** Perl_padnamelist_store(pTHX_ PADNAMELIST *pnl,
5936 \& SSize_t key,
5937 \& PADNAME *val)
5938 .Ve
5939 .RE
5940 .RS 4
5941 .RE
5942 .ie n .IP """perl_alloc""" 4
5943 .el .IP \f(CWperl_alloc\fR 4
5944 .IX Xref "perl_alloc"
5945 .IX Item "perl_alloc"
5946 Allocates a new Perl interpreter. See perlembed.
5947 .RS 4
5948 .Sp
5949 .Vb 1
5950 \& PerlInterpreter * perl_alloc()
5951 .Ve
5952 .RE
5953 .RS 4
5954 .RE
5955 .ie n .IP """PERL_ASYNC_CHECK""" 4
5956 .el .IP \f(CWPERL_ASYNC_CHECK\fR 4
5957 .IX Item "PERL_ASYNC_CHECK"
5958 Described in perlinterp.
5959 .RS 4
5960 .Sp
5961 .Vb 1
5962 \& void PERL_ASYNC_CHECK()
5963 .Ve
5964 .RE
5965 .RS 4
5966 .RE
5967 .ie n .IP """perl_clone""" 4
5968 .el .IP \f(CWperl_clone\fR 4
5969 .IX Xref "perl_clone"
5970 .IX Item "perl_clone"
5971 Create and return a new interpreter by cloning the current one.
5972 .Sp
5973 \&\f(CW\*(C`perl_clone\*(C'\fR takes these flags as parameters:
5974 .Sp
5975 \&\f(CW\*(C`CLONEf_COPY_STACKS\*(C'\fR \- is used to, well, copy the stacks also,
5976 without it we only clone the data and zero the stacks,
5977 with it we copy the stacks and the new perl interpreter is
5978 ready to run at the exact same point as the previous one.
5979 The pseudo\-fork code uses \f(CW\*(C`COPY_STACKS\*(C'\fR while the
5980 threads\->create doesn\*(Aqt.
5981 .Sp
5982 \&\f(CW\*(C`CLONEf_KEEP_PTR_TABLE\*(C'\fR \-
5983 \&\f(CW\*(C`perl_clone\*(C'\fR keeps a ptr_table with the pointer of the old
5984 variable as a key and the new variable as a value,
5985 this allows it to check if something has been cloned and not
5986 clone it again, but rather just use the value and increase the
5987 refcount.
5988 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
5989 using the function \f(CW\*(C`ptr_table_free(PL_ptr_table);\ PL_ptr_table\ =\ NULL;\*(C'\fR.
5990 A reason to keep it around is if you want to dup some of your own
5991 variables which are outside the graph that perl scans.
5992 .Sp
5993 \&\f(CW\*(C`CLONEf_CLONE_HOST\*(C'\fR \-
5994 This is a win32 thing, it is ignored on unix, it tells perl\*(Aqs
5995 win32host code (which is c++) to clone itself, this is needed on
5996 win32 if you want to run two threads at the same time,
5997 if you just want to do some stuff in a separate perl interpreter
5998 and then throw it away and return to the original one,
5999 you don\*(Aqt need to do anything.
6000 .RS 4
6001 .Sp
6002 .Vb 2
6003 \& PerlInterpreter * perl_clone(PerlInterpreter *proto_perl,
6004 \& UV flags)
6005 .Ve
6006 .RE
6007 .RS 4
6008 .RE
6009 .ie n .IP """perl_construct""" 4
6010 .el .IP \f(CWperl_construct\fR 4
6011 .IX Xref "perl_construct"
6012 .IX Item "perl_construct"
6013 Initializes a new Perl interpreter. See perlembed.
6014 .RS 4
6015 .Sp
6016 .Vb 1
6017 \& void perl_construct(PerlInterpreter *my_perl)
6018 .Ve
6019 .RE
6020 .RS 4
6021 .RE
6022 .ie n .IP """perl_destruct""" 4
6023 .el .IP \f(CWperl_destruct\fR 4
6024 .IX Xref "perl_destruct"
6025 .IX Item "perl_destruct"
6026 Shuts down a Perl interpreter. See perlembed for a tutorial.
6027 .Sp
6028 \&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter. It must have been previously
6029 created through the use of "perl_alloc" and "perl_construct". It may
6030 have been initialised through "perl_parse", and may have been used
6031 through "perl_run" and other means. This function should be called for
6032 any Perl interpreter that has been constructed with "perl_construct",
6033 even if subsequent operations on it failed, for example if "perl_parse"
6034 returned a non\-zero value.
6035 .Sp
6036 If the interpreter\*(Aqs \f(CW\*(C`PL_exit_flags\*(C'\fR word has the
6037 \&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function will execute code
6038 in \f(CW\*(C`END\*(C'\fR blocks before performing the rest of destruction. If it is
6039 desired to make any use of the interpreter between "perl_parse" and
6040 "perl_destruct" other than just calling "perl_run", then this flag
6041 should be set early on. This matters if "perl_run" will not be called,
6042 or if anything else will be done in addition to calling "perl_run".
6043 .Sp
6044 Returns a value be a suitable value to pass to the C library function
6045 \&\f(CW\*(C`exit\*(C'\fR (or to return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating
6046 the nature of the way the interpreter terminated. This takes into account
6047 any failure of "perl_parse" and any early exit from "perl_run".
6048 The exit code is of the type required by the host operating system,
6049 so because of differing exit code conventions it is not portable to
6050 interpret specific numeric values as having specific meanings.
6051 .RS 4
6052 .Sp
6053 .Vb 1
6054 \& int perl_destruct(PerlInterpreter *my_perl)
6055 .Ve
6056 .RE
6057 .RS 4
6058 .RE
6059 .ie n .IP """perl_free""" 4
6060 .el .IP \f(CWperl_free\fR 4
6061 .IX Xref "perl_free"
6062 .IX Item "perl_free"
6063 Releases a Perl interpreter. See perlembed.
6064 .RS 4
6065 .Sp
6066 .Vb 1
6067 \& void perl_free(PerlInterpreter *my_perl)
6068 .Ve
6069 .RE
6070 .RS 4
6071 .RE
6072 .ie n .IP """PERL_GET_CONTEXT""" 4
6073 .el .IP \f(CWPERL_GET_CONTEXT\fR 4
6074 .IX Item "PERL_GET_CONTEXT"
6075 Described in perlguts.
6076 .RS 4
6077 .Sp
6078 .Vb 1
6079 \& PerlInterpreter* PERL_GET_CONTEXT
6080 .Ve
6081 .RE
6082 .RS 4
6083 .RE
6084 .ie n .IP """perl_parse""" 4
6085 .el .IP \f(CWperl_parse\fR 4
6086 .IX Xref "perl_parse"
6087 .IX Item "perl_parse"
6088 Tells a Perl interpreter to parse a Perl script. This performs most
6089 of the initialisation of a Perl interpreter. See perlembed for
6090 a tutorial.
6091 .Sp
6092 \&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter that is to parse the script.
6093 It must have been previously created through the use of "perl_alloc"
6094 and "perl_construct". \f(CW\*(C`xsinit\*(C'\fR points to a callback function that
6095 will be called to set up the ability for this Perl interpreter to load
6096 XS extensions, or may be null to perform no such setup.
6097 .Sp
6098 \&\f(CW\*(C`argc\*(C'\fR and \f(CW\*(C`argv\*(C'\fR supply a set of command\-line arguments to the Perl
6099 interpreter, as would normally be passed to the \f(CW\*(C`main\*(C'\fR function of
6100 a C program. \f(CW\*(C`argv[argc]\*(C'\fR must be null. These arguments are where
6101 the script to parse is specified, either by naming a script file or by
6102 providing a script in a \f(CW\*(C`\-e\*(C'\fR option.
6103 If \f(CW$0\fR will be written to in the Perl interpreter, then
6104 the argument strings must be in writable memory, and so mustn\*(Aqt just be
6105 string constants.
6106 .Sp
6107 \&\f(CW\*(C`env\*(C'\fR specifies a set of environment variables that will be used by
6108 this Perl interpreter. If non\-null, it must point to a null\-terminated
6109 array of environment strings. If null, the Perl interpreter will use
6110 the environment supplied by the \f(CW\*(C`environ\*(C'\fR global variable.
6111 .Sp
6112 This function initialises the interpreter, and parses and compiles the
6113 script specified by the command\-line arguments. This includes executing
6114 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
6115 \&\f(CW\*(C`INIT\*(C'\fR blocks or the main program.
6116 .Sp
6117 Returns an integer of slightly tricky interpretation. The correct
6118 use of the return value is as a truth value indicating whether there
6119 was a failure in initialisation. If zero is returned, this indicates
6120 that initialisation was successful, and it is safe to proceed to call
6121 "perl_run" and make other use of it. If a non\-zero value is returned,
6122 this indicates some problem that means the interpreter wants to terminate.
6123 The interpreter should not be just abandoned upon such failure; the caller
6124 should proceed to shut the interpreter down cleanly with "perl_destruct"
6125 and free it with "perl_free".
6126 .Sp
6127 For historical reasons, the non\-zero return value also attempts to
6128 be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to
6129 return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature
6130 of the way initialisation terminated. However, this isn\*(Aqt portable,
6131 due to differing exit code conventions. An attempt is made to return
6132 an exit code of the type required by the host operating system, but
6133 because it is constrained to be non\-zero, it is not necessarily possible
6134 to indicate every type of exit. It is only reliable on Unix, where a
6135 zero exit code can be augmented with a set bit that will be ignored.
6136 In any case, this function is not the correct place to acquire an exit
6137 code: one should get that from "perl_destruct".
6138 .RS 4
6139 .Sp
6140 .Vb 2
6141 \& int perl_parse(PerlInterpreter *my_perl, XSINIT_t xsinit,
6142 \& int argc, char **argv, char **env)
6143 .Ve
6144 .RE
6145 .RS 4
6146 .RE
6147 .ie n .IP """perl_run""" 4
6148 .el .IP \f(CWperl_run\fR 4
6149 .IX Xref "perl_run"
6150 .IX Item "perl_run"
6151 Tells a Perl interpreter to run its main program. See perlembed
6152 for a tutorial.
6153 .Sp
6154 \&\f(CW\*(C`my_perl\*(C'\fR points to the Perl interpreter. It must have been previously
6155 created through the use of "perl_alloc" and "perl_construct", and
6156 initialised through "perl_parse". This function should not be called
6157 if "perl_parse" returned a non\-zero value, indicating a failure in
6158 initialisation or compilation.
6159 .Sp
6160 This function executes code in \f(CW\*(C`INIT\*(C'\fR blocks, and then executes the
6161 main program. The code to be executed is that established by the prior
6162 call to "perl_parse". If the interpreter\*(Aqs \f(CW\*(C`PL_exit_flags\*(C'\fR word
6163 does not have the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag set, then this function
6164 will also execute code in \f(CW\*(C`END\*(C'\fR blocks. If it is desired to make any
6165 further use of the interpreter after calling this function, then \f(CW\*(C`END\*(C'\fR
6166 blocks should be postponed to "perl_destruct" time by setting that flag.
6167 .Sp
6168 Returns an integer of slightly tricky interpretation. The correct use
6169 of the return value is as a truth value indicating whether the program
6170 terminated non\-locally. If zero is returned, this indicates that
6171 the program ran to completion, and it is safe to make other use of the
6172 interpreter (provided that the \f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR flag was set as
6173 described above). If a non\-zero value is returned, this indicates that
6174 the interpreter wants to terminate early. The interpreter should not be
6175 just abandoned because of this desire to terminate; the caller should
6176 proceed to shut the interpreter down cleanly with "perl_destruct"
6177 and free it with "perl_free".
6178 .Sp
6179 For historical reasons, the non\-zero return value also attempts to
6180 be a suitable value to pass to the C library function \f(CW\*(C`exit\*(C'\fR (or to
6181 return from \f(CW\*(C`main\*(C'\fR), to serve as an exit code indicating the nature of
6182 the way the program terminated. However, this isn\*(Aqt portable, due to
6183 differing exit code conventions. An attempt is made to return an exit
6184 code of the type required by the host operating system, but because
6185 it is constrained to be non\-zero, it is not necessarily possible to
6186 indicate every type of exit. It is only reliable on Unix, where a zero
6187 exit code can be augmented with a set bit that will be ignored. In any
6188 case, this function is not the correct place to acquire an exit code:
6189 one should get that from "perl_destruct".
6190 .RS 4
6191 .Sp
6192 .Vb 1
6193 \& int perl_run(PerlInterpreter *my_perl)
6194 .Ve
6195 .RE
6196 .RS 4
6197 .RE
6198 .ie n .IP """PERL_SET_CONTEXT""" 4
6199 .el .IP \f(CWPERL_SET_CONTEXT\fR 4
6200 .IX Item "PERL_SET_CONTEXT"
6201 Described in perlguts.
6202 .RS 4
6203 .Sp
6204 .Vb 1
6205 \& void PERL_SET_CONTEXT(PerlInterpreter* i)
6206 .Ve
6207 .RE
6208 .RS 4
6209 .RE
6210 .ie n .IP """PERL_SYS_INIT""" 4
6211 .el .IP \f(CWPERL_SYS_INIT\fR 4
6212 .IX Item "PERL_SYS_INIT"
6213 .PD 0
6214 .ie n .IP """PERL_SYS_INIT3""" 4
6215 .el .IP \f(CWPERL_SYS_INIT3\fR 4
6216 .IX Xref "PERL_SYS_INIT PERL_SYS_INIT3"
6217 .IX Item "PERL_SYS_INIT3"
6218 .PD
6219 These provide system\-specific tune up of the C runtime environment necessary to
6220 run Perl interpreters. Only one should be used, and it should be called only
6221 once, before creating any Perl interpreters.
6222 .Sp
6223 They differ in that \f(CW\*(C`PERL_SYS_INIT3\*(C'\fR also initializes \f(CW\*(C`env\*(C'\fR.
6224 .RS 4
6225 .Sp
6226 .Vb 2
6227 \& void PERL_SYS_INIT (int *argc, char*** argv)
6228 \& void PERL_SYS_INIT3(int *argc, char*** argv, char*** env)
6229 .Ve
6230 .RE
6231 .RS 4
6232 .RE
6233 .ie n .IP """PERL_SYS_TERM""" 4
6234 .el .IP \f(CWPERL_SYS_TERM\fR 4
6235 .IX Xref "PERL_SYS_TERM"
6236 .IX Item "PERL_SYS_TERM"
6237 Provides system\-specific clean up of the C runtime environment after
6238 running Perl interpreters. This should be called only once, after
6239 freeing any remaining Perl interpreters.
6240 .RS 4
6241 .Sp
6242 .Vb 1
6243 \& void PERL_SYS_TERM()
6244 .Ve
6245 .RE
6246 .RS 4
6247 .RE
6248 .ie n .IP """PerlInterpreter""" 4
6249 .el .IP \f(CWPerlInterpreter\fR 4
6250 .IX Item "PerlInterpreter"
6251 Described in perlembed.
6252 .ie n .IP """PL_exit_flags""" 4
6253 .el .IP \f(CWPL_exit_flags\fR 4
6254 .IX Xref "PL_exit_flags"
6255 .IX Item "PL_exit_flags"
6256 Contains flags controlling perl\*(Aqs behaviour on \fBexit()\fR:
6257 .RS 4
6258 .IP \(bu 4
6259 \&\f(CW\*(C`PERL_EXIT_DESTRUCT_END\*(C'\fR
6260 .Sp
6261 If set, END blocks are executed when the interpreter is destroyed.
6262 This is normally set by perl itself after the interpreter is
6263 constructed.
6264 .IP \(bu 4
6265 \&\f(CW\*(C`PERL_EXIT_ABORT\*(C'\fR
6266 .Sp
6267 Call \f(CWabort()\fR on exit. This is used internally by perl itself to
6268 abort if exit is called while processing exit.
6269 .IP \(bu 4
6270 \&\f(CW\*(C`PERL_EXIT_WARN\*(C'\fR
6271 .Sp
6272 Warn on exit.
6273 .IP \(bu 4
6274 \&\f(CW\*(C`PERL_EXIT_EXPECTED\*(C'\fR
6275 .Sp
6276 Set by the "exit" in perlfunc operator.
6277 .RE
6278 .RS 4
6279 .Sp
6280 .Vb 1
6281 \& U8 PL_exit_flags
6282 .Ve
6283 .RE
6284 .RS 4
6285 .RE
6286 .ie n .IP """PL_origalen""" 4
6287 .el .IP \f(CWPL_origalen\fR 4
6288 .IX Item "PL_origalen"
6289 Described in perlembed.
6290 .ie n .IP """PL_perl_destruct_level""" 4
6291 .el .IP \f(CWPL_perl_destruct_level\fR 4
6292 .IX Xref "PL_perl_destruct_level"
6293 .IX Item "PL_perl_destruct_level"
6294 This value may be set when embedding for full cleanup.
6295 .Sp
6296 Possible values:
6297 .RS 4
6298 .IP \(bu 4
6299 0 \- none
6300 .IP \(bu 4
6301 1 \- full
6302 .IP \(bu 4
6303 2 or greater \- full with checks.
6304 .RE
6305 .RS 4
6306 .Sp
6307 If \f(CW$ENV{PERL_DESTRUCT_LEVEL}\fR is set to an integer greater than the
6308 value of \f(CW\*(C`PL_perl_destruct_level\*(C'\fR its value is used instead.
6309 .Sp
6310 On threaded perls, each thread has an independent copy of this variable;
6311 each initialized at creation time with the current value of the creating
6312 thread\*(Aqs copy.
6313 .Sp
6314 .Vb 1
6315 \& signed char PL_perl_destruct_level
6316 .Ve
6317 .RE
6318 .RS 4
6319 .RE
6320 .ie n .IP """ptr_table_fetch""" 4
6321 .el .IP \f(CWptr_table_fetch\fR 4
6322 .IX Xref "ptr_table_fetch"
6323 .IX Item "ptr_table_fetch"
6324 Look for \f(CW\*(C`sv\*(C'\fR in the pointer\-mapping table \f(CW\*(C`tbl\*(C'\fR, returning its value, or
6325 NULL if not found.
6326 .RS 4
6327 .Sp
6328 .Vb 4
6329 \& void * ptr_table_fetch( PTR_TBL_t * const tbl,
6330 \& const void * const sv)
6331 \& void * Perl_ptr_table_fetch(pTHX_ PTR_TBL_t * const tbl,
6332 \& const void * const sv)
6333 .Ve
6334 .RE
6335 .RS 4
6336 .RE
6337 .ie n .IP """ptr_table_free""" 4
6338 .el .IP \f(CWptr_table_free\fR 4
6339 .IX Xref "ptr_table_free"
6340 .IX Item "ptr_table_free"
6341 Clear and free a ptr table
6342 .RS 4
6343 .Sp
6344 .Vb 2
6345 \& void ptr_table_free( PTR_TBL_t * const tbl)
6346 \& void Perl_ptr_table_free(pTHX_ PTR_TBL_t * const tbl)
6347 .Ve
6348 .RE
6349 .RS 4
6350 .RE
6351 .ie n .IP """ptr_table_new""" 4
6352 .el .IP \f(CWptr_table_new\fR 4
6353 .IX Xref "ptr_table_new"
6354 .IX Item "ptr_table_new"
6355 Create a new pointer\-mapping table
6356 .RS 4
6357 .Sp
6358 .Vb 2
6359 \& PTR_TBL_t * ptr_table_new()
6360 \& PTR_TBL_t * Perl_ptr_table_new(pTHX)
6361 .Ve
6362 .RE
6363 .RS 4
6364 .RE
6365 .ie n .IP """ptr_table_split""" 4
6366 .el .IP \f(CWptr_table_split\fR 4
6367 .IX Xref "ptr_table_split"
6368 .IX Item "ptr_table_split"
6369 Double the hash bucket size of an existing ptr table
6370 .RS 4
6371 .Sp
6372 .Vb 2
6373 \& void ptr_table_split( PTR_TBL_t * const tbl)
6374 \& void Perl_ptr_table_split(pTHX_ PTR_TBL_t * const tbl)
6375 .Ve
6376 .RE
6377 .RS 4
6378 .RE
6379 .ie n .IP """ptr_table_store""" 4
6380 .el .IP \f(CWptr_table_store\fR 4
6381 .IX Xref "ptr_table_store"
6382 .IX Item "ptr_table_store"
6383 Add a new entry to a pointer\-mapping table \f(CW\*(C`tbl\*(C'\fR.
6384 In hash terms, \f(CW\*(C`oldsv\*(C'\fR is the key; Cnewsv> is the value.
6385 .Sp
6386 The names "old" and "new" are specific to the core\*(Aqs typical use of ptr_tables
6387 in thread cloning.
6388 .RS 4
6389 .Sp
6390 .Vb 6
6391 \& void ptr_table_store( PTR_TBL_t * const tbl,
6392 \& const void * const oldsv,
6393 \& void * const newsv)
6394 \& void Perl_ptr_table_store(pTHX_ PTR_TBL_t * const tbl,
6395 \& const void * const oldsv,
6396 \& void * const newsv)
6397 .Ve
6398 .RE
6399 .RS 4
6400 .RE
6401 .ie n .IP """require_pv""" 4
6402 .el .IP \f(CWrequire_pv\fR 4
6403 .IX Xref "require_pv"
6404 .IX Item "require_pv"
6405 Tells Perl to \f(CW\*(C`require\*(C'\fR the file named by the string argument. It is
6406 analogous to the Perl code \f(CW\*(C`eval "require \*(Aq$file\*(Aq"\*(C'\fR. It\*(Aqs even
6407 implemented that way; consider using load_module instead.
6408 .Sp
6409 NOTE: the \f(CWperl_require_pv()\fR form is \fBdeprecated\fR.
6410 .RS 4
6411 .Sp
6412 .Vb 2
6413 \& void require_pv( const char *pv)
6414 \& void Perl_require_pv(pTHX_ const char *pv)
6415 .Ve
6416 .RE
6417 .RS 4
6418 .RE
6419 .ie n .IP """vload_module""" 4
6420 .el .IP \f(CWvload_module\fR 4
6421 .IX Xref "vload_module"
6422 .IX Item "vload_module"
6423 Like \f(CW"load_module"\fR but the arguments are an encapsulated argument list.
6424 .RS 4
6425 .Sp
6426 .Vb 4
6427 \& void vload_module( U32 flags, SV *name, SV *ver,
6428 \& va_list *args)
6429 \& void Perl_vload_module(pTHX_ U32 flags, SV *name, SV *ver,
6430 \& va_list *args)
6431 .Ve
6432 .RE
6433 .RS 4
6434 .RE
6435 .SH Errno
6436 .IX Header "Errno"
6437 .ie n .IP """sv_string_from_errnum""" 4
6438 .el .IP \f(CWsv_string_from_errnum\fR 4
6439 .IX Xref "sv_string_from_errnum"
6440 .IX Item "sv_string_from_errnum"
6441 Generates the message string describing an OS error and returns it as
6442 an SV. \f(CW\*(C`errnum\*(C'\fR must be a value that \f(CW\*(C`errno\*(C'\fR could take, identifying
6443 the type of error.
6444 .Sp
6445 If \f(CW\*(C`tgtsv\*(C'\fR is non\-null then the string will be written into that SV
6446 (overwriting existing content) and it will be returned. If \f(CW\*(C`tgtsv\*(C'\fR
6447 is a null pointer then the string will be written into a new mortal SV
6448 which will be returned.
6449 .Sp
6450 The message will be taken from whatever locale would be used by \f(CW$!\fR,
6451 and will be encoded in the SV in whatever manner would be used by \f(CW$!\fR.
6452 The details of this process are subject to future change. Currently,
6453 the message is taken from the C locale by default (usually producing an
6454 English message), and from the currently selected locale when in the scope
6455 of the \f(CW\*(C`use locale\*(C'\fR pragma. A heuristic attempt is made to decode the
6456 message from the locale\*(Aqs character encoding, but it will only be decoded
6457 as either UTF\-8 or ISO\-8859\-1. It is always correctly decoded in a UTF\-8
6458 locale, usually in an ISO\-8859\-1 locale, and never in any other locale.
6459 .Sp
6460 The SV is always returned containing an actual string, and with no other
6461 OK bits set. Unlike \f(CW$!\fR, a message is even yielded for \f(CW\*(C`errnum\*(C'\fR zero
6462 (meaning success), and if no useful message is available then a useless
6463 string (currently empty) is returned.
6464 .RS 4
6465 .Sp
6466 .Vb 2
6467 \& SV * sv_string_from_errnum( int errnum, SV *tgtsv)
6468 \& SV * Perl_sv_string_from_errnum(pTHX_ int errnum, SV *tgtsv)
6469 .Ve
6470 .RE
6471 .RS 4
6472 .RE
6473 .SH "Exception Handling (simple) Macros"
6474 .IX Header "Exception Handling (simple) Macros"
6475 .ie n .IP """dXCPT""" 4
6476 .el .IP \f(CWdXCPT\fR 4
6477 .IX Xref "dXCPT"
6478 .IX Item "dXCPT"
6479 Set up necessary local variables for exception handling.
6480 See "Exception Handling" in perlguts.
6481 .RS 4
6482 .Sp
6483 .Vb 1
6484 \& dXCPT;
6485 .Ve
6486 .RE
6487 .RS 4
6488 .RE
6489 .ie n .IP """JMPENV_JUMP""" 4
6490 .el .IP \f(CWJMPENV_JUMP\fR 4
6491 .IX Item "JMPENV_JUMP"
6492 .PD 0
6493 .ie n .IP """JMPENV_PUSH""" 4
6494 .el .IP \f(CWJMPENV_PUSH\fR 4
6495 .IX Item "JMPENV_PUSH"
6496 .ie n .IP """PL_restartop""" 4
6497 .el .IP \f(CWPL_restartop\fR 4
6498 .IX Item "PL_restartop"
6499 .PD
6500 Described in perlinterp.
6501 .RS 4
6502 .Sp
6503 .Vb 3
6504 \& void JMPENV_JUMP (int v)
6505 \& void JMPENV_PUSH (int v)
6506 \& OP * PL_restartop
6507 .Ve
6508 .RE
6509 .RS 4
6510 .RE
6511 .ie n .IP """XCPT_CATCH""" 4
6512 .el .IP \f(CWXCPT_CATCH\fR 4
6513 .IX Xref "XCPT_CATCH"
6514 .IX Item "XCPT_CATCH"
6515 Introduces a catch block. See "Exception Handling" in perlguts.
6516 .ie n .IP """XCPT_RETHROW""" 4
6517 .el .IP \f(CWXCPT_RETHROW\fR 4
6518 .IX Xref "XCPT_RETHROW"
6519 .IX Item "XCPT_RETHROW"
6520 Rethrows a previously caught exception. See "Exception Handling" in perlguts.
6521 .RS 4
6522 .Sp
6523 .Vb 1
6524 \& XCPT_RETHROW;
6525 .Ve
6526 .RE
6527 .RS 4
6528 .RE
6529 .ie n .IP """XCPT_TRY_END""" 4
6530 .el .IP \f(CWXCPT_TRY_END\fR 4
6531 .IX Xref "XCPT_TRY_END"
6532 .IX Item "XCPT_TRY_END"
6533 Ends a try block. See "Exception Handling" in perlguts.
6534 .ie n .IP """XCPT_TRY_START""" 4
6535 .el .IP \f(CWXCPT_TRY_START\fR 4
6536 .IX Xref "XCPT_TRY_START"
6537 .IX Item "XCPT_TRY_START"
6538 Starts a try block. See "Exception Handling" in perlguts.
6539 .SH "Filesystem configuration values"
6540 .IX Header "Filesystem configuration values"
6541 Also see "List of capability HAS_foo symbols".
6542 .ie n .IP """DIRNAMLEN""" 4
6543 .el .IP \f(CWDIRNAMLEN\fR 4
6544 .IX Xref "DIRNAMLEN"
6545 .IX Item "DIRNAMLEN"
6546 This symbol, if defined, indicates to the C program that the length
6547 of directory entry names is provided by a \f(CW\*(C`d_namlen\*(C'\fR field. Otherwise
6548 you need to do \f(CWstrlen()\fR on the \f(CW\*(C`d_name\*(C'\fR field.
6549 .ie n .IP """DOSUID""" 4
6550 .el .IP \f(CWDOSUID\fR 4
6551 .IX Xref "DOSUID"
6552 .IX Item "DOSUID"
6553 This symbol, if defined, indicates that the C program should
6554 check the script that it is executing for setuid/setgid bits, and
6555 attempt to emulate setuid/setgid on systems that have disabled
6556 setuid #! scripts because the kernel can\*(Aqt do it securely.
6557 It is up to the package designer to make sure that this emulation
6558 is done securely. Among other things, it should do an fstat on
6559 the script it just opened to make sure it really is a setuid/setgid
6560 script, it should make sure the arguments passed correspond exactly
6561 to the argument on the #! line, and it should not trust any
6562 subprocesses to which it must pass the filename rather than the
6563 file descriptor of the script to be executed.
6564 .ie n .IP """EOF_NONBLOCK""" 4
6565 .el .IP \f(CWEOF_NONBLOCK\fR 4
6566 .IX Xref "EOF_NONBLOCK"
6567 .IX Item "EOF_NONBLOCK"
6568 This symbol, if defined, indicates to the C program that a \f(CWread()\fR on
6569 a non\-blocking file descriptor will return 0 on \f(CW\*(C`EOF\*(C'\fR, and not the value
6570 held in \f(CW\*(C`RD_NODATA\*(C'\fR (\-1 usually, in that case!).
6571 .ie n .IP """FCNTL_CAN_LOCK""" 4
6572 .el .IP \f(CWFCNTL_CAN_LOCK\fR 4
6573 .IX Xref "FCNTL_CAN_LOCK"
6574 .IX Item "FCNTL_CAN_LOCK"
6575 This symbol, if defined, indicates that \f(CWfcntl()\fR can be used
6576 for file locking. Normally on Unix systems this is defined.
6577 It may be undefined on \f(CW\*(C`VMS\*(C'\fR.
6578 .ie n .IP """FFLUSH_ALL""" 4
6579 .el .IP \f(CWFFLUSH_ALL\fR 4
6580 .IX Xref "FFLUSH_ALL"
6581 .IX Item "FFLUSH_ALL"
6582 This symbol, if defined, tells that to flush
6583 all pending stdio output one must loop through all
6584 the stdio file handles stored in an array and fflush them.
6585 Note that if \f(CW\*(C`fflushNULL\*(C'\fR is defined, fflushall will not
6586 even be probed for and will be left undefined.
6587 .ie n .IP """FFLUSH_NULL""" 4
6588 .el .IP \f(CWFFLUSH_NULL\fR 4
6589 .IX Xref "FFLUSH_NULL"
6590 .IX Item "FFLUSH_NULL"
6591 This symbol, if defined, tells that \f(CWfflush(NULL)\fR correctly
6592 flushes all pending stdio output without side effects. In
6593 particular, on some platforms calling \f(CWfflush(NULL)\fR *still*
6594 corrupts \f(CW\*(C`STDIN\*(C'\fR if it is a pipe.
6595 .ie n .IP """FILE_base""" 4
6596 .el .IP \f(CWFILE_base\fR 4
6597 .IX Xref "FILE_base"
6598 .IX Item "FILE_base"
6599 This macro is used to access the \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the
6600 \&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
6601 defined if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined.
6602 .RS 4
6603 .Sp
6604 .Vb 1
6605 \& void * FILE_base(FILE * f)
6606 .Ve
6607 .RE
6608 .RS 4
6609 .RE
6610 .ie n .IP """FILE_bufsiz""" 4
6611 .el .IP \f(CWFILE_bufsiz\fR 4
6612 .IX Xref "FILE_bufsiz"
6613 .IX Item "FILE_bufsiz"
6614 This macro is used to determine the number of bytes in the I/O
6615 buffer pointed to by \f(CW\*(C`_base\*(C'\fR field (or equivalent) of the \f(CW\*(C`FILE\*(C'\fR
6616 structure pointed to its argument. This macro will always be defined
6617 if \f(CW\*(C`USE_STDIO_BASE\*(C'\fR is defined.
6618 .RS 4
6619 .Sp
6620 .Vb 1
6621 \& Size_t FILE_bufsiz(FILE *f)
6622 .Ve
6623 .RE
6624 .RS 4
6625 .RE
6626 .ie n .IP """FILE_cnt""" 4
6627 .el .IP \f(CWFILE_cnt\fR 4
6628 .IX Xref "FILE_cnt"
6629 .IX Item "FILE_cnt"
6630 This macro is used to access the \f(CW\*(C`_cnt\*(C'\fR field (or equivalent) of the
6631 \&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
6632 defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined.
6633 .RS 4
6634 .Sp
6635 .Vb 1
6636 \& Size_t FILE_cnt(FILE * f)
6637 .Ve
6638 .RE
6639 .RS 4
6640 .RE
6641 .ie n .IP """FILE_ptr""" 4
6642 .el .IP \f(CWFILE_ptr\fR 4
6643 .IX Xref "FILE_ptr"
6644 .IX Item "FILE_ptr"
6645 This macro is used to access the \f(CW\*(C`_ptr\*(C'\fR field (or equivalent) of the
6646 \&\f(CW\*(C`FILE\*(C'\fR structure pointed to by its argument. This macro will always be
6647 defined if \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is defined.
6648 .RS 4
6649 .Sp
6650 .Vb 1
6651 \& void * FILE_ptr(FILE * f)
6652 .Ve
6653 .RE
6654 .RS 4
6655 .RE
6656 .ie n .IP """FLEXFILENAMES""" 4
6657 .el .IP \f(CWFLEXFILENAMES\fR 4
6658 .IX Xref "FLEXFILENAMES"
6659 .IX Item "FLEXFILENAMES"
6660 This symbol, if defined, indicates that the system supports filenames
6661 longer than 14 characters.
6662 .ie n .IP """HAS_DIR_DD_FD""" 4
6663 .el .IP \f(CWHAS_DIR_DD_FD\fR 4
6664 .IX Xref "HAS_DIR_DD_FD"
6665 .IX Item "HAS_DIR_DD_FD"
6666 This symbol, if defined, indicates that the \f(CW\*(C`DIR\*(C'\fR* dirstream
6667 structure contains a member variable named \f(CW\*(C`dd_fd\*(C'\fR.
6668 .ie n .IP """HAS_DUP2""" 4
6669 .el .IP \f(CWHAS_DUP2\fR 4
6670 .IX Xref "HAS_DUP2"
6671 .IX Item "HAS_DUP2"
6672 This symbol, if defined, indicates that the \f(CW\*(C`dup2\*(C'\fR routine is
6673 available to duplicate file descriptors.
6674 .ie n .IP """HAS_DUP3""" 4
6675 .el .IP \f(CWHAS_DUP3\fR 4
6676 .IX Xref "HAS_DUP3"
6677 .IX Item "HAS_DUP3"
6678 This symbol, if defined, indicates that the \f(CW\*(C`dup3\*(C'\fR routine is
6679 available to duplicate file descriptors.
6680 .ie n .IP """HAS_FAST_STDIO""" 4
6681 .el .IP \f(CWHAS_FAST_STDIO\fR 4
6682 .IX Xref "HAS_FAST_STDIO"
6683 .IX Item "HAS_FAST_STDIO"
6684 This symbol, if defined, indicates that the "fast stdio"
6685 is available to manipulate the stdio buffers directly.
6686 .ie n .IP """HAS_FCHDIR""" 4
6687 .el .IP \f(CWHAS_FCHDIR\fR 4
6688 .IX Xref "HAS_FCHDIR"
6689 .IX Item "HAS_FCHDIR"
6690 This symbol, if defined, indicates that the \f(CW\*(C`fchdir\*(C'\fR routine is
6691 available to change directory using a file descriptor.
6692 .ie n .IP """HAS_FCNTL""" 4
6693 .el .IP \f(CWHAS_FCNTL\fR 4
6694 .IX Xref "HAS_FCNTL"
6695 .IX Item "HAS_FCNTL"
6696 This symbol, if defined, indicates to the C program that
6697 the \f(CWfcntl()\fR function exists.
6698 .ie n .IP """HAS_FDCLOSE""" 4
6699 .el .IP \f(CWHAS_FDCLOSE\fR 4
6700 .IX Xref "HAS_FDCLOSE"
6701 .IX Item "HAS_FDCLOSE"
6702 This symbol, if defined, indicates that the \f(CW\*(C`fdclose\*(C'\fR routine is
6703 available to free a \f(CW\*(C`FILE\*(C'\fR structure without closing the underlying
6704 file descriptor. This function appeared in \f(CW\*(C`FreeBSD\*(C'\fR 10.2.
6705 .ie n .IP """HAS_FDOPENDIR""" 4
6706 .el .IP \f(CWHAS_FDOPENDIR\fR 4
6707 .IX Xref "HAS_FDOPENDIR"
6708 .IX Item "HAS_FDOPENDIR"
6709 This symbol, if defined, indicates that the \f(CW\*(C`fdopendir\*(C'\fR routine is
6710 available to open a directory descriptor.
6711 .ie n .IP """HAS_FPATHCONF""" 4
6712 .el .IP \f(CWHAS_FPATHCONF\fR 4
6713 .IX Xref "HAS_FPATHCONF"
6714 .IX Item "HAS_FPATHCONF"
6715 This symbol, if defined, indicates that \f(CWpathconf()\fR is available
6716 to determine file\-system related limits and options associated
6717 with a given open file descriptor.
6718 .ie n .IP """HAS_FPOS64_T""" 4
6719 .el .IP \f(CWHAS_FPOS64_T\fR 4
6720 .IX Xref "HAS_FPOS64_T"
6721 .IX Item "HAS_FPOS64_T"
6722 This symbol will be defined if the C compiler supports \f(CW\*(C`fpos64_t\*(C'\fR.
6723 .ie n .IP """HAS_FSTATFS""" 4
6724 .el .IP \f(CWHAS_FSTATFS\fR 4
6725 .IX Xref "HAS_FSTATFS"
6726 .IX Item "HAS_FSTATFS"
6727 This symbol, if defined, indicates that the \f(CW\*(C`fstatfs\*(C'\fR routine is
6728 available to stat filesystems by file descriptors.
6729 .ie n .IP """HAS_FSTATVFS""" 4
6730 .el .IP \f(CWHAS_FSTATVFS\fR 4
6731 .IX Xref "HAS_FSTATVFS"
6732 .IX Item "HAS_FSTATVFS"
6733 This symbol, if defined, indicates that the \f(CW\*(C`fstatvfs\*(C'\fR routine is
6734 available to stat filesystems by file descriptors.
6735 .ie n .IP """HAS_GETFSSTAT""" 4
6736 .el .IP \f(CWHAS_GETFSSTAT\fR 4
6737 .IX Xref "HAS_GETFSSTAT"
6738 .IX Item "HAS_GETFSSTAT"
6739 This symbol, if defined, indicates that the \f(CW\*(C`getfsstat\*(C'\fR routine is
6740 available to stat filesystems in bulk.
6741 .ie n .IP """HAS_GETMNT""" 4
6742 .el .IP \f(CWHAS_GETMNT\fR 4
6743 .IX Xref "HAS_GETMNT"
6744 .IX Item "HAS_GETMNT"
6745 This symbol, if defined, indicates that the \f(CW\*(C`getmnt\*(C'\fR routine is
6746 available to get filesystem mount info by filename.
6747 .ie n .IP """HAS_GETMNTENT""" 4
6748 .el .IP \f(CWHAS_GETMNTENT\fR 4
6749 .IX Xref "HAS_GETMNTENT"
6750 .IX Item "HAS_GETMNTENT"
6751 This symbol, if defined, indicates that the \f(CW\*(C`getmntent\*(C'\fR routine is
6752 available to iterate through mounted file systems to get their info.
6753 .ie n .IP """HAS_HASMNTOPT""" 4
6754 .el .IP \f(CWHAS_HASMNTOPT\fR 4
6755 .IX Xref "HAS_HASMNTOPT"
6756 .IX Item "HAS_HASMNTOPT"
6757 This symbol, if defined, indicates that the \f(CW\*(C`hasmntopt\*(C'\fR routine is
6758 available to query the mount options of file systems.
6759 .ie n .IP """HAS_LSEEK_PROTO""" 4
6760 .el .IP \f(CWHAS_LSEEK_PROTO\fR 4
6761 .IX Xref "HAS_LSEEK_PROTO"
6762 .IX Item "HAS_LSEEK_PROTO"
6763 This symbol, if defined, indicates that the system provides
6764 a prototype for the \f(CWlseek()\fR function. Otherwise, it is up
6765 to the program to supply one. A good guess is
6766 .Sp
6767 .Vb 1
6768 \& extern off_t lseek(int, off_t, int);
6769 .Ve
6770 .ie n .IP """HAS_MKDIR""" 4
6771 .el .IP \f(CWHAS_MKDIR\fR 4
6772 .IX Xref "HAS_MKDIR"
6773 .IX Item "HAS_MKDIR"
6774 This symbol, if defined, indicates that the \f(CW\*(C`mkdir\*(C'\fR routine is available
6775 to create directories. Otherwise you should fork off a new process to
6776 exec \fI/bin/mkdir\fR.
6777 .ie n .IP """HAS_OFF64_T""" 4
6778 .el .IP \f(CWHAS_OFF64_T\fR 4
6779 .IX Xref "HAS_OFF64_T"
6780 .IX Item "HAS_OFF64_T"
6781 This symbol will be defined if the C compiler supports \f(CW\*(C`off64_t\*(C'\fR.
6782 .ie n .IP """HAS_OPENAT""" 4
6783 .el .IP \f(CWHAS_OPENAT\fR 4
6784 .IX Xref "HAS_OPENAT"
6785 .IX Item "HAS_OPENAT"
6786 This symbol is defined if the \f(CWopenat()\fR routine is available.
6787 .ie n .IP """HAS_OPEN3""" 4
6788 .el .IP \f(CWHAS_OPEN3\fR 4
6789 .IX Xref "HAS_OPEN3"
6790 .IX Item "HAS_OPEN3"
6791 This manifest constant lets the C program know that the three
6792 argument form of \f(CWopen(2)\fR is available.
6793 .ie n .IP """HAS_POLL""" 4
6794 .el .IP \f(CWHAS_POLL\fR 4
6795 .IX Xref "HAS_POLL"
6796 .IX Item "HAS_POLL"
6797 This symbol, if defined, indicates that the \f(CW\*(C`poll\*(C'\fR routine is
6798 available to \f(CW\*(C`poll\*(C'\fR active file descriptors. Please check \f(CW\*(C`I_POLL\*(C'\fR and
6799 \&\f(CW\*(C`I_SYS_POLL\*(C'\fR to know which header should be included as well.
6800 .ie n .IP """HAS_READDIR""" 4
6801 .el .IP \f(CWHAS_READDIR\fR 4
6802 .IX Xref "HAS_READDIR"
6803 .IX Item "HAS_READDIR"
6804 This symbol, if defined, indicates that the \f(CW\*(C`readdir\*(C'\fR routine is
6805 available to read directory entries. You may have to include
6806 \&\fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
6807 .ie n .IP """HAS_READDIR64_R""" 4
6808 .el .IP \f(CWHAS_READDIR64_R\fR 4
6809 .IX Xref "HAS_READDIR64_R"
6810 .IX Item "HAS_READDIR64_R"
6811 This symbol, if defined, indicates that the \f(CW\*(C`readdir64_r\*(C'\fR routine
6812 is available to readdir64 re\-entrantly.
6813 .ie n .IP """HAS_REWINDDIR""" 4
6814 .el .IP \f(CWHAS_REWINDDIR\fR 4
6815 .IX Xref "HAS_REWINDDIR"
6816 .IX Item "HAS_REWINDDIR"
6817 This symbol, if defined, indicates that the \f(CW\*(C`rewinddir\*(C'\fR routine is
6818 available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
6819 .ie n .IP """HAS_RMDIR""" 4
6820 .el .IP \f(CWHAS_RMDIR\fR 4
6821 .IX Xref "HAS_RMDIR"
6822 .IX Item "HAS_RMDIR"
6823 This symbol, if defined, indicates that the \f(CW\*(C`rmdir\*(C'\fR routine is
6824 available to remove directories. Otherwise you should fork off a
6825 new process to exec \fI/bin/rmdir\fR.
6826 .ie n .IP """HAS_SEEKDIR""" 4
6827 .el .IP \f(CWHAS_SEEKDIR\fR 4
6828 .IX Xref "HAS_SEEKDIR"
6829 .IX Item "HAS_SEEKDIR"
6830 This symbol, if defined, indicates that the \f(CW\*(C`seekdir\*(C'\fR routine is
6831 available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
6832 .ie n .IP """HAS_SELECT""" 4
6833 .el .IP \f(CWHAS_SELECT\fR 4
6834 .IX Xref "HAS_SELECT"
6835 .IX Item "HAS_SELECT"
6836 This symbol, if defined, indicates that the \f(CW\*(C`select\*(C'\fR routine is
6837 available to \f(CW\*(C`select\*(C'\fR active file descriptors. If the timeout field
6838 is used, \fIsys/time.h\fR may need to be included.
6839 .ie n .IP """HAS_SETVBUF""" 4
6840 .el .IP \f(CWHAS_SETVBUF\fR 4
6841 .IX Xref "HAS_SETVBUF"
6842 .IX Item "HAS_SETVBUF"
6843 This symbol, if defined, indicates that the \f(CW\*(C`setvbuf\*(C'\fR routine is
6844 available to change buffering on an open stdio stream.
6845 to a line\-buffered mode.
6846 .ie n .IP """HAS_STDIO_STREAM_ARRAY""" 4
6847 .el .IP \f(CWHAS_STDIO_STREAM_ARRAY\fR 4
6848 .IX Xref "HAS_STDIO_STREAM_ARRAY"
6849 .IX Item "HAS_STDIO_STREAM_ARRAY"
6850 This symbol, if defined, tells that there is an array
6851 holding the stdio streams.
6852 .ie n .IP """HAS_STRUCT_FS_DATA""" 4
6853 .el .IP \f(CWHAS_STRUCT_FS_DATA\fR 4
6854 .IX Xref "HAS_STRUCT_FS_DATA"
6855 .IX Item "HAS_STRUCT_FS_DATA"
6856 This symbol, if defined, indicates that the \f(CW\*(C`struct fs_data\*(C'\fR
6857 to do \f(CWstatfs()\fR is supported.
6858 .ie n .IP """HAS_STRUCT_STATFS""" 4
6859 .el .IP \f(CWHAS_STRUCT_STATFS\fR 4
6860 .IX Xref "HAS_STRUCT_STATFS"
6861 .IX Item "HAS_STRUCT_STATFS"
6862 This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR
6863 to do \f(CWstatfs()\fR is supported.
6864 .ie n .IP """HAS_STRUCT_STATFS_F_FLAGS""" 4
6865 .el .IP \f(CWHAS_STRUCT_STATFS_F_FLAGS\fR 4
6866 .IX Xref "HAS_STRUCT_STATFS_F_FLAGS"
6867 .IX Item "HAS_STRUCT_STATFS_F_FLAGS"
6868 This symbol, if defined, indicates that the \f(CW\*(C`struct statfs\*(C'\fR
6869 does have the \f(CW\*(C`f_flags\*(C'\fR member containing the mount flags of
6870 the filesystem containing the file.
6871 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),
6872 not from \fIsys/statfs.h\fR (\f(CW\*(C`SYSV\*(C'\fR). Older \f(CW\*(C`BSDs\*(C'\fR (like Ultrix) do not
6873 have \f(CWstatfs()\fR and \f(CW\*(C`struct statfs\*(C'\fR, they have \f(CWustat()\fR and \f(CWgetmnt()\fR
6874 with \f(CW\*(C`struct ustat\*(C'\fR and \f(CW\*(C`struct fs_data\*(C'\fR.
6875 .ie n .IP """HAS_TELLDIR""" 4
6876 .el .IP \f(CWHAS_TELLDIR\fR 4
6877 .IX Xref "HAS_TELLDIR"
6878 .IX Item "HAS_TELLDIR"
6879 This symbol, if defined, indicates that the \f(CW\*(C`telldir\*(C'\fR routine is
6880 available. You may have to include \fIdirent.h\fR. See \f(CW"I_DIRENT"\fR.
6881 .ie n .IP """HAS_USTAT""" 4
6882 .el .IP \f(CWHAS_USTAT\fR 4
6883 .IX Xref "HAS_USTAT"
6884 .IX Item "HAS_USTAT"
6885 This symbol, if defined, indicates that the \f(CW\*(C`ustat\*(C'\fR system call is
6886 available to query file system statistics by \f(CW\*(C`dev_t\*(C'\fR.
6887 .ie n .IP """I_FCNTL""" 4
6888 .el .IP \f(CWI_FCNTL\fR 4
6889 .IX Xref "I_FCNTL"
6890 .IX Item "I_FCNTL"
6891 This manifest constant tells the C program to include \fIfcntl.h\fR.
6892 .RS 4
6893 .Sp
6894 .Vb 3
6895 \& #ifdef I_FCNTL
6896 \& #include <fcntl.h>
6897 \& #endif
6898 .Ve
6899 .RE
6900 .RS 4
6901 .RE
6902 .ie n .IP """I_SYS_DIR""" 4
6903 .el .IP \f(CWI_SYS_DIR\fR 4
6904 .IX Xref "I_SYS_DIR"
6905 .IX Item "I_SYS_DIR"
6906 This symbol, if defined, indicates to the C program that it should
6907 include \fIsys/dir.h\fR.
6908 .RS 4
6909 .Sp
6910 .Vb 3
6911 \& #ifdef I_SYS_DIR
6912 \& #include <sys_dir.h>
6913 \& #endif
6914 .Ve
6915 .RE
6916 .RS 4
6917 .RE
6918 .ie n .IP """I_SYS_FILE""" 4
6919 .el .IP \f(CWI_SYS_FILE\fR 4
6920 .IX Xref "I_SYS_FILE"
6921 .IX Item "I_SYS_FILE"
6922 This symbol, if defined, indicates to the C program that it should
6923 include \fIsys/file.h\fR to get definition of \f(CW\*(C`R_OK\*(C'\fR and friends.
6924 .RS 4
6925 .Sp
6926 .Vb 3
6927 \& #ifdef I_SYS_FILE
6928 \& #include <sys_file.h>
6929 \& #endif
6930 .Ve
6931 .RE
6932 .RS 4
6933 .RE
6934 .ie n .IP """I_SYS_NDIR""" 4
6935 .el .IP \f(CWI_SYS_NDIR\fR 4
6936 .IX Xref "I_SYS_NDIR"
6937 .IX Item "I_SYS_NDIR"
6938 This symbol, if defined, indicates to the C program that it should
6939 include \fIsys/ndir.h\fR.
6940 .RS 4
6941 .Sp
6942 .Vb 3
6943 \& #ifdef I_SYS_NDIR
6944 \& #include <sys_ndir.h>
6945 \& #endif
6946 .Ve
6947 .RE
6948 .RS 4
6949 .RE
6950 .ie n .IP """I_SYS_STATFS""" 4
6951 .el .IP \f(CWI_SYS_STATFS\fR 4
6952 .IX Xref "I_SYS_STATFS"
6953 .IX Item "I_SYS_STATFS"
6954 This symbol, if defined, indicates that \fIsys/statfs.h\fR exists.
6955 .RS 4
6956 .Sp
6957 .Vb 3
6958 \& #ifdef I_SYS_STATFS
6959 \& #include <sys_statfs.h>
6960 \& #endif
6961 .Ve
6962 .RE
6963 .RS 4
6964 .RE
6965 .ie n .IP """LSEEKSIZE""" 4
6966 .el .IP \f(CWLSEEKSIZE\fR 4
6967 .IX Xref "LSEEKSIZE"
6968 .IX Item "LSEEKSIZE"
6969 This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR.
6970 .ie n .IP """RD_NODATA""" 4
6971 .el .IP \f(CWRD_NODATA\fR 4
6972 .IX Xref "RD_NODATA"
6973 .IX Item "RD_NODATA"
6974 This symbol holds the return code from \f(CWread()\fR when no data is present
6975 on the non\-blocking file descriptor. Be careful! If \f(CW\*(C`EOF_NONBLOCK\*(C'\fR is
6976 not defined, then you can\*(Aqt distinguish between no data and \f(CW\*(C`EOF\*(C'\fR by
6977 issuing a \f(CWread()\fR. You\*(Aqll have to find another way to tell for sure!
6978 .ie n .IP """READDIR64_R_PROTO""" 4
6979 .el .IP \f(CWREADDIR64_R_PROTO\fR 4
6980 .IX Xref "READDIR64_R_PROTO"
6981 .IX Item "READDIR64_R_PROTO"
6982 This symbol encodes the prototype of \f(CW\*(C`readdir64_r\*(C'\fR.
6983 It is zero if \f(CW\*(C`d_readdir64_r\*(C'\fR is undef, and one of the
6984 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir64_r\*(C'\fR
6985 is defined.
6986 .ie n .IP """ST_INO_SIGN""" 4
6987 .el .IP \f(CWST_INO_SIGN\fR 4
6988 .IX Xref "ST_INO_SIGN"
6989 .IX Item "ST_INO_SIGN"
6990 This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR\*(Aqs \f(CW\*(C`st_ino\*(C'\fR.
6991 1 for unsigned, \-1 for signed.
6992 .ie n .IP """ST_INO_SIZE""" 4
6993 .el .IP \f(CWST_INO_SIZE\fR 4
6994 .IX Xref "ST_INO_SIZE"
6995 .IX Item "ST_INO_SIZE"
6996 This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR\*(Aqs \f(CW\*(C`st_ino\*(C'\fR in bytes.
6997 .ie n .IP """STDCHAR""" 4
6998 .el .IP \f(CWSTDCHAR\fR 4
6999 .IX Xref "STDCHAR"
7000 .IX Item "STDCHAR"
7001 This symbol is defined to be the type of char used in \fIstdio.h\fR.
7002 It has the values "unsigned char" or "char".
7003 .ie n .IP """STDIO_CNT_LVALUE""" 4
7004 .el .IP \f(CWSTDIO_CNT_LVALUE\fR 4
7005 .IX Xref "STDIO_CNT_LVALUE"
7006 .IX Item "STDIO_CNT_LVALUE"
7007 This symbol is defined if the \f(CW\*(C`FILE_cnt\*(C'\fR macro can be used as an
7008 lvalue.
7009 .ie n .IP """STDIO_PTR_LVAL_NOCHANGE_CNT""" 4
7010 .el .IP \f(CWSTDIO_PTR_LVAL_NOCHANGE_CNT\fR 4
7011 .IX Xref "STDIO_PTR_LVAL_NOCHANGE_CNT"
7012 .IX Item "STDIO_PTR_LVAL_NOCHANGE_CNT"
7013 This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue
7014 to increase the pointer by n leaves \f(CWFile_cnt(fp)\fR unchanged.
7015 .ie n .IP """STDIO_PTR_LVAL_SETS_CNT""" 4
7016 .el .IP \f(CWSTDIO_PTR_LVAL_SETS_CNT\fR 4
7017 .IX Xref "STDIO_PTR_LVAL_SETS_CNT"
7018 .IX Item "STDIO_PTR_LVAL_SETS_CNT"
7019 This symbol is defined if using the \f(CW\*(C`FILE_ptr\*(C'\fR macro as an lvalue
7020 to increase the pointer by n has the side effect of decreasing the
7021 value of \f(CWFile_cnt(fp)\fR by n.
7022 .ie n .IP """STDIO_PTR_LVALUE""" 4
7023 .el .IP \f(CWSTDIO_PTR_LVALUE\fR 4
7024 .IX Xref "STDIO_PTR_LVALUE"
7025 .IX Item "STDIO_PTR_LVALUE"
7026 This symbol is defined if the \f(CW\*(C`FILE_ptr\*(C'\fR macro can be used as an
7027 lvalue.
7028 .ie n .IP """STDIO_STREAM_ARRAY""" 4
7029 .el .IP \f(CWSTDIO_STREAM_ARRAY\fR 4
7030 .IX Xref "STDIO_STREAM_ARRAY"
7031 .IX Item "STDIO_STREAM_ARRAY"
7032 This symbol tells the name of the array holding the stdio streams.
7033 Usual values include \f(CW\*(C`_iob\*(C'\fR, \f(CW\*(C`_\|_iob\*(C'\fR, and \f(CW\*(C`_\|_sF\*(C'\fR.
7034 .ie n .IP """VAL_EAGAIN""" 4
7035 .el .IP \f(CWVAL_EAGAIN\fR 4
7036 .IX Xref "VAL_EAGAIN"
7037 .IX Item "VAL_EAGAIN"
7038 This symbol holds the errno error code set by \f(CWread()\fR when no data was
7039 present on the non\-blocking file descriptor.
7040 .ie n .IP """VAL_O_NONBLOCK""" 4
7041 .el .IP \f(CWVAL_O_NONBLOCK\fR 4
7042 .IX Xref "VAL_O_NONBLOCK"
7043 .IX Item "VAL_O_NONBLOCK"
7044 This symbol is to be used during \f(CWopen()\fR or \f(CWfcntl(F_SETFL)\fR to turn on
7045 non\-blocking I/O for the file descriptor. Note that there is no way
7046 back, i.e. you cannot turn it blocking again this way. If you wish to
7047 alternatively switch between blocking and non\-blocking, use the
7048 \&\f(CWioctl(FIOSNBIO)\fR call instead, but that is not supported by all devices.
7049 .ie n .IP """VOID_CLOSEDIR""" 4
7050 .el .IP \f(CWVOID_CLOSEDIR\fR 4
7051 .IX Xref "VOID_CLOSEDIR"
7052 .IX Item "VOID_CLOSEDIR"
7053 This symbol, if defined, indicates that the \f(CWclosedir()\fR routine
7054 does not return a value.
7055 .SH "Floating point"
7056 .IX Header "Floating point"
7057 Also "List of capability HAS_foo symbols" lists capabilities
7058 that arent in this section. For example \f(CW\*(C`HAS_ASINH\*(C'\fR, for the
7059 hyperbolic sine function.
7060 .ie n .IP """CASTFLAGS""" 4
7061 .el .IP \f(CWCASTFLAGS\fR 4
7062 .IX Xref "CASTFLAGS"
7063 .IX Item "CASTFLAGS"
7064 This symbol contains flags that say what difficulties the compiler
7065 has casting odd floating values to unsigned long:
7066 .Sp
7067 .Vb 4
7068 \& 0 = ok
7069 \& 1 = couldn\*(Aqt cast < 0
7070 \& 2 = couldn\*(Aqt cast >= 0x80000000
7071 \& 4 = couldn\*(Aqt cast in argument expression list
7072 .Ve
7073 .ie n .IP """CASTNEGFLOAT""" 4
7074 .el .IP \f(CWCASTNEGFLOAT\fR 4
7075 .IX Xref "CASTNEGFLOAT"
7076 .IX Item "CASTNEGFLOAT"
7077 This symbol is defined if the C compiler can cast negative
7078 numbers to unsigned longs, ints and shorts.
7079 .ie n .IP """DOUBLE_HAS_INF""" 4
7080 .el .IP \f(CWDOUBLE_HAS_INF\fR 4
7081 .IX Xref "DOUBLE_HAS_INF"
7082 .IX Item "DOUBLE_HAS_INF"
7083 This symbol, if defined, indicates that the double has
7084 the infinity.
7085 .ie n .IP """DOUBLE_HAS_NAN""" 4
7086 .el .IP \f(CWDOUBLE_HAS_NAN\fR 4
7087 .IX Xref "DOUBLE_HAS_NAN"
7088 .IX Item "DOUBLE_HAS_NAN"
7089 This symbol, if defined, indicates that the double has
7090 the not\-a\-number.
7091 .ie n .IP """DOUBLE_HAS_NEGATIVE_ZERO""" 4
7092 .el .IP \f(CWDOUBLE_HAS_NEGATIVE_ZERO\fR 4
7093 .IX Xref "DOUBLE_HAS_NEGATIVE_ZERO"
7094 .IX Item "DOUBLE_HAS_NEGATIVE_ZERO"
7095 This symbol, if defined, indicates that the double has
7096 the \f(CW\*(C`negative_zero\*(C'\fR.
7097 .ie n .IP """DOUBLE_HAS_SUBNORMALS""" 4
7098 .el .IP \f(CWDOUBLE_HAS_SUBNORMALS\fR 4
7099 .IX Xref "DOUBLE_HAS_SUBNORMALS"
7100 .IX Item "DOUBLE_HAS_SUBNORMALS"
7101 This symbol, if defined, indicates that the double has
7102 the subnormals (denormals).
7103 .ie n .IP """DOUBLE_STYLE_CRAY""" 4
7104 .el .IP \f(CWDOUBLE_STYLE_CRAY\fR 4
7105 .IX Xref "DOUBLE_STYLE_CRAY"
7106 .IX Item "DOUBLE_STYLE_CRAY"
7107 This symbol, if defined, indicates that the double is
7108 the 64\-bit \f(CW\*(C`CRAY\*(C'\fR mainframe format.
7109 .ie n .IP """DOUBLE_STYLE_IBM""" 4
7110 .el .IP \f(CWDOUBLE_STYLE_IBM\fR 4
7111 .IX Xref "DOUBLE_STYLE_IBM"
7112 .IX Item "DOUBLE_STYLE_IBM"
7113 This symbol, if defined, indicates that the double is
7114 the 64\-bit \f(CW\*(C`IBM\*(C'\fR mainframe format.
7115 .ie n .IP """DOUBLE_STYLE_IEEE""" 4
7116 .el .IP \f(CWDOUBLE_STYLE_IEEE\fR 4
7117 .IX Xref "DOUBLE_STYLE_IEEE"
7118 .IX Item "DOUBLE_STYLE_IEEE"
7119 This symbol, if defined, indicates that the double is
7120 the 64\-bit \f(CW\*(C`IEEE\*(C'\fR 754.
7121 .ie n .IP """DOUBLE_STYLE_VAX""" 4
7122 .el .IP \f(CWDOUBLE_STYLE_VAX\fR 4
7123 .IX Xref "DOUBLE_STYLE_VAX"
7124 .IX Item "DOUBLE_STYLE_VAX"
7125 This symbol, if defined, indicates that the double is
7126 the 64\-bit \f(CW\*(C`VAX\*(C'\fR format D or G.
7127 .ie n .IP """DOUBLEINFBYTES""" 4
7128 .el .IP \f(CWDOUBLEINFBYTES\fR 4
7129 .IX Xref "DOUBLEINFBYTES"
7130 .IX Item "DOUBLEINFBYTES"
7131 This symbol, if defined, is a comma\-separated list of
7132 hexadecimal bytes for the double precision infinity.
7133 .ie n .IP """DOUBLEKIND""" 4
7134 .el .IP \f(CWDOUBLEKIND\fR 4
7135 .IX Xref "DOUBLEKIND"
7136 .IX Item "DOUBLEKIND"
7137 \&\f(CW\*(C`DOUBLEKIND\*(C'\fR will be one of
7138 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_LITTLE_ENDIAN\*(C'\fR
7139 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_32_BIT_BIG_ENDIAN\*(C'\fR
7140 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_LITTLE_ENDIAN\*(C'\fR
7141 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_BIG_ENDIAN\*(C'\fR
7142 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR
7143 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR
7144 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_LE_BE\*(C'\fR
7145 \&\f(CW\*(C`DOUBLE_IS_IEEE_754_64_BIT_MIXED_ENDIAN_BE_LE\*(C'\fR
7146 \&\f(CW\*(C`DOUBLE_IS_VAX_F_FLOAT\*(C'\fR
7147 \&\f(CW\*(C`DOUBLE_IS_VAX_D_FLOAT\*(C'\fR
7148 \&\f(CW\*(C`DOUBLE_IS_VAX_G_FLOAT\*(C'\fR
7149 \&\f(CW\*(C`DOUBLE_IS_IBM_SINGLE_32_BIT\*(C'\fR
7150 \&\f(CW\*(C`DOUBLE_IS_IBM_DOUBLE_64_BIT\*(C'\fR
7151 \&\f(CW\*(C`DOUBLE_IS_CRAY_SINGLE_64_BIT\*(C'\fR
7152 \&\f(CW\*(C`DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR
7153 .ie n .IP """DOUBLEMANTBITS""" 4
7154 .el .IP \f(CWDOUBLEMANTBITS\fR 4
7155 .IX Xref "DOUBLEMANTBITS"
7156 .IX Item "DOUBLEMANTBITS"
7157 This symbol, if defined, tells how many mantissa bits
7158 there are in double precision floating point format.
7159 Note that this is usually \f(CW\*(C`DBL_MANT_DIG\*(C'\fR minus one, since
7160 with the standard \f(CW\*(C`IEEE\*(C'\fR 754 formats \f(CW\*(C`DBL_MANT_DIG\*(C'\fR includes
7161 the implicit bit, which doesn\*(Aqt really exist.
7162 .ie n .IP """DOUBLENANBYTES""" 4
7163 .el .IP \f(CWDOUBLENANBYTES\fR 4
7164 .IX Xref "DOUBLENANBYTES"
7165 .IX Item "DOUBLENANBYTES"
7166 This symbol, if defined, is a comma\-separated list of
7167 hexadecimal bytes (0xHH) for the double precision not\-a\-number.
7168 .ie n .IP """DOUBLESIZE""" 4
7169 .el .IP \f(CWDOUBLESIZE\fR 4
7170 .IX Xref "DOUBLESIZE"
7171 .IX Item "DOUBLESIZE"
7172 This symbol contains the size of a double, so that the C preprocessor
7173 can make decisions based on it.
7174 .ie n .IP """Gconvert""" 4
7175 .el .IP \f(CWGconvert\fR 4
7176 .IX Xref "Gconvert"
7177 .IX Item "Gconvert"
7178 This preprocessor macro is defined to convert a floating point
7179 number to a string without a trailing decimal point. This
7180 emulates the behavior of \f(CWsprintf("%g")\fR, but is sometimes much more
7181 efficient. If \f(CWgconvert()\fR is not available, but \f(CWgcvt()\fR drops the
7182 trailing decimal point, then \f(CWgcvt()\fR is used. If all else fails,
7183 a macro using \f(CWsprintf("%g")\fR is used. Arguments for the Gconvert
7184 macro are: value, number of digits, whether trailing zeros should
7185 be retained, and the output buffer.
7186 The usual values are:
7187 .Sp
7188 .Vb 3
7189 \& d_Gconvert=\*(Aqgconvert((x),(n),(t),(b))\*(Aq
7190 \& d_Gconvert=\*(Aqgcvt((x),(n),(b))\*(Aq
7191 \& d_Gconvert=\*(Aqsprintf((b),"%.*g",(n),(x))\*(Aq
7192 .Ve
7193 .Sp
7194 The last two assume trailing zeros should not be kept.
7195 .RS 4
7196 .Sp
7197 .Vb 1
7198 \& char * Gconvert(double x, Size_t n, bool t, char * b)
7199 .Ve
7200 .RE
7201 .RS 4
7202 .RE
7203 .ie n .IP """HAS_ATOLF""" 4
7204 .el .IP \f(CWHAS_ATOLF\fR 4
7205 .IX Xref "HAS_ATOLF"
7206 .IX Item "HAS_ATOLF"
7207 This symbol, if defined, indicates that the \f(CW\*(C`atolf\*(C'\fR routine is
7208 available to convert strings into long doubles.
7209 .ie n .IP """HAS_CLASS""" 4
7210 .el .IP \f(CWHAS_CLASS\fR 4
7211 .IX Xref "HAS_CLASS"
7212 .IX Item "HAS_CLASS"
7213 This symbol, if defined, indicates that the \f(CW\*(C`class\*(C'\fR routine is
7214 available to classify doubles. Available for example in \f(CW\*(C`AIX\*(C'\fR.
7215 The returned values are defined in \fIfloat.h\fR and are:
7216 .Sp
7217 .Vb 10
7218 \& FP_PLUS_NORM Positive normalized, nonzero
7219 \& FP_MINUS_NORM Negative normalized, nonzero
7220 \& FP_PLUS_DENORM Positive denormalized, nonzero
7221 \& FP_MINUS_DENORM Negative denormalized, nonzero
7222 \& FP_PLUS_ZERO +0.0
7223 \& FP_MINUS_ZERO \-0.0
7224 \& FP_PLUS_INF +INF
7225 \& FP_MINUS_INF \-INF
7226 \& FP_NANS Signaling Not a Number (NaNS)
7227 \& FP_NANQ Quiet Not a Number (NaNQ)
7228 .Ve
7229 .ie n .IP """HAS_FINITE""" 4
7230 .el .IP \f(CWHAS_FINITE\fR 4
7231 .IX Xref "HAS_FINITE"
7232 .IX Item "HAS_FINITE"
7233 This symbol, if defined, indicates that the \f(CW\*(C`finite\*(C'\fR routine is
7234 available to check whether a double is \f(CW\*(C`finite\*(C'\fR (non\-infinity non\-NaN).
7235 .ie n .IP """HAS_FINITEL""" 4
7236 .el .IP \f(CWHAS_FINITEL\fR 4
7237 .IX Xref "HAS_FINITEL"
7238 .IX Item "HAS_FINITEL"
7239 This symbol, if defined, indicates that the \f(CW\*(C`finitel\*(C'\fR routine is
7240 available to check whether a long double is finite
7241 (non\-infinity non\-NaN).
7242 .ie n .IP """HAS_FP_CLASS""" 4
7243 .el .IP \f(CWHAS_FP_CLASS\fR 4
7244 .IX Xref "HAS_FP_CLASS"
7245 .IX Item "HAS_FP_CLASS"
7246 This symbol, if defined, indicates that the \f(CW\*(C`fp_class\*(C'\fR routine is
7247 available to classify doubles. Available for example in Digital \f(CW\*(C`UNIX\*(C'\fR.
7248 The returned values are defined in \fImath.h\fR and are:
7249 .Sp
7250 .Vb 10
7251 \& FP_SNAN Signaling NaN (Not\-a\-Number)
7252 \& FP_QNAN Quiet NaN (Not\-a\-Number)
7253 \& FP_POS_INF +infinity
7254 \& FP_NEG_INF \-infinity
7255 \& FP_POS_NORM Positive normalized
7256 \& FP_NEG_NORM Negative normalized
7257 \& FP_POS_DENORM Positive denormalized
7258 \& FP_NEG_DENORM Negative denormalized
7259 \& FP_POS_ZERO +0.0 (positive zero)
7260 \& FP_NEG_ZERO \-0.0 (negative zero)
7261 .Ve
7262 .ie n .IP """HAS_FP_CLASSIFY""" 4
7263 .el .IP \f(CWHAS_FP_CLASSIFY\fR 4
7264 .IX Xref "HAS_FP_CLASSIFY"
7265 .IX Item "HAS_FP_CLASSIFY"
7266 This symbol, if defined, indicates that the \f(CW\*(C`fp_classify\*(C'\fR routine is
7267 available to classify doubles. The values are defined in \fImath.h\fR
7268 .Sp
7269 .Vb 5
7270 \& FP_NORMAL Normalized
7271 \& FP_ZERO Zero
7272 \& FP_INFINITE Infinity
7273 \& FP_SUBNORMAL Denormalized
7274 \& FP_NAN NaN
7275 .Ve
7276 .ie n .IP """HAS_FP_CLASSL""" 4
7277 .el .IP \f(CWHAS_FP_CLASSL\fR 4
7278 .IX Xref "HAS_FP_CLASSL"
7279 .IX Item "HAS_FP_CLASSL"
7280 This symbol, if defined, indicates that the \f(CW\*(C`fp_classl\*(C'\fR routine is
7281 available to classify long doubles. Available for example in
7282 Digital \f(CW\*(C`UNIX\*(C'\fR. See for possible values \f(CW\*(C`HAS_FP_CLASS\*(C'\fR.
7283 .ie n .IP """HAS_FPCLASS""" 4
7284 .el .IP \f(CWHAS_FPCLASS\fR 4
7285 .IX Xref "HAS_FPCLASS"
7286 .IX Item "HAS_FPCLASS"
7287 This symbol, if defined, indicates that the \f(CW\*(C`fpclass\*(C'\fR routine is
7288 available to classify doubles. Available for example in Solaris/\f(CW\*(C`SVR4\*(C'\fR.
7289 The returned values are defined in \fIieeefp.h\fR and are:
7290 .Sp
7291 .Vb 10
7292 \& FP_SNAN signaling NaN
7293 \& FP_QNAN quiet NaN
7294 \& FP_NINF negative infinity
7295 \& FP_PINF positive infinity
7296 \& FP_NDENORM negative denormalized non\-zero
7297 \& FP_PDENORM positive denormalized non\-zero
7298 \& FP_NZERO negative zero
7299 \& FP_PZERO positive zero
7300 \& FP_NNORM negative normalized non\-zero
7301 \& FP_PNORM positive normalized non\-zero
7302 .Ve
7303 .ie n .IP """HAS_FPCLASSIFY""" 4
7304 .el .IP \f(CWHAS_FPCLASSIFY\fR 4
7305 .IX Xref "HAS_FPCLASSIFY"
7306 .IX Item "HAS_FPCLASSIFY"
7307 This symbol, if defined, indicates that the \f(CW\*(C`fpclassify\*(C'\fR routine is
7308 available to classify doubles. Available for example in HP\-UX.
7309 The returned values are defined in \fImath.h\fR and are
7310 .Sp
7311 .Vb 5
7312 \& FP_NORMAL Normalized
7313 \& FP_ZERO Zero
7314 \& FP_INFINITE Infinity
7315 \& FP_SUBNORMAL Denormalized
7316 \& FP_NAN NaN
7317 .Ve
7318 .ie n .IP """HAS_FPCLASSL""" 4
7319 .el .IP \f(CWHAS_FPCLASSL\fR 4
7320 .IX Xref "HAS_FPCLASSL"
7321 .IX Item "HAS_FPCLASSL"
7322 This symbol, if defined, indicates that the \f(CW\*(C`fpclassl\*(C'\fR routine is
7323 available to classify long doubles. Available for example in \f(CW\*(C`IRIX\*(C'\fR.
7324 The returned values are defined in \fIieeefp.h\fR and are:
7325 .Sp
7326 .Vb 10
7327 \& FP_SNAN signaling NaN
7328 \& FP_QNAN quiet NaN
7329 \& FP_NINF negative infinity
7330 \& FP_PINF positive infinity
7331 \& FP_NDENORM negative denormalized non\-zero
7332 \& FP_PDENORM positive denormalized non\-zero
7333 \& FP_NZERO negative zero
7334 \& FP_PZERO positive zero
7335 \& FP_NNORM negative normalized non\-zero
7336 \& FP_PNORM positive normalized non\-zero
7337 .Ve
7338 .ie n .IP """HAS_FPGETROUND""" 4
7339 .el .IP \f(CWHAS_FPGETROUND\fR 4
7340 .IX Xref "HAS_FPGETROUND"
7341 .IX Item "HAS_FPGETROUND"
7342 This symbol, if defined, indicates that the \f(CW\*(C`fpgetround\*(C'\fR routine is
7343 available to get the floating point rounding mode.
7344 .ie n .IP """HAS_FREXPL""" 4
7345 .el .IP \f(CWHAS_FREXPL\fR 4
7346 .IX Xref "HAS_FREXPL"
7347 .IX Item "HAS_FREXPL"
7348 This symbol, if defined, indicates that the \f(CW\*(C`frexpl\*(C'\fR routine is
7349 available to break a long double floating\-point number into
7350 a normalized fraction and an integral power of 2.
7351 .ie n .IP """HAS_ILOGB""" 4
7352 .el .IP \f(CWHAS_ILOGB\fR 4
7353 .IX Xref "HAS_ILOGB"
7354 .IX Item "HAS_ILOGB"
7355 This symbol, if defined, indicates that the \f(CW\*(C`ilogb\*(C'\fR routine is
7356 available to get integer exponent of a floating\-point value.
7357 .ie n .IP """HAS_ISFINITE""" 4
7358 .el .IP \f(CWHAS_ISFINITE\fR 4
7359 .IX Xref "HAS_ISFINITE"
7360 .IX Item "HAS_ISFINITE"
7361 This symbol, if defined, indicates that the \f(CW\*(C`isfinite\*(C'\fR routine is
7362 available to check whether a double is finite (non\-infinity non\-NaN).
7363 .ie n .IP """HAS_ISFINITEL""" 4
7364 .el .IP \f(CWHAS_ISFINITEL\fR 4
7365 .IX Xref "HAS_ISFINITEL"
7366 .IX Item "HAS_ISFINITEL"
7367 This symbol, if defined, indicates that the \f(CW\*(C`isfinitel\*(C'\fR routine is
7368 available to check whether a long double is finite.
7369 (non\-infinity non\-NaN).
7370 .ie n .IP """HAS_ISINF""" 4
7371 .el .IP \f(CWHAS_ISINF\fR 4
7372 .IX Xref "HAS_ISINF"
7373 .IX Item "HAS_ISINF"
7374 This symbol, if defined, indicates that the \f(CW\*(C`isinf\*(C'\fR routine is
7375 available to check whether a double is an infinity.
7376 .ie n .IP """HAS_ISINFL""" 4
7377 .el .IP \f(CWHAS_ISINFL\fR 4
7378 .IX Xref "HAS_ISINFL"
7379 .IX Item "HAS_ISINFL"
7380 This symbol, if defined, indicates that the \f(CW\*(C`isinfl\*(C'\fR routine is
7381 available to check whether a long double is an infinity.
7382 .ie n .IP """HAS_ISNAN""" 4
7383 .el .IP \f(CWHAS_ISNAN\fR 4
7384 .IX Xref "HAS_ISNAN"
7385 .IX Item "HAS_ISNAN"
7386 This symbol, if defined, indicates that the \f(CW\*(C`isnan\*(C'\fR routine is
7387 available to check whether a double is a NaN.
7388 .ie n .IP """HAS_ISNANL""" 4
7389 .el .IP \f(CWHAS_ISNANL\fR 4
7390 .IX Xref "HAS_ISNANL"
7391 .IX Item "HAS_ISNANL"
7392 This symbol, if defined, indicates that the \f(CW\*(C`isnanl\*(C'\fR routine is
7393 available to check whether a long double is a NaN.
7394 .ie n .IP """HAS_ISNORMAL""" 4
7395 .el .IP \f(CWHAS_ISNORMAL\fR 4
7396 .IX Xref "HAS_ISNORMAL"
7397 .IX Item "HAS_ISNORMAL"
7398 This symbol, if defined, indicates that the \f(CW\*(C`isnormal\*(C'\fR routine is
7399 available to check whether a double is normal (non\-zero normalized).
7400 .ie n .IP """HAS_J0""" 4
7401 .el .IP \f(CWHAS_J0\fR 4
7402 .IX Xref "HAS_J0"
7403 .IX Item "HAS_J0"
7404 This symbol, if defined, indicates to the C program that the
7405 \&\f(CWj0()\fR function is available for Bessel functions of the first
7406 kind of the order zero, for doubles.
7407 .ie n .IP """HAS_J0L""" 4
7408 .el .IP \f(CWHAS_J0L\fR 4
7409 .IX Xref "HAS_J0L"
7410 .IX Item "HAS_J0L"
7411 This symbol, if defined, indicates to the C program that the
7412 \&\f(CWj0l()\fR function is available for Bessel functions of the first
7413 kind of the order zero, for long doubles.
7414 .ie n .IP """HAS_LDBL_DIG""" 4
7415 .el .IP \f(CWHAS_LDBL_DIG\fR 4
7416 .IX Xref "HAS_LDBL_DIG"
7417 .IX Item "HAS_LDBL_DIG"
7418 This symbol, if defined, indicates that this system\*(Aqs \fIfloat.h\fR
7419 or \fIlimits.h\fR defines the symbol \f(CW\*(C`LDBL_DIG\*(C'\fR, which is the number
7420 of significant digits in a long double precision number. Unlike
7421 for \f(CW\*(C`DBL_DIG\*(C'\fR, there\*(Aqs no good guess for \f(CW\*(C`LDBL_DIG\*(C'\fR if it is undefined.
7422 .ie n .IP """HAS_LDEXPL""" 4
7423 .el .IP \f(CWHAS_LDEXPL\fR 4
7424 .IX Xref "HAS_LDEXPL"
7425 .IX Item "HAS_LDEXPL"
7426 This symbol, if defined, indicates that the \f(CW\*(C`ldexpl\*(C'\fR routine is
7427 available to shift a long double floating\-point number
7428 by an integral power of 2.
7429 .ie n .IP """HAS_LLRINT""" 4
7430 .el .IP \f(CWHAS_LLRINT\fR 4
7431 .IX Xref "HAS_LLRINT"
7432 .IX Item "HAS_LLRINT"
7433 This symbol, if defined, indicates that the \f(CW\*(C`llrint\*(C'\fR routine is
7434 available to return the long long value closest to a double
7435 (according to the current rounding mode).
7436 .ie n .IP """HAS_LLRINTL""" 4
7437 .el .IP \f(CWHAS_LLRINTL\fR 4
7438 .IX Xref "HAS_LLRINTL"
7439 .IX Item "HAS_LLRINTL"
7440 This symbol, if defined, indicates that the \f(CW\*(C`llrintl\*(C'\fR routine is
7441 available to return the long long value closest to a long double
7442 (according to the current rounding mode).
7443 .ie n .IP """HAS_LLROUNDL""" 4
7444 .el .IP \f(CWHAS_LLROUNDL\fR 4
7445 .IX Xref "HAS_LLROUNDL"
7446 .IX Item "HAS_LLROUNDL"
7447 This symbol, if defined, indicates that the \f(CW\*(C`llroundl\*(C'\fR routine is
7448 available to return the nearest long long value away from zero of
7449 the long double argument value.
7450 .ie n .IP """HAS_LONG_DOUBLE""" 4
7451 .el .IP \f(CWHAS_LONG_DOUBLE\fR 4
7452 .IX Xref "HAS_LONG_DOUBLE"
7453 .IX Item "HAS_LONG_DOUBLE"
7454 This symbol will be defined if the C compiler supports long
7455 doubles.
7456 .ie n .IP """HAS_LRINT""" 4
7457 .el .IP \f(CWHAS_LRINT\fR 4
7458 .IX Xref "HAS_LRINT"
7459 .IX Item "HAS_LRINT"
7460 This symbol, if defined, indicates that the \f(CW\*(C`lrint\*(C'\fR routine is
7461 available to return the integral value closest to a double
7462 (according to the current rounding mode).
7463 .ie n .IP """HAS_LRINTL""" 4
7464 .el .IP \f(CWHAS_LRINTL\fR 4
7465 .IX Xref "HAS_LRINTL"
7466 .IX Item "HAS_LRINTL"
7467 This symbol, if defined, indicates that the \f(CW\*(C`lrintl\*(C'\fR routine is
7468 available to return the integral value closest to a long double
7469 (according to the current rounding mode).
7470 .ie n .IP """HAS_LROUNDL""" 4
7471 .el .IP \f(CWHAS_LROUNDL\fR 4
7472 .IX Xref "HAS_LROUNDL"
7473 .IX Item "HAS_LROUNDL"
7474 This symbol, if defined, indicates that the \f(CW\*(C`lroundl\*(C'\fR routine is
7475 available to return the nearest integral value away from zero of
7476 the long double argument value.
7477 .ie n .IP """HAS_MODFL""" 4
7478 .el .IP \f(CWHAS_MODFL\fR 4
7479 .IX Xref "HAS_MODFL"
7480 .IX Item "HAS_MODFL"
7481 This symbol, if defined, indicates that the \f(CW\*(C`modfl\*(C'\fR routine is
7482 available to split a long double x into a fractional part f and
7483 an integer part i such that |f| < 1.0 and (f + i) = x.
7484 .ie n .IP """HAS_NAN""" 4
7485 .el .IP \f(CWHAS_NAN\fR 4
7486 .IX Xref "HAS_NAN"
7487 .IX Item "HAS_NAN"
7488 This symbol, if defined, indicates that the \f(CW\*(C`nan\*(C'\fR routine is
7489 available to generate NaN.
7490 .ie n .IP """HAS_NEXTTOWARD""" 4
7491 .el .IP \f(CWHAS_NEXTTOWARD\fR 4
7492 .IX Xref "HAS_NEXTTOWARD"
7493 .IX Item "HAS_NEXTTOWARD"
7494 This symbol, if defined, indicates that the \f(CW\*(C`nexttoward\*(C'\fR routine is
7495 available to return the next machine representable long double from
7496 x in direction y.
7497 .ie n .IP """HAS_REMAINDER""" 4
7498 .el .IP \f(CWHAS_REMAINDER\fR 4
7499 .IX Xref "HAS_REMAINDER"
7500 .IX Item "HAS_REMAINDER"
7501 This symbol, if defined, indicates that the \f(CW\*(C`remainder\*(C'\fR routine is
7502 available to return the floating\-point \f(CW\*(C`remainder\*(C'\fR.
7503 .ie n .IP """HAS_SCALBN""" 4
7504 .el .IP \f(CWHAS_SCALBN\fR 4
7505 .IX Xref "HAS_SCALBN"
7506 .IX Item "HAS_SCALBN"
7507 This symbol, if defined, indicates that the \f(CW\*(C`scalbn\*(C'\fR routine is
7508 available to multiply floating\-point number by integral power
7509 of radix.
7510 .ie n .IP """HAS_SIGNBIT""" 4
7511 .el .IP \f(CWHAS_SIGNBIT\fR 4
7512 .IX Xref "HAS_SIGNBIT"
7513 .IX Item "HAS_SIGNBIT"
7514 This symbol, if defined, indicates that the \f(CW\*(C`signbit\*(C'\fR routine is
7515 available to check if the given number has the sign bit set.
7516 This should include correct testing of \-0.0. This will only be set
7517 if the \f(CWsignbit()\fR routine is safe to use with the NV type used internally
7518 in perl. Users should call \f(CWPerl_signbit()\fR, which will be #defined to
7519 the system\*(Aqs \f(CWsignbit()\fR function or macro if this symbol is defined.
7520 .ie n .IP """HAS_SQRTL""" 4
7521 .el .IP \f(CWHAS_SQRTL\fR 4
7522 .IX Xref "HAS_SQRTL"
7523 .IX Item "HAS_SQRTL"
7524 This symbol, if defined, indicates that the \f(CW\*(C`sqrtl\*(C'\fR routine is
7525 available to do long double square roots.
7526 .ie n .IP """HAS_STRTOD_L""" 4
7527 .el .IP \f(CWHAS_STRTOD_L\fR 4
7528 .IX Xref "HAS_STRTOD_L"
7529 .IX Item "HAS_STRTOD_L"
7530 This symbol, if defined, indicates that the \f(CW\*(C`strtod_l\*(C'\fR routine is
7531 available to convert strings to long doubles.
7532 .ie n .IP """HAS_STRTOLD""" 4
7533 .el .IP \f(CWHAS_STRTOLD\fR 4
7534 .IX Xref "HAS_STRTOLD"
7535 .IX Item "HAS_STRTOLD"
7536 This symbol, if defined, indicates that the \f(CW\*(C`strtold\*(C'\fR routine is
7537 available to convert strings to long doubles.
7538 .ie n .IP """HAS_STRTOLD_L""" 4
7539 .el .IP \f(CWHAS_STRTOLD_L\fR 4
7540 .IX Xref "HAS_STRTOLD_L"
7541 .IX Item "HAS_STRTOLD_L"
7542 This symbol, if defined, indicates that the \f(CW\*(C`strtold_l\*(C'\fR routine is
7543 available to convert strings to long doubles.
7544 .ie n .IP """HAS_TRUNC""" 4
7545 .el .IP \f(CWHAS_TRUNC\fR 4
7546 .IX Xref "HAS_TRUNC"
7547 .IX Item "HAS_TRUNC"
7548 This symbol, if defined, indicates that the \f(CW\*(C`trunc\*(C'\fR routine is
7549 available to round doubles towards zero.
7550 .ie n .IP """HAS_UNORDERED""" 4
7551 .el .IP \f(CWHAS_UNORDERED\fR 4
7552 .IX Xref "HAS_UNORDERED"
7553 .IX Item "HAS_UNORDERED"
7554 This symbol, if defined, indicates that the \f(CW\*(C`unordered\*(C'\fR routine is
7555 available to check whether two doubles are \f(CW\*(C`unordered\*(C'\fR
7556 (effectively: whether either of them is NaN)
7557 .ie n .IP """I_FENV""" 4
7558 .el .IP \f(CWI_FENV\fR 4
7559 .IX Xref "I_FENV"
7560 .IX Item "I_FENV"
7561 This symbol, if defined, indicates to the C program that it should
7562 include \fIfenv.h\fR to get the floating point environment definitions.
7563 .RS 4
7564 .Sp
7565 .Vb 3
7566 \& #ifdef I_FENV
7567 \& #include <fenv.h>
7568 \& #endif
7569 .Ve
7570 .RE
7571 .RS 4
7572 .RE
7573 .ie n .IP """I_QUADMATH""" 4
7574 .el .IP \f(CWI_QUADMATH\fR 4
7575 .IX Xref "I_QUADMATH"
7576 .IX Item "I_QUADMATH"
7577 This symbol, if defined, indicates that \fIquadmath.h\fR exists and
7578 should be included.
7579 .RS 4
7580 .Sp
7581 .Vb 3
7582 \& #ifdef I_QUADMATH
7583 \& #include <quadmath.h>
7584 \& #endif
7585 .Ve
7586 .RE
7587 .RS 4
7588 .RE
7589 .ie n .IP """LONG_DOUBLE_STYLE_IEEE""" 4
7590 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE\fR 4
7591 .IX Xref "LONG_DOUBLE_STYLE_IEEE"
7592 .IX Item "LONG_DOUBLE_STYLE_IEEE"
7593 This symbol, if defined, indicates that the long double
7594 is any of the \f(CW\*(C`IEEE\*(C'\fR 754 style long doubles:
7595 \&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_STD\*(C'\fR, \f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_EXTENDED\*(C'\fR,
7596 \&\f(CW\*(C`LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\*(C'\fR.
7597 .ie n .IP """LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE""" 4
7598 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE\fR 4
7599 .IX Xref "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
7600 .IX Item "LONG_DOUBLE_STYLE_IEEE_DOUBLEDOUBLE"
7601 This symbol, if defined, indicates that the long double is
7602 the 128\-bit double\-double.
7603 .ie n .IP """LONG_DOUBLE_STYLE_IEEE_EXTENDED""" 4
7604 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_EXTENDED\fR 4
7605 .IX Xref "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
7606 .IX Item "LONG_DOUBLE_STYLE_IEEE_EXTENDED"
7607 This symbol, if defined, indicates that the long double is
7608 the 80\-bit \f(CW\*(C`IEEE\*(C'\fR 754. Note that despite the \*(Aqextended\*(Aq this
7609 is less than the \*(Aqstd\*(Aq, since this is an extension of
7610 the double precision.
7611 .ie n .IP """LONG_DOUBLE_STYLE_IEEE_STD""" 4
7612 .el .IP \f(CWLONG_DOUBLE_STYLE_IEEE_STD\fR 4
7613 .IX Xref "LONG_DOUBLE_STYLE_IEEE_STD"
7614 .IX Item "LONG_DOUBLE_STYLE_IEEE_STD"
7615 This symbol, if defined, indicates that the long double is
7616 the 128\-bit \f(CW\*(C`IEEE\*(C'\fR 754.
7617 .ie n .IP """LONG_DOUBLE_STYLE_VAX""" 4
7618 .el .IP \f(CWLONG_DOUBLE_STYLE_VAX\fR 4
7619 .IX Xref "LONG_DOUBLE_STYLE_VAX"
7620 .IX Item "LONG_DOUBLE_STYLE_VAX"
7621 This symbol, if defined, indicates that the long double is
7622 the 128\-bit \f(CW\*(C`VAX\*(C'\fR format H.
7623 .ie n .IP """LONG_DOUBLEKIND""" 4
7624 .el .IP \f(CWLONG_DOUBLEKIND\fR 4
7625 .IX Xref "LONG_DOUBLEKIND"
7626 .IX Item "LONG_DOUBLEKIND"
7627 \&\f(CW\*(C`LONG_DOUBLEKIND\*(C'\fR will be one of
7628 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLE\*(C'\fR
7629 \&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_LITTLE_ENDIAN\*(C'\fR
7630 \&\f(CW\*(C`LONG_DOUBLE_IS_IEEE_754_128_BIT_BIG_ENDIAN\*(C'\fR
7631 \&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_LITTLE_ENDIAN\*(C'\fR
7632 \&\f(CW\*(C`LONG_DOUBLE_IS_X86_80_BIT_BIG_ENDIAN\*(C'\fR
7633 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_LE\*(C'\fR
7634 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_BE\*(C'\fR
7635 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LE_BE\*(C'\fR
7636 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BE_LE\*(C'\fR
7637 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_LITTLE_ENDIAN\*(C'\fR
7638 \&\f(CW\*(C`LONG_DOUBLE_IS_DOUBLEDOUBLE_128_BIT_BIG_ENDIAN\*(C'\fR
7639 \&\f(CW\*(C`LONG_DOUBLE_IS_VAX_H_FLOAT\*(C'\fR
7640 \&\f(CW\*(C`LONG_DOUBLE_IS_UNKNOWN_FORMAT\*(C'\fR
7641 It is only defined if the system supports long doubles.
7642 .ie n .IP """LONG_DOUBLESIZE""" 4
7643 .el .IP \f(CWLONG_DOUBLESIZE\fR 4
7644 .IX Xref "LONG_DOUBLESIZE"
7645 .IX Item "LONG_DOUBLESIZE"
7646 This symbol contains the size of a long double, so that the
7647 C preprocessor can make decisions based on it. It is only
7648 defined if the system supports long doubles. Note that this
7649 is \f(CW\*(C`sizeof(long double)\*(C'\fR, which may include unused bytes.
7650 .ie n .IP """LONGDBLINFBYTES""" 4
7651 .el .IP \f(CWLONGDBLINFBYTES\fR 4
7652 .IX Xref "LONGDBLINFBYTES"
7653 .IX Item "LONGDBLINFBYTES"
7654 This symbol, if defined, is a comma\-separated list of
7655 hexadecimal bytes for the long double precision infinity.
7656 .ie n .IP """LONGDBLMANTBITS""" 4
7657 .el .IP \f(CWLONGDBLMANTBITS\fR 4
7658 .IX Xref "LONGDBLMANTBITS"
7659 .IX Item "LONGDBLMANTBITS"
7660 This symbol, if defined, tells how many mantissa bits
7661 there are in long double precision floating point format.
7662 Note that this can be \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR minus one,
7663 since \f(CW\*(C`LDBL_MANT_DIG\*(C'\fR can include the \f(CW\*(C`IEEE\*(C'\fR 754 implicit bit.
7664 The common x86\-style 80\-bit long double does not have
7665 an implicit bit.
7666 .ie n .IP """LONGDBLNANBYTES""" 4
7667 .el .IP \f(CWLONGDBLNANBYTES\fR 4
7668 .IX Xref "LONGDBLNANBYTES"
7669 .IX Item "LONGDBLNANBYTES"
7670 This symbol, if defined, is a comma\-separated list of
7671 hexadecimal bytes (0xHH) for the long double precision not\-a\-number.
7672 .ie n .IP """NV""" 4
7673 .el .IP \f(CWNV\fR 4
7674 .IX Item "NV"
7675 Described in perlguts.
7676 .ie n .IP """NV_OVERFLOWS_INTEGERS_AT""" 4
7677 .el .IP \f(CWNV_OVERFLOWS_INTEGERS_AT\fR 4
7678 .IX Xref "NV_OVERFLOWS_INTEGERS_AT"
7679 .IX Item "NV_OVERFLOWS_INTEGERS_AT"
7680 This symbol gives the largest integer value that NVs can hold. This
7681 value + 1.0 cannot be stored accurately. It is expressed as constant
7682 floating point expression to reduce the chance of decimal/binary
7683 conversion issues. If it can not be determined, the value 0 is given.
7684 .ie n .IP """NV_PRESERVES_UV""" 4
7685 .el .IP \f(CWNV_PRESERVES_UV\fR 4
7686 .IX Xref "NV_PRESERVES_UV"
7687 .IX Item "NV_PRESERVES_UV"
7688 This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
7689 can preserve all the bits of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR.
7690 .ie n .IP """NV_PRESERVES_UV_BITS""" 4
7691 .el .IP \f(CWNV_PRESERVES_UV_BITS\fR 4
7692 .IX Xref "NV_PRESERVES_UV_BITS"
7693 .IX Item "NV_PRESERVES_UV_BITS"
7694 This symbol contains the number of bits a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
7695 can preserve of a variable of type \f(CW\*(C`UVTYPE\*(C'\fR.
7696 .ie n .IP """NV_ZERO_IS_ALLBITS_ZERO""" 4
7697 .el .IP \f(CWNV_ZERO_IS_ALLBITS_ZERO\fR 4
7698 .IX Xref "NV_ZERO_IS_ALLBITS_ZERO"
7699 .IX Item "NV_ZERO_IS_ALLBITS_ZERO"
7700 This symbol, if defined, indicates that a variable of type \f(CW\*(C`NVTYPE\*(C'\fR
7701 stores 0.0 in memory as all bits zero.
7702 .ie n .IP """NVMANTBITS""" 4
7703 .el .IP \f(CWNVMANTBITS\fR 4
7704 .IX Xref "NVMANTBITS"
7705 .IX Item "NVMANTBITS"
7706 This symbol, if defined, tells how many mantissa bits
7707 (not including implicit bit) there are in a Perl NV.
7708 This depends on which floating point type was chosen.
7709 .ie n .IP """NVSIZE""" 4
7710 .el .IP \f(CWNVSIZE\fR 4
7711 .IX Xref "NVSIZE"
7712 .IX Item "NVSIZE"
7713 This symbol contains the \f(CWsizeof(NV)\fR.
7714 Note that some floating point formats have unused bytes.
7715 The most notable example is the x86* 80\-bit extended precision
7716 which comes in byte sizes of 12 and 16 (for 32 and 64 bit
7717 platforms, respectively), but which only uses 10 bytes.
7718 Perl compiled with \f(CW\*(C`\-Duselongdouble\*(C'\fR on x86* is like this.
7719 .ie n .IP """NVTYPE""" 4
7720 .el .IP \f(CWNVTYPE\fR 4
7721 .IX Xref "NVTYPE"
7722 .IX Item "NVTYPE"
7723 This symbol defines the C type used for Perl\*(Aqs NV.
7724 .SH "General Configuration"
7725 .IX Xref "PERL_GCC_BRACE_GROUPS_FORBIDDEN"
7726 .IX Header "General Configuration"
7727 This section contains configuration information not otherwise
7728 found in the more specialized sections of this document. At the
7729 end is a list of \f(CW\*(C`#defines\*(C'\fR whose name should be enough to tell
7730 you what they do, and a list of #defines which tell you if you
7731 need to \f(CW\*(C`#include\*(C'\fR files to get the corresponding functionality.
7732 .ie n .IP """ASCIIish""" 4
7733 .el .IP \f(CWASCIIish\fR 4
7734 .IX Xref "ASCIIish"
7735 .IX Item "ASCIIish"
7736 A preprocessor symbol that is defined iff the system is an ASCII platform; this
7737 symbol would not be defined on \f(CW"EBCDIC"\fR platforms.
7738 .RS 4
7739 .Sp
7740 .Vb 1
7741 \& #ifdef ASCIIish
7742 .Ve
7743 .RE
7744 .RS 4
7745 .RE
7746 .ie n .IP """BYTEORDER""" 4
7747 .el .IP \f(CWBYTEORDER\fR 4
7748 .IX Xref "BYTEORDER"
7749 .IX Item "BYTEORDER"
7750 This symbol holds the hexadecimal constant defined in byteorder,
7751 in a UV, i.e. 0x1234 or 0x4321 or 0x12345678, etc...
7752 If the compiler supports cross\-compiling or multiple\-architecture
7753 binaries, use compiler\-defined macros to
7754 determine the byte order.
7755 .ie n .IP """CAT2""" 4
7756 .el .IP \f(CWCAT2\fR 4
7757 .IX Xref "CAT2"
7758 .IX Item "CAT2"
7759 This macro concatenates 2 tokens together.
7760 .RS 4
7761 .Sp
7762 .Vb 1
7763 \& token CAT2(token x, token y)
7764 .Ve
7765 .RE
7766 .RS 4
7767 .RE
7768 .ie n .IP """CHARBITS""" 4
7769 .el .IP \f(CWCHARBITS\fR 4
7770 .IX Xref "CHARBITS"
7771 .IX Item "CHARBITS"
7772 This symbol contains the size of a char, so that the C preprocessor
7773 can make decisions based on it.
7774 .ie n .IP """DB_VERSION_MAJOR_CFG""" 4
7775 .el .IP \f(CWDB_VERSION_MAJOR_CFG\fR 4
7776 .IX Xref "DB_VERSION_MAJOR_CFG"
7777 .IX Item "DB_VERSION_MAJOR_CFG"
7778 This symbol, if defined, defines the major version number of
7779 Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
7780 .ie n .IP """DB_VERSION_MINOR_CFG""" 4
7781 .el .IP \f(CWDB_VERSION_MINOR_CFG\fR 4
7782 .IX Xref "DB_VERSION_MINOR_CFG"
7783 .IX Item "DB_VERSION_MINOR_CFG"
7784 This symbol, if defined, defines the minor version number of
7785 Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
7786 For DB version 1 this is always 0.
7787 .ie n .IP """DB_VERSION_PATCH_CFG""" 4
7788 .el .IP \f(CWDB_VERSION_PATCH_CFG\fR 4
7789 .IX Xref "DB_VERSION_PATCH_CFG"
7790 .IX Item "DB_VERSION_PATCH_CFG"
7791 This symbol, if defined, defines the patch version number of
7792 Berkeley DB found in the \fIdb.h\fR header when Perl was configured.
7793 For DB version 1 this is always 0.
7794 .ie n .IP """DEFAULT_INC_EXCLUDES_DOT""" 4
7795 .el .IP \f(CWDEFAULT_INC_EXCLUDES_DOT\fR 4
7796 .IX Xref "DEFAULT_INC_EXCLUDES_DOT"
7797 .IX Item "DEFAULT_INC_EXCLUDES_DOT"
7798 This symbol, if defined, removes the legacy default behavior of
7799 including \*(Aq.\*(Aq at the end of @\f(CW\*(C`INC\*(C'\fR.
7800 .ie n .IP """DLSYM_NEEDS_UNDERSCORE""" 4
7801 .el .IP \f(CWDLSYM_NEEDS_UNDERSCORE\fR 4
7802 .IX Xref "DLSYM_NEEDS_UNDERSCORE"
7803 .IX Item "DLSYM_NEEDS_UNDERSCORE"
7804 This symbol, if defined, indicates that we need to prepend an
7805 underscore to the symbol name before calling \f(CWdlsym()\fR. This only
7806 makes sense if you *have* dlsym, which we will presume is the
7807 case if you\*(Aqre using \fIdl_dlopen.xs\fR.
7808 .ie n .IP """Drand01""" 4
7809 .el .IP \f(CWDrand01\fR 4
7810 .IX Xref "Drand01"
7811 .IX Item "Drand01"
7812 This macro is to be used to generate uniformly distributed
7813 random numbers over the range [0., 1.[. You may have to supply
7814 an \*(Aqextern double \f(CWdrand48()\fR;\*(Aq in your program since SunOS 4.1.3
7815 doesn\*(Aqt provide you with anything relevant in its headers.
7816 See \f(CW"HAS_DRAND48_PROTO"\fR.
7817 .RS 4
7818 .Sp
7819 .Vb 1
7820 \& double Drand01()
7821 .Ve
7822 .RE
7823 .RS 4
7824 .RE
7825 .ie n .IP """EBCDIC""" 4
7826 .el .IP \f(CWEBCDIC\fR 4
7827 .IX Xref "EBCDIC"
7828 .IX Item "EBCDIC"
7829 This symbol, if defined, indicates that this system uses
7830 \&\f(CW\*(C`EBCDIC\*(C'\fR encoding.
7831 .ie n .IP """HAS_CSH""" 4
7832 .el .IP \f(CWHAS_CSH\fR 4
7833 .IX Xref "HAS_CSH"
7834 .IX Item "HAS_CSH"
7835 This symbol, if defined, indicates that the C\-shell exists.
7836 .ie n .IP """HAS_GETHOSTNAME""" 4
7837 .el .IP \f(CWHAS_GETHOSTNAME\fR 4
7838 .IX Xref "HAS_GETHOSTNAME"
7839 .IX Item "HAS_GETHOSTNAME"
7840 This symbol, if defined, indicates that the C program may use the
7841 \&\f(CWgethostname()\fR routine to derive the host name. See also \f(CW"HAS_UNAME"\fR
7842 and \f(CW"PHOSTNAME"\fR.
7843 .ie n .IP """HAS_GNULIBC""" 4
7844 .el .IP \f(CWHAS_GNULIBC\fR 4
7845 .IX Xref "HAS_GNULIBC"
7846 .IX Item "HAS_GNULIBC"
7847 This symbol, if defined, indicates to the C program that
7848 the \f(CW\*(C`GNU\*(C'\fR C library is being used. A better check is to use
7849 the \f(CW\*(C`_\|_GLIBC_\|_\*(C'\fR and \f(CW\*(C`_\|_GLIBC_MINOR_\|_\*(C'\fR symbols supplied with glibc.
7850 .ie n .IP """HAS_LGAMMA""" 4
7851 .el .IP \f(CWHAS_LGAMMA\fR 4
7852 .IX Xref "HAS_LGAMMA"
7853 .IX Item "HAS_LGAMMA"
7854 This symbol, if defined, indicates that the \f(CW\*(C`lgamma\*(C'\fR routine is
7855 available to do the log gamma function. See also \f(CW"HAS_TGAMMA"\fR and
7856 \&\f(CW"HAS_LGAMMA_R"\fR.
7857 .ie n .IP """HAS_LGAMMA_R""" 4
7858 .el .IP \f(CWHAS_LGAMMA_R\fR 4
7859 .IX Xref "HAS_LGAMMA_R"
7860 .IX Item "HAS_LGAMMA_R"
7861 This symbol, if defined, indicates that the \f(CW\*(C`lgamma_r\*(C'\fR routine is
7862 available to do the log gamma function without using the global
7863 signgam variable.
7864 .ie n .IP """HAS_NON_INT_BITFIELDS""" 4
7865 .el .IP \f(CWHAS_NON_INT_BITFIELDS\fR 4
7866 .IX Xref "HAS_NON_INT_BITFIELDS"
7867 .IX Item "HAS_NON_INT_BITFIELDS"
7868 This symbol, if defined, indicates that the C compiler accepts, without
7869 error or warning, \f(CW\*(C`struct bitfields\*(C'\fR that are declared with sizes other
7870 than plain \*(Aqint\*(Aq; for example \*(Aqunsigned char\*(Aq is accepted.
7871 .ie n .IP """HAS_PRCTL_SET_NAME""" 4
7872 .el .IP \f(CWHAS_PRCTL_SET_NAME\fR 4
7873 .IX Xref "HAS_PRCTL_SET_NAME"
7874 .IX Item "HAS_PRCTL_SET_NAME"
7875 This symbol, if defined, indicates that the prctl routine is
7876 available to set process title and supports \f(CW\*(C`PR_SET_NAME\*(C'\fR.
7877 .ie n .IP """HAS_PROCSELFEXE""" 4
7878 .el .IP \f(CWHAS_PROCSELFEXE\fR 4
7879 .IX Xref "HAS_PROCSELFEXE"
7880 .IX Item "HAS_PROCSELFEXE"
7881 This symbol is defined if \f(CW\*(C`PROCSELFEXE_PATH\*(C'\fR is a symlink
7882 to the absolute pathname of the executing program.
7883 .ie n .IP """HAS_PSEUDOFORK""" 4
7884 .el .IP \f(CWHAS_PSEUDOFORK\fR 4
7885 .IX Xref "HAS_PSEUDOFORK"
7886 .IX Item "HAS_PSEUDOFORK"
7887 This symbol, if defined, indicates that an emulation of the
7888 fork routine is available.
7889 .ie n .IP """HAS_REGCOMP""" 4
7890 .el .IP \f(CWHAS_REGCOMP\fR 4
7891 .IX Xref "HAS_REGCOMP"
7892 .IX Item "HAS_REGCOMP"
7893 This symbol, if defined, indicates that the \f(CWregcomp()\fR routine is
7894 available to do some regular pattern matching (usually on \f(CW\*(C`POSIX\*(C'\fR.2
7895 conforming systems).
7896 .ie n .IP """HAS_SETPGID""" 4
7897 .el .IP \f(CWHAS_SETPGID\fR 4
7898 .IX Xref "HAS_SETPGID"
7899 .IX Item "HAS_SETPGID"
7900 This symbol, if defined, indicates that the \f(CW\*(C`setpgid(pid, gpid)\*(C'\fR
7901 routine is available to set process group ID.
7902 .ie n .IP """HAS_SIGSETJMP""" 4
7903 .el .IP \f(CWHAS_SIGSETJMP\fR 4
7904 .IX Xref "HAS_SIGSETJMP"
7905 .IX Item "HAS_SIGSETJMP"
7906 This variable indicates to the C program that the \f(CWsigsetjmp()\fR
7907 routine is available to save the calling process\*(Aqs registers
7908 and stack environment for later use by \f(CWsiglongjmp()\fR, and
7909 to optionally save the process\*(Aqs signal mask. See
7910 \&\f(CW"Sigjmp_buf"\fR, \f(CW"Sigsetjmp"\fR, and \f(CW"Siglongjmp"\fR.
7911 .ie n .IP """HAS_STRUCT_CMSGHDR""" 4
7912 .el .IP \f(CWHAS_STRUCT_CMSGHDR\fR 4
7913 .IX Xref "HAS_STRUCT_CMSGHDR"
7914 .IX Item "HAS_STRUCT_CMSGHDR"
7915 This symbol, if defined, indicates that the \f(CW\*(C`struct cmsghdr\*(C'\fR
7916 is supported.
7917 .ie n .IP """HAS_STRUCT_MSGHDR""" 4
7918 .el .IP \f(CWHAS_STRUCT_MSGHDR\fR 4
7919 .IX Xref "HAS_STRUCT_MSGHDR"
7920 .IX Item "HAS_STRUCT_MSGHDR"
7921 This symbol, if defined, indicates that the \f(CW\*(C`struct msghdr\*(C'\fR
7922 is supported.
7923 .ie n .IP """HAS_TGAMMA""" 4
7924 .el .IP \f(CWHAS_TGAMMA\fR 4
7925 .IX Xref "HAS_TGAMMA"
7926 .IX Item "HAS_TGAMMA"
7927 This symbol, if defined, indicates that the \f(CW\*(C`tgamma\*(C'\fR routine is
7928 available to do the gamma function. See also \f(CW"HAS_LGAMMA"\fR.
7929 .ie n .IP """HAS_UNAME""" 4
7930 .el .IP \f(CWHAS_UNAME\fR 4
7931 .IX Xref "HAS_UNAME"
7932 .IX Item "HAS_UNAME"
7933 This symbol, if defined, indicates that the C program may use the
7934 \&\f(CWuname()\fR routine to derive the host name. See also \f(CW"HAS_GETHOSTNAME"\fR
7935 and \f(CW"PHOSTNAME"\fR.
7936 .ie n .IP """HAS_UNION_SEMUN""" 4
7937 .el .IP \f(CWHAS_UNION_SEMUN\fR 4
7938 .IX Xref "HAS_UNION_SEMUN"
7939 .IX Item "HAS_UNION_SEMUN"
7940 This symbol, if defined, indicates that the \f(CW\*(C`union semun\*(C'\fR is
7941 defined by including \fIsys/sem.h\fR. If not, the user code
7942 probably needs to define it as:
7943 .Sp
7944 .Vb 5
7945 \& union semun {
7946 \& int val;
7947 \& struct semid_ds *buf;
7948 \& unsigned short *array;
7949 \& }
7950 .Ve
7951 .ie n .IP """I_DIRENT""" 4
7952 .el .IP \f(CWI_DIRENT\fR 4
7953 .IX Xref "I_DIRENT"
7954 .IX Item "I_DIRENT"
7955 This symbol, if defined, indicates to the C program that it should
7956 include \fIdirent.h\fR. Using this symbol also triggers the definition
7957 of the \f(CW\*(C`Direntry_t\*(C'\fR define which ends up being \*(Aq\f(CW\*(C`struct dirent\*(C'\fR\*(Aq or
7958 \&\*(Aq\f(CW\*(C`struct direct\*(C'\fR\*(Aq depending on the availability of \fIdirent.h\fR.
7959 .RS 4
7960 .Sp
7961 .Vb 3
7962 \& #ifdef I_DIRENT
7963 \& #include <dirent.h>
7964 \& #endif
7965 .Ve
7966 .RE
7967 .RS 4
7968 .RE
7969 .ie n .IP """I_POLL""" 4
7970 .el .IP \f(CWI_POLL\fR 4
7971 .IX Xref "I_POLL"
7972 .IX Item "I_POLL"
7973 This symbol, if defined, indicates that \fIpoll.h\fR exists and
7974 should be included. (see also \f(CW"HAS_POLL"\fR)
7975 .RS 4
7976 .Sp
7977 .Vb 3
7978 \& #ifdef I_POLL
7979 \& #include <poll.h>
7980 \& #endif
7981 .Ve
7982 .RE
7983 .RS 4
7984 .RE
7985 .ie n .IP """I_SYS_RESOURCE""" 4
7986 .el .IP \f(CWI_SYS_RESOURCE\fR 4
7987 .IX Xref "I_SYS_RESOURCE"
7988 .IX Item "I_SYS_RESOURCE"
7989 This symbol, if defined, indicates to the C program that it should
7990 include \fIsys/resource.h\fR.
7991 .RS 4
7992 .Sp
7993 .Vb 3
7994 \& #ifdef I_SYS_RESOURCE
7995 \& #include <sys_resource.h>
7996 \& #endif
7997 .Ve
7998 .RE
7999 .RS 4
8000 .RE
8001 .ie n .IP """LIBM_LIB_VERSION""" 4
8002 .el .IP \f(CWLIBM_LIB_VERSION\fR 4
8003 .IX Xref "LIBM_LIB_VERSION"
8004 .IX Item "LIBM_LIB_VERSION"
8005 This symbol, if defined, indicates that libm exports \f(CW\*(C`_LIB_VERSION\*(C'\fR
8006 and that \fImath.h\fR defines the enum to manipulate it.
8007 .ie n .IP """NEED_VA_COPY""" 4
8008 .el .IP \f(CWNEED_VA_COPY\fR 4
8009 .IX Item "NEED_VA_COPY"
8010 This symbol, if defined, indicates that the system stores
8011 the variable argument list datatype, \f(CW\*(C`va_list\*(C'\fR, in a format
8012 that cannot be copied by simple assignment, so that some
8013 other means must be used when copying is required.
8014 As such systems vary in their provision (or non\-provision)
8015 of copying mechanisms, \fIhandy.h\fR defines a platform\-
8016 independent macro, \f(CW\*(C`Perl_va_copy(src, dst)\*(C'\fR, to do the job.
8017 .ie n .IP """OSNAME""" 4
8018 .el .IP \f(CWOSNAME\fR 4
8019 .IX Xref "OSNAME"
8020 .IX Item "OSNAME"
8021 This symbol contains the name of the operating system, as determined
8022 by Configure. You shouldn\*(Aqt rely on it too much; the specific
8023 feature tests from Configure are generally more reliable.
8024 .ie n .IP """OSVERS""" 4
8025 .el .IP \f(CWOSVERS\fR 4
8026 .IX Xref "OSVERS"
8027 .IX Item "OSVERS"
8028 This symbol contains the version of the operating system, as determined
8029 by Configure. You shouldn\*(Aqt rely on it too much; the specific
8030 feature tests from Configure are generally more reliable.
8031 .ie n .IP """PERL_USE_GCC_BRACE_GROUPS""" 4
8032 .el .IP \f(CWPERL_USE_GCC_BRACE_GROUPS\fR 4
8033 .IX Xref "PERL_USE_GCC_BRACE_GROUPS"
8034 .IX Item "PERL_USE_GCC_BRACE_GROUPS"
8035 This C pre\-processor value, if defined, indicates that it is permissible to use
8036 the GCC brace groups extension. However, use of this extension is DISCOURAGED.
8037 Use a \f(CW\*(C`static inline\*(C'\fR function instead.
8038 .Sp
8039 The extension, of the form
8040 .Sp
8041 .Vb 1
8042 \& ({ statement ... })
8043 .Ve
8044 .Sp
8045 turns the block consisting of \fIstatement ...\fR into an expression with a
8046 value, unlike plain C language blocks. This can present optimization
8047 possibilities, \fBBUT\fR, unless you know for sure that this will never be
8048 compiled without this extension being available and not forbidden, you need to
8049 specify an alternative. Thus two code paths have to be maintained, which can
8050 get out\-of\-sync. All these issues are solved by using a \f(CW\*(C`static inline\*(C'\fR
8051 function instead.
8052 .Sp
8053 Perl can be configured to not use this feature by passing the parameter
8054 \&\f(CW\*(C`\-Accflags=\-DPERL_GCC_BRACE_GROUPS_FORBIDDEN\*(C'\fR to \fIConfigure\fR.
8055 .RS 4
8056 .Sp
8057 .Vb 1
8058 \& #ifdef PERL_USE_GCC_BRACE_GROUPS
8059 .Ve
8060 .RE
8061 .RS 4
8062 .RE
8063 .ie n .IP """PHOSTNAME""" 4
8064 .el .IP \f(CWPHOSTNAME\fR 4
8065 .IX Xref "PHOSTNAME"
8066 .IX Item "PHOSTNAME"
8067 This symbol, if defined, indicates the command to feed to the
8068 \&\f(CWpopen()\fR routine to derive the host name. See also \f(CW"HAS_GETHOSTNAME"\fR
8069 and \f(CW"HAS_UNAME"\fR. Note that the command uses a fully qualified path,
8070 so that it is safe even if used by a process with super\-user
8071 privileges.
8072 .ie n .IP """PROCSELFEXE_PATH""" 4
8073 .el .IP \f(CWPROCSELFEXE_PATH\fR 4
8074 .IX Xref "PROCSELFEXE_PATH"
8075 .IX Item "PROCSELFEXE_PATH"
8076 If \f(CW\*(C`HAS_PROCSELFEXE\*(C'\fR is defined this symbol is the filename
8077 of the symbolic link pointing to the absolute pathname of
8078 the executing program.
8079 .ie n .IP """PTRSIZE""" 4
8080 .el .IP \f(CWPTRSIZE\fR 4
8081 .IX Xref "PTRSIZE"
8082 .IX Item "PTRSIZE"
8083 This symbol contains the size of a pointer, so that the C preprocessor
8084 can make decisions based on it. It will be \f(CW\*(C`sizeof(void *)\*(C'\fR if
8085 the compiler supports (void *); otherwise it will be
8086 \&\f(CW\*(C`sizeof(char *)\*(C'\fR.
8087 .ie n .IP """RANDBITS""" 4
8088 .el .IP \f(CWRANDBITS\fR 4
8089 .IX Xref "RANDBITS"
8090 .IX Item "RANDBITS"
8091 This symbol indicates how many bits are produced by the
8092 function used to generate normalized random numbers.
8093 Values include 15, 16, 31, and 48.
8094 .ie n .IP """seedDrand01""" 4
8095 .el .IP \f(CWseedDrand01\fR 4
8096 .IX Xref "seedDrand01"
8097 .IX Item "seedDrand01"
8098 This symbol defines the macro to be used in seeding the
8099 random number generator (see \f(CW"Drand01"\fR).
8100 .RS 4
8101 .Sp
8102 .Vb 1
8103 \& void seedDrand01(Rand_seed_t x)
8104 .Ve
8105 .RE
8106 .RS 4
8107 .RE
8108 .ie n .IP """SELECT_MIN_BITS""" 4
8109 .el .IP \f(CWSELECT_MIN_BITS\fR 4
8110 .IX Xref "SELECT_MIN_BITS"
8111 .IX Item "SELECT_MIN_BITS"
8112 This symbol holds the minimum number of bits operated by select.
8113 That is, if you do \f(CW\*(C`select(n, ...)\*(C'\fR, how many bits at least will be
8114 cleared in the masks if some activity is detected. Usually this
8115 is either n or 32*\f(CWceil(n/32)\fR, especially many little\-endians do
8116 the latter. This is only useful if you have \f(CWselect()\fR, naturally.
8117 .ie n .IP """SETUID_SCRIPTS_ARE_SECURE_NOW""" 4
8118 .el .IP \f(CWSETUID_SCRIPTS_ARE_SECURE_NOW\fR 4
8119 .IX Xref "SETUID_SCRIPTS_ARE_SECURE_NOW"
8120 .IX Item "SETUID_SCRIPTS_ARE_SECURE_NOW"
8121 This symbol, if defined, indicates that the bug that prevents
8122 setuid scripts from being secure is not present in this kernel.
8123 .ie n .IP """ST_DEV_SIGN""" 4
8124 .el .IP \f(CWST_DEV_SIGN\fR 4
8125 .IX Xref "ST_DEV_SIGN"
8126 .IX Item "ST_DEV_SIGN"
8127 This symbol holds the signedness of \f(CW\*(C`struct stat\*(C'\fR\*(Aqs \f(CW\*(C`st_dev\*(C'\fR.
8128 1 for unsigned, \-1 for signed.
8129 .ie n .IP """ST_DEV_SIZE""" 4
8130 .el .IP \f(CWST_DEV_SIZE\fR 4
8131 .IX Xref "ST_DEV_SIZE"
8132 .IX Item "ST_DEV_SIZE"
8133 This variable contains the size of \f(CW\*(C`struct stat\*(C'\fR\*(Aqs \f(CW\*(C`st_dev\*(C'\fR in bytes.
8134 .ie n .IP """STRINGIFY""" 4
8135 .el .IP \f(CWSTRINGIFY\fR 4
8136 .IX Xref "STRINGIFY"
8137 .IX Item "STRINGIFY"
8138 This macro surrounds its token with double quotes.
8139 .RS 4
8140 .Sp
8141 .Vb 1
8142 \& string STRINGIFY(token x)
8143 .Ve
8144 .RE
8145 .RS 4
8146 .RE
8147 .ie n .SS "List of capability ""HAS_\fIfoo\fP"" symbols"
8148 .el .SS "List of capability \f(CWHAS_\fP\f(CIfoo\fP\f(CW\fP symbols"
8149 .IX Subsection "List of capability HAS_foo symbols"
8150 This is a list of those symbols that dont appear elsewhere in ths
8151 document that indicate if the current platform has a certain
8152 capability. Their names all begin with \f(CW\*(C`HAS_\*(C'\fR. Only those
8153 symbols whose capability is directly derived from the name are
8154 listed here. All others have their meaning expanded out elsewhere
8155 in this document. This (relatively) compact list is because we
8156 think that the expansion would add little or no value and take up
8157 a lot of space (because there are so many). If you think certain
8158 ones should be expanded, send email to
8159 perl5\[email protected] <mailto:[email protected]>.
8160 .PP
8161 Each symbol here will be \f(CW\*(C`#define\*(C'\fRd if and only if the platform
8162 has the capability. If you need more detail, see the
8163 corresponding entry in \fIconfig.h\fR. For convenience, the list is
8164 split so that the ones that indicate there is a reentrant version
8165 of a capability are listed separately
8166 .PP
8167 \&\f(CW\*(C`HAS_\|_FWALK\*(C'\fR,\ \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_FD_SET\*(C'\fR,\ \f(CW\*(C`HAS_FDIM\*(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_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_SYS_ERRLIST\*(C'\fR,\ \f(CW\*(C`HAS_SYSCALL\*(C'\fR,\ \f(CW\*(C`HAS_SYSCONF\*(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
8168 .PP
8169 And, the reentrant capabilities:
8170 .PP
8171 \&\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
8172 .PP
8173 Example usage:
8174 .Sp
8175 .Vb 5
8176 \& #ifdef HAS_STRNLEN
8177 \& use strnlen()
8178 \& #else
8179 \& use an alternative implementation
8180 \& #endif
8181 .Ve
8182 .ie n .SS "List of ""#include"" needed symbols"
8183 .el .SS "List of \f(CW#include\fP needed symbols"
8184 .IX Subsection "List of #include needed symbols"
8185 This list contains symbols that indicate if certain \f(CW\*(C`#include\*(C'\fR
8186 files are present on the platform. If your code accesses the
8187 functionality that one of these is for, you will need to
8188 \&\f(CW\*(C`#include\*(C'\fR it if the symbol on this list is \f(CW\*(C`#define\*(C'\fRd. For
8189 more detail, see the corresponding entry in \fIconfig.h\fR.
8190 .PP
8191 \&\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_GDBM_NDBM\*(C'\fR,\ \f(CW\*(C`I_GDBMNDBM\*(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_NET_ERRNO\*(C'\fR,\ \f(CW\*(C`I_NETDB\*(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_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_SYS_UN\*(C'\fR,\ \f(CW\*(C`I_SYS_VFS\*(C'\fR,\ \f(CW\*(C`I_SYS_WAIT\*(C'\fR,\ \f(CW\*(C`I_SYSLOG\*(C'\fR,\ \f(CW\*(C`I_SYSMODE\*(C'\fR,\ \f(CW\*(C`I_SYSUIO\*(C'\fR,\ \f(CW\*(C`I_SYSUTSNAME\*(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
8192 .PP
8193 Example usage:
8194 .Sp
8195 .Vb 3
8196 \& #ifdef I_WCHAR
8197 \& #include <wchar.h>
8198 \& #endif
8199 .Ve
8200 .SH "Global Variables"
8201 .IX Header "Global Variables"
8202 These variables are global to an entire process. They are shared between
8203 all interpreters and all threads in a process. Any variables not documented
8204 here may be changed or removed without notice, so don\*(Aqt use them!
8205 If you feel you really do need to use an unlisted variable, first send email to
8206 perl5\[email protected] <mailto:[email protected]>. It may be that
8207 someone there will point out a way to accomplish what you need without using an
8208 internal variable. But if not, you should get a go\-ahead to document and then
8209 use the variable.
8210 .ie n .IP """PL_check""" 4
8211 .el .IP \f(CWPL_check\fR 4
8212 .IX Xref "PL_check"
8213 .IX Item "PL_check"
8214 Array, indexed by opcode, of functions that will be called for the "check"
8215 phase of optree building during compilation of Perl code. For most (but
8216 not all) types of op, once the op has been initially built and populated
8217 with child ops it will be filtered through the check function referenced
8218 by the appropriate element of this array. The new op is passed in as the
8219 sole argument to the check function, and the check function returns the
8220 completed op. The check function may (as the name suggests) check the op
8221 for validity and signal errors. It may also initialise or modify parts of
8222 the ops, or perform more radical surgery such as adding or removing child
8223 ops, or even throw the op away and return a different op in its place.
8224 .Sp
8225 This array of function pointers is a convenient place to hook into the
8226 compilation process. An XS module can put its own custom check function
8227 in place of any of the standard ones, to influence the compilation of a
8228 particular type of op. However, a custom check function must never fully
8229 replace a standard check function (or even a custom check function from
8230 another module). A module modifying checking must instead \fBwrap\fR the
8231 preexisting check function. A custom check function must be selective
8232 about when to apply its custom behaviour. In the usual case where
8233 it decides not to do anything special with an op, it must chain the
8234 preexisting op function. Check functions are thus linked in a chain,
8235 with the core\*(Aqs base checker at the end.
8236 .Sp
8237 For thread safety, modules should not write directly to this array.
8238 Instead, use the function "wrap_op_checker".
8239 .ie n .IP """PL_infix_plugin""" 4
8240 .el .IP \f(CWPL_infix_plugin\fR 4
8241 .IX Xref "PL_infix_plugin"
8242 .IX Item "PL_infix_plugin"
8243 NOTE: \f(CW\*(C`PL_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be
8244 removed without notice.
8245 .Sp
8246 \&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module
8247 \&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make
8248 use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing
8249 of new infix operators.
8250 .Sp
8251 Function pointer, pointing at a function used to handle extended infix
8252 operators. The function should be declared as
8253 .Sp
8254 .Vb 3
8255 \& int infix_plugin_function(pTHX_
8256 \& char *opname, STRLEN oplen,
8257 \& struct Perl_custom_infix **infix_ptr)
8258 .Ve
8259 .Sp
8260 The function is called from the tokenizer whenever a possible infix operator
8261 is seen. \f(CW\*(C`opname\*(C'\fR points to the operator name in the parser\*(Aqs input buffer,
8262 and \f(CW\*(C`oplen\*(C'\fR gives the \fImaximum\fR number of bytes of it that should be
8263 consumed; it is not null\-terminated. The function is expected to examine the
8264 operator name and possibly other state such as %^H, to
8265 determine whether it wants to handle the operator name.
8266 .Sp
8267 As compared to the single stage of \f(CW\*(C`PL_keyword_plugin\*(C'\fR, parsing of additional
8268 infix operators occurs in three separate stages. This is because of the more
8269 complex interactions it has with the parser, to ensure that operator
8270 precedence rules work correctly. These stages are co\-ordinated by the use of
8271 an additional information structure.
8272 .Sp
8273 If the function wants to handle the infix operator, it must set the variable
8274 pointed to by \f(CW\*(C`infix_ptr\*(C'\fR to the address of a structure that provides this
8275 additional information about the subsequent parsing stages. If it does not,
8276 it should make a call to the next function in the chain.
8277 .Sp
8278 This structure has the following definition:
8279 .Sp
8280 .Vb 7
8281 \& struct Perl_custom_infix {
8282 \& enum Perl_custom_infix_precedence prec;
8283 \& void (*parse)(pTHX_ SV **opdata,
8284 \& struct Perl_custom_infix *);
8285 \& OP *(*build_op)(pTHX_ SV **opdata, OP *lhs, OP *rhs,
8286 \& struct Perl_custom_infix *);
8287 \& };
8288 .Ve
8289 .Sp
8290 The function must then return an integer giving the number of bytes consumed
8291 by the name of this operator. In the case of an operator whose name is
8292 composed of identifier characters, this must be equal to \f(CW\*(C`oplen\*(C'\fR. In the case
8293 of an operator named by non\-identifier characters, this is permitted to be
8294 shorter than \f(CW\*(C`oplen\*(C'\fR, and any additional characters after it will not be
8295 claimed by the infix operator but instead will be consumed by the tokenizer
8296 and parser as normal.
8297 .Sp
8298 If the optional \f(CW\*(C`parse\*(C'\fR function is provided, it is called immediately by the
8299 parser to let the operator\*(Aqs definition consume any additional syntax from the
8300 source code. This should \fInot\fR be used for normal operand parsing, but it may
8301 be useful when implementing things like parametric operators or meta\-operators
8302 that consume more syntax themselves. This function may use the variable
8303 pointed to by \f(CW\*(C`opdata\*(C'\fR to provide an SV containing additional data to be
8304 passed into the \f(CW\*(C`build_op\*(C'\fR function later on.
8305 .Sp
8306 The information structure gives the operator precedence level in the \f(CW\*(C`prec\*(C'\fR
8307 field. This is used to tell the parser how much of the surrounding syntax
8308 before and after should be considered as operands to the operator.
8309 .Sp
8310 The tokenizer and parser will then continue to operate as normal until enough
8311 additional input has been parsed to form both the left\- and right\-hand side
8312 operands to the operator, according to the precedence level. At this point the
8313 \&\f(CW\*(C`build_op\*(C'\fR function is called, being passed the left\- and right\-hand operands
8314 as optree fragments. It is expected to combine them into the resulting optree
8315 fragment, which it should return.
8316 .Sp
8317 After the \f(CW\*(C`build_op\*(C'\fR function has returned, if the variable pointed to by
8318 \&\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
8319 \&\f(CWSvREFCNT_dec()\fR.
8320 .Sp
8321 For thread safety, modules should not set this variable directly.
8322 Instead, use the function "wrap_infix_plugin".
8323 .Sp
8324 However, that all said, the introductory note above still applies. This
8325 variable is provided in core perl only for the benefit of the
8326 \&\f(CW\*(C`XS::Parse::Infix\*(C'\fR module. That module acts as a central registry for infix
8327 operators, automatically handling things like deparse support and
8328 discovery/reflection, and these abilities only work because it knows all the
8329 registered operators. Other modules should not use this interpreter variable
8330 directly to implement them because then those central features would no longer
8331 work properly.
8332 .Sp
8333 Furthermore, it is likely that this (experimental) API will be replaced in a
8334 future Perl version by a more complete API that fully implements the central
8335 registry and other semantics currently provided by \f(CW\*(C`XS::Parse::Infix\*(C'\fR, once
8336 the module has had sufficient experimental testing time. This current
8337 mechanism exists only as an interim measure to get to that stage.
8338 .ie n .IP """PL_keyword_plugin""" 4
8339 .el .IP \f(CWPL_keyword_plugin\fR 4
8340 .IX Xref "PL_keyword_plugin"
8341 .IX Item "PL_keyword_plugin"
8342 NOTE: \f(CW\*(C`PL_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be
8343 removed without notice.
8344 .Sp
8345 Function pointer, pointing at a function used to handle extended keywords.
8346 The function should be declared as
8347 .Sp
8348 .Vb 3
8349 \& int keyword_plugin_function(pTHX_
8350 \& char *keyword_ptr, STRLEN keyword_len,
8351 \& OP **op_ptr)
8352 .Ve
8353 .Sp
8354 The function is called from the tokeniser, whenever a possible keyword
8355 is seen. \f(CW\*(C`keyword_ptr\*(C'\fR points at the word in the parser\*(Aqs input
8356 buffer, and \f(CW\*(C`keyword_len\*(C'\fR gives its length; it is not null\-terminated.
8357 The function is expected to examine the word, and possibly other state
8358 such as %^H, to decide whether it wants to handle it
8359 as an extended keyword. If it does not, the function should return
8360 \&\f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR, and the normal parser process will continue.
8361 .Sp
8362 If the function wants to handle the keyword, it first must
8363 parse anything following the keyword that is part of the syntax
8364 introduced by the keyword. See "Lexer interface" for details.
8365 .Sp
8366 When a keyword is being handled, the plugin function must build
8367 a tree of \f(CW\*(C`OP\*(C'\fR structures, representing the code that was parsed.
8368 The root of the tree must be stored in \f(CW*op_ptr\fR. The function then
8369 returns a constant indicating the syntactic role of the construct that
8370 it has parsed: \f(CW\*(C`KEYWORD_PLUGIN_STMT\*(C'\fR if it is a complete statement, or
8371 \&\f(CW\*(C`KEYWORD_PLUGIN_EXPR\*(C'\fR if it is an expression. Note that a statement
8372 construct cannot be used inside an expression (except via \f(CW\*(C`do BLOCK\*(C'\fR
8373 and similar), and an expression is not a complete statement (it requires
8374 at least a terminating semicolon).
8375 .Sp
8376 When a keyword is handled, the plugin function may also have
8377 (compile\-time) side effects. It may modify \f(CW\*(C`%^H\*(C'\fR, define functions, and
8378 so on. Typically, if side effects are the main purpose of a handler,
8379 it does not wish to generate any ops to be included in the normal
8380 compilation. In this case it is still required to supply an op tree,
8381 but it suffices to generate a single null op.
8382 .Sp
8383 That\*(Aqs how the \f(CW*PL_keyword_plugin\fR function needs to behave overall.
8384 Conventionally, however, one does not completely replace the existing
8385 handler function. Instead, take a copy of \f(CW\*(C`PL_keyword_plugin\*(C'\fR before
8386 assigning your own function pointer to it. Your handler function should
8387 look for keywords that it is interested in and handle those. Where it
8388 is not interested, it should call the saved plugin function, passing on
8389 the arguments it received. Thus \f(CW\*(C`PL_keyword_plugin\*(C'\fR actually points
8390 at a chain of handler functions, all of which have an opportunity to
8391 handle keywords, and only the last function in the chain (built into
8392 the Perl core) will normally return \f(CW\*(C`KEYWORD_PLUGIN_DECLINE\*(C'\fR.
8393 .Sp
8394 For thread safety, modules should not set this variable directly.
8395 Instead, use the function "wrap_keyword_plugin".
8396 .ie n .IP """PL_phase""" 4
8397 .el .IP \f(CWPL_phase\fR 4
8398 .IX Xref "PL_phase"
8399 .IX Item "PL_phase"
8400 A value that indicates the current Perl interpreter\*(Aqs phase. Possible values
8401 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,
8402 \&\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
8403 \&\f(CW\*(C`PERL_PHASE_DESTRUCT\*(C'\fR.
8404 .Sp
8405 For example, the following determines whether the interpreter is in
8406 global destruction:
8407 .Sp
8408 .Vb 3
8409 \& if (PL_phase == PERL_PHASE_DESTRUCT) {
8410 \& // we are in global destruction
8411 \& }
8412 .Ve
8413 .Sp
8414 \&\f(CW\*(C`PL_phase\*(C'\fR was introduced in Perl 5.14; in prior perls you can use
8415 \&\f(CW\*(C`PL_dirty\*(C'\fR (boolean) to determine whether the interpreter is in global
8416 destruction. (Use of \f(CW\*(C`PL_dirty\*(C'\fR is discouraged since 5.14.)
8417 .RS 4
8418 .Sp
8419 .Vb 1
8420 \& enum perl_phase PL_phase
8421 .Ve
8422 .RE
8423 .RS 4
8424 .RE
8425 .SH "GV Handling and Stashes"
8426 .IX Xref "GV GV_ADD GV_ADDMG GV_ADDMULTI GV_ADDWARN GV_AUTOLOAD_ISMETHOD GV_NO_SVGMAGIC GV_NOADD_NOINIT GV_NOEXPAND GV_NOINIT GV_NOTQUAL GV_NOUNIVERSAL GV_SUPER SVf_UTF8"
8427 .IX Header "GV Handling and Stashes"
8428 A GV is a structure which corresponds to a Perl typeglob, \fIi.e.\fR, *foo.
8429 It is a structure that holds a pointer to a scalar, an array, a hash etc,
8430 corresponding to \f(CW$foo\fR, \f(CW@foo\fR, \f(CW%foo\fR.
8431 .PP
8432 GVs are usually found as values in stashes (symbol table hashes) where
8433 Perl stores its global variables.
8434 .PP
8435 A \fBstash\fR is a hash that contains all variables that are defined
8436 within a package. See "Stashes and Globs" in perlguts
8437 .ie n .IP """amagic_call""" 4
8438 .el .IP \f(CWamagic_call\fR 4
8439 .IX Xref "amagic_call"
8440 .IX Item "amagic_call"
8441 Perform the overloaded (active magic) operation given by \f(CW\*(C`method\*(C'\fR.
8442 \&\f(CW\*(C`method\*(C'\fR is one of the values found in \fIoverload.h\fR.
8443 .Sp
8444 \&\f(CW\*(C`flags\*(C'\fR affects how the operation is performed, as follows:
8445 .RS 4
8446 .ie n .IP """AMGf_noleft""" 4
8447 .el .IP \f(CWAMGf_noleft\fR 4
8448 .IX Item "AMGf_noleft"
8449 \&\f(CW\*(C`left\*(C'\fR is not to be used in this operation.
8450 .ie n .IP """AMGf_noright""" 4
8451 .el .IP \f(CWAMGf_noright\fR 4
8452 .IX Item "AMGf_noright"
8453 \&\f(CW\*(C`right\*(C'\fR is not to be used in this operation.
8454 .ie n .IP """AMGf_unary""" 4
8455 .el .IP \f(CWAMGf_unary\fR 4
8456 .IX Item "AMGf_unary"
8457 The operation is done only on just one operand.
8458 .ie n .IP """AMGf_assign""" 4
8459 .el .IP \f(CWAMGf_assign\fR 4
8460 .IX Item "AMGf_assign"
8461 The operation changes one of the operands, e.g., \f(CW$x\fR += 1
8462 .RE
8463 .RS 4
8464 .Sp
8465 .Vb 4
8466 \& SV * amagic_call( SV *left, SV *right, int method,
8467 \& int dir)
8468 \& SV * Perl_amagic_call(pTHX_ SV *left, SV *right, int method,
8469 \& int dir)
8470 .Ve
8471 .RE
8472 .RS 4
8473 .RE
8474 .ie n .IP """amagic_deref_call""" 4
8475 .el .IP \f(CWamagic_deref_call\fR 4
8476 .IX Xref "amagic_deref_call"
8477 .IX Item "amagic_deref_call"
8478 Perform \f(CW\*(C`method\*(C'\fR overloading dereferencing on \f(CW\*(C`ref\*(C'\fR, returning the
8479 dereferenced result. \f(CW\*(C`method\*(C'\fR must be one of the dereference operations given
8480 in \fIoverload.h\fR.
8481 .Sp
8482 If overloading is inactive on \f(CW\*(C`ref\*(C'\fR, returns \f(CW\*(C`ref\*(C'\fR itself.
8483 .RS 4
8484 .Sp
8485 .Vb 2
8486 \& SV * amagic_deref_call( SV *ref, int method)
8487 \& SV * Perl_amagic_deref_call(pTHX_ SV *ref, int method)
8488 .Ve
8489 .RE
8490 .RS 4
8491 .RE
8492 .ie n .IP """gv_add_by_type""" 4
8493 .el .IP \f(CWgv_add_by_type\fR 4
8494 .IX Xref "gv_add_by_type"
8495 .IX Item "gv_add_by_type"
8496 Make sure there is a slot of type \f(CW\*(C`type\*(C'\fR in the GV \f(CW\*(C`gv\*(C'\fR.
8497 .RS 4
8498 .Sp
8499 .Vb 2
8500 \& GV * gv_add_by_type( GV *gv, svtype type)
8501 \& GV * Perl_gv_add_by_type(pTHX_ GV *gv, svtype type)
8502 .Ve
8503 .RE
8504 .RS 4
8505 .RE
8506 .ie n .IP """Gv_AMupdate""" 4
8507 .el .IP \f(CWGv_AMupdate\fR 4
8508 .IX Xref "Gv_AMupdate"
8509 .IX Item "Gv_AMupdate"
8510 Recalculates overload magic in the package given by \f(CW\*(C`stash\*(C'\fR.
8511 .Sp
8512 Returns:
8513 .RS 4
8514 .IP "1 on success and there is some overload" 4
8515 .IX Item "1 on success and there is some overload"
8516 .PD 0
8517 .IP "0 if there is no overload" 4
8518 .IX Item "0 if there is no overload"
8519 .ie n .IP "\-1 if some error occurred and it couldn\*(Aqt croak (because ""destructing"" is true)." 4
8520 .el .IP "\-1 if some error occurred and it couldn\*(Aqt croak (because \f(CWdestructing\fR is true)." 4
8521 .IX Item "-1 if some error occurred and it couldn't croak (because destructing is true)."
8522 .PD
8523 .RE
8524 .RS 4
8525 .Sp
8526 .Vb 2
8527 \& int Gv_AMupdate( HV *stash, bool destructing)
8528 \& int Perl_Gv_AMupdate(pTHX_ HV *stash, bool destructing)
8529 .Ve
8530 .RE
8531 .RS 4
8532 .RE
8533 .ie n .IP """gv_autoload_pv""" 4
8534 .el .IP \f(CWgv_autoload_pv\fR 4
8535 .IX Item "gv_autoload_pv"
8536 .PD 0
8537 .ie n .IP """gv_autoload_pvn""" 4
8538 .el .IP \f(CWgv_autoload_pvn\fR 4
8539 .IX Item "gv_autoload_pvn"
8540 .ie n .IP """gv_autoload_sv""" 4
8541 .el .IP \f(CWgv_autoload_sv\fR 4
8542 .IX Item "gv_autoload_sv"
8543 .ie n .IP """gv_autoload4""" 4
8544 .el .IP \f(CWgv_autoload4\fR 4
8545 .IX Xref "gv_autoload_pv gv_autoload_pvn gv_autoload_sv gv_autoload4"
8546 .IX Item "gv_autoload4"
8547 .PD
8548 These each search for an \f(CW\*(C`AUTOLOAD\*(C'\fR method, returning NULL if not found, or
8549 else returning a pointer to its GV, while setting the package
8550 \&\f(CW$AUTOLOAD\fR variable to the name (fully qualified). Also,
8551 if found and the GV\*(Aqs CV is an XSUB, the CV\*(Aqs PV will be set to the name, and
8552 its stash will be set to the stash of the GV.
8553 .Sp
8554 Searching is done in \f(CW\*(C`MRO\*(C'\fR order, as specified in
8555 "\f(CW\*(C`gv_fetchmeth\*(C'\fR", beginning with \f(CW\*(C`stash\*(C'\fR if it isn\*(Aqt NULL.
8556 .Sp
8557 \&\f(CW\*(C`gv_autoload4\*(C'\fR) has a \f(CW\*(C`method\*(C'\fR parameter; the others a \f(CW\*(C`flags\*(C'\fR one (both
8558 types explained below). Otherwise, the forms differ only in how the name is
8559 specified.
8560 .Sp
8561 In \f(CW\*(C`gv_autoload_pv\*(C'\fR, \f(CW\*(C`namepv\*(C'\fR is a C language NUL\-terminated string.
8562 .Sp
8563 In \f(CW\*(C`gv_autoload_pvn\*(C'\fR and \f(CW\*(C`gv_autoload4\*(C'\fR), \f(CW\*(C`name\*(C'\fR points to the first byte of
8564 the name, and an additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes.
8565 Hence, \f(CW*name\fR may contain embedded\-NUL characters.
8566 .Sp
8567 In \f(CW\*(C`gv_autoload_sv\*(C'\fR, \f(CW*namesv\fR is an SV, and the name is the PV extracted
8568 from that using "\f(CW\*(C`SvPV\*(C'\fR". If the SV is marked as being in UTF\-8, the
8569 extracted PV will also be.
8570 .Sp
8571 The other way to indicate that the name is encoded as UTF\-8 is to set the
8572 \&\f(CW\*(C`SVf_UTF8\*(C'\fR bit in \f(CW\*(C`flags\*(C'\fR for the forms that have that parameter.
8573 The name is never considered to be UTF\-8 in \f(CW\*(C`gv_autoload4\*(C'\fR.
8574 .Sp
8575 The \f(CW\*(C`method\*(C'\fR parameter in \f(CW\*(C`gv_autoload4\*(C'\fR is used only to indicate that the
8576 name is for a method (non\-zero), or not (zero). The other forms use the
8577 \&\f(CW\*(C`GV_AUTOLOAD_ISMETHOD\*(C'\fR bit in \f(CW\*(C`flags\*(C'\fR to indicate this.
8578 .Sp
8579 The only other significant value in \f(CW\*(C`flags\*(C'\fR currently is \f(CW\*(C`GV_SUPER\*(C'\fR
8580 to indicate, if set, to skip searching for the name in \f(CW\*(C`stash\*(C'\fR.
8581 .RS 4
8582 .Sp
8583 .Vb 10
8584 \& GV * gv_autoload_pv ( NOCHECK HV *stash,
8585 \& const char *namepv, U32 flags)
8586 \& GV * Perl_gv_autoload_pv (pTHX_ NOCHECK HV *stash,
8587 \& const char *namepv, U32 flags)
8588 \& GV * gv_autoload_pvn( NOCHECK HV *stash,
8589 \& const char *name, STRLEN len,
8590 \& U32 flags)
8591 \& GV * Perl_gv_autoload_pvn(pTHX_ NOCHECK HV *stash,
8592 \& const char *name, STRLEN len,
8593 \& U32 flags)
8594 \& GV * gv_autoload_sv ( NOCHECK HV *stash, SV *namesv,
8595 \& U32 flags)
8596 \& GV * Perl_gv_autoload_sv (pTHX_ NOCHECK HV *stash, SV *namesv,
8597 \& U32 flags)
8598 \& GV * gv_autoload4 ( HV *stash, const char *name,
8599 \& STRLEN len, I32 method
8600 \&)
8601 .Ve
8602 .RE
8603 .RS 4
8604 .RE
8605 .ie n .IP """gv_AVadd""" 4
8606 .el .IP \f(CWgv_AVadd\fR 4
8607 .IX Item "gv_AVadd"
8608 .PD 0
8609 .ie n .IP """gv_HVadd""" 4
8610 .el .IP \f(CWgv_HVadd\fR 4
8611 .IX Item "gv_HVadd"
8612 .ie n .IP """gv_IOadd""" 4
8613 .el .IP \f(CWgv_IOadd\fR 4
8614 .IX Item "gv_IOadd"
8615 .ie n .IP """gv_SVadd""" 4
8616 .el .IP \f(CWgv_SVadd\fR 4
8617 .IX Xref "gv_AVadd gv_HVadd gv_IOadd gv_SVadd"
8618 .IX Item "gv_SVadd"
8619 .PD
8620 Make sure there is a slot of the given type (AV, HV, IO, SV) in the GV \f(CW\*(C`gv\*(C'\fR.
8621 .RS 4
8622 .Sp
8623 .Vb 8
8624 \& GV * gv_AVadd( GV *gv)
8625 \& GV * Perl_gv_AVadd(pTHX_ GV *gv)
8626 \& GV * gv_HVadd( GV *gv)
8627 \& GV * Perl_gv_HVadd(pTHX_ GV *gv)
8628 \& GV * gv_IOadd( GV *gv)
8629 \& GV * Perl_gv_IOadd(pTHX_ GV *gv)
8630 \& GV * gv_SVadd( GV *gv)
8631 \& GV * Perl_gv_SVadd(pTHX_ GV *gv)
8632 .Ve
8633 .RE
8634 .RS 4
8635 .RE
8636 .ie n .IP """gv_const_sv""" 4
8637 .el .IP \f(CWgv_const_sv\fR 4
8638 .IX Xref "gv_const_sv"
8639 .IX Item "gv_const_sv"
8640 If \f(CW\*(C`gv\*(C'\fR is a typeglob whose subroutine entry is a constant sub eligible for
8641 inlining, or \f(CW\*(C`gv\*(C'\fR is a placeholder reference that would be promoted to such
8642 a typeglob, then returns the value returned by the sub. Otherwise, returns
8643 \&\f(CW\*(C`NULL\*(C'\fR.
8644 .RS 4
8645 .Sp
8646 .Vb 2
8647 \& SV * gv_const_sv( GV *gv)
8648 \& SV * Perl_gv_const_sv(pTHX_ GV *gv)
8649 .Ve
8650 .RE
8651 .RS 4
8652 .RE
8653 .ie n .IP """gv_efullname3""" 4
8654 .el .IP \f(CWgv_efullname3\fR 4
8655 .IX Item "gv_efullname3"
8656 .PD 0
8657 .ie n .IP """gv_efullname4""" 4
8658 .el .IP \f(CWgv_efullname4\fR 4
8659 .IX Item "gv_efullname4"
8660 .ie n .IP """gv_fullname3""" 4
8661 .el .IP \f(CWgv_fullname3\fR 4
8662 .IX Item "gv_fullname3"
8663 .ie n .IP """gv_fullname4""" 4
8664 .el .IP \f(CWgv_fullname4\fR 4
8665 .IX Xref "gv_efullname3 gv_efullname4 gv_fullname3 gv_fullname4"
8666 .IX Item "gv_fullname4"
8667 .PD
8668 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
8669 instead the effective package name (see "HvENAME").
8670 .Sp
8671 If \f(CW\*(C`prefix\*(C'\fR is non\-NULL, it is considered to be a C language NUL\-terminated
8672 string, and the stored name will be prefaced with it.
8673 .Sp
8674 The other difference between the functions is that the \f(CW*4\fR forms have an
8675 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
8676 kept; if \f(CW\*(C`false\*(C'\fR it is stripped. With the \f(CW*3\fR forms, it is always kept.
8677 .RS 4
8678 .Sp
8679 .Vb 10
8680 \& void gv_efullname3( SV *sv, const GV *gv,
8681 \& const char *prefix)
8682 \& void Perl_gv_efullname3(pTHX_ SV *sv, const GV *gv,
8683 \& const char *prefix)
8684 \& void gv_efullname4( SV *sv, const GV *gv,
8685 \& const char *prefix, bool keepmain)
8686 \& void Perl_gv_efullname4(pTHX_ SV *sv, const GV *gv,
8687 \& const char *prefix, bool keepmain)
8688 \& void gv_fullname3 ( SV *sv, const GV *gv,
8689 \& const char *prefix)
8690 \& void Perl_gv_fullname3 (pTHX_ SV *sv, const GV *gv,
8691 \& const char *prefix)
8692 \& void gv_fullname4 ( SV *sv, const GV *gv,
8693 \& const char *prefix, bool keepmain)
8694 \& void Perl_gv_fullname4 (pTHX_ SV *sv, const GV *gv,
8695 \& const char *prefix, bool keepmain)
8696 .Ve
8697 .RE
8698 .RS 4
8699 .RE
8700 .ie n .IP """gv_fetchfile""" 4
8701 .el .IP \f(CWgv_fetchfile\fR 4
8702 .IX Item "gv_fetchfile"
8703 .PD 0
8704 .ie n .IP """gv_fetchfile_flags""" 4
8705 .el .IP \f(CWgv_fetchfile_flags\fR 4
8706 .IX Xref "gv_fetchfile gv_fetchfile_flags"
8707 .IX Item "gv_fetchfile_flags"
8708 .PD
8709 These return the debugger glob for the file (compiled by Perl) whose name is
8710 given by the \f(CW\*(C`name\*(C'\fR parameter.
8711 .Sp
8712 There are currently exactly two differences between these functions.
8713 .Sp
8714 The \f(CW\*(C`name\*(C'\fR parameter to \f(CW\*(C`gv_fetchfile\*(C'\fR is a C string, meaning it is
8715 \&\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
8716 Perl string, whose length (in bytes) is passed in via the \f(CW\*(C`namelen\*(C'\fR parameter
8717 This means the name may contain embedded \f(CW\*(C`NUL\*(C'\fR characters.
8718 \&\f(CW\*(C`namelen\*(C'\fR doesn\*(Aqt exist in plain \f(CW\*(C`gv_fetchfile\*(C'\fR).
8719 .Sp
8720 The other difference is that \f(CW\*(C`gv_fetchfile_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR
8721 parameter, which is currently completely ignored, but allows for possible
8722 future extensions.
8723 .RS 4
8724 .Sp
8725 .Vb 8
8726 \& GV * gv_fetchfile ( const char *name)
8727 \& GV * Perl_gv_fetchfile (pTHX_ const char *name)
8728 \& GV * gv_fetchfile_flags( const char * const name,
8729 \& const STRLEN len,
8730 \& const U32 flags)
8731 \& GV * Perl_gv_fetchfile_flags(pTHX_ const char * const name,
8732 \& const STRLEN len,
8733 \& const U32 flags)
8734 .Ve
8735 .RE
8736 .RS 4
8737 .RE
8738 .ie n .IP """gv_fetchmeth""" 4
8739 .el .IP \f(CWgv_fetchmeth\fR 4
8740 .IX Item "gv_fetchmeth"
8741 .PD 0
8742 .ie n .IP """gv_fetchmeth_autoload""" 4
8743 .el .IP \f(CWgv_fetchmeth_autoload\fR 4
8744 .IX Item "gv_fetchmeth_autoload"
8745 .ie n .IP """gv_fetchmeth_pv""" 4
8746 .el .IP \f(CWgv_fetchmeth_pv\fR 4
8747 .IX Item "gv_fetchmeth_pv"
8748 .ie n .IP """gv_fetchmeth_pv_autoload""" 4
8749 .el .IP \f(CWgv_fetchmeth_pv_autoload\fR 4
8750 .IX Item "gv_fetchmeth_pv_autoload"
8751 .ie n .IP """gv_fetchmeth_pvn""" 4
8752 .el .IP \f(CWgv_fetchmeth_pvn\fR 4
8753 .IX Item "gv_fetchmeth_pvn"
8754 .ie n .IP """gv_fetchmeth_pvn_autoload""" 4
8755 .el .IP \f(CWgv_fetchmeth_pvn_autoload\fR 4
8756 .IX Item "gv_fetchmeth_pvn_autoload"
8757 .ie n .IP """gv_fetchmeth_sv""" 4
8758 .el .IP \f(CWgv_fetchmeth_sv\fR 4
8759 .IX Item "gv_fetchmeth_sv"
8760 .ie n .IP """gv_fetchmeth_sv_autoload""" 4
8761 .el .IP \f(CWgv_fetchmeth_sv_autoload\fR 4
8762 .IX Xref "gv_fetchmeth gv_fetchmeth_autoload gv_fetchmeth_pv gv_fetchmeth_pv_autoload gv_fetchmeth_pvn gv_fetchmeth_pvn_autoload gv_fetchmeth_sv gv_fetchmeth_sv_autoload"
8763 .IX Item "gv_fetchmeth_sv_autoload"
8764 .PD
8765 These each look for a glob with name \f(CW\*(C`name\*(C'\fR, containing a defined subroutine,
8766 returning the GV of that glob if found, or \f(CW\*(C`NULL\*(C'\fR if not.
8767 .Sp
8768 You probably want to use the \f(CW"gv_fetchmethod"\fR family of functions
8769 instead.
8770 .Sp
8771 Searching is always done in the following order, with some steps skipped
8772 depending on various criteria. The first match found is used, ending the
8773 search. \f(CW\*(C`gv_fetchmeth_pv\*(C'\fR and \f(CW\*(C`gv_fetchmeth_pv_autoload\*(C'\fR lack a flags
8774 parameter, so in the following, consider \f(CW\*(C`flags\*(C'\fR to be zero for those two
8775 functions.
8776 .RS 4
8777 .IP 1. 4
8778 \&\f(CW\*(C`stash\*(C'\fR is searched first, unless \f(CW\*(C`stash\*(C'\fR either is NULL or \f(CW\*(C`GV_SUPER\*(C'\fR is
8779 set in \f(CW\*(C`flags\*(C'\fR.
8780 .IP 2. 4
8781 Stashes accessible via \f(CW@ISA\fR are searched next.
8782 .Sp
8783 Searching is conducted according to \f(CW\*(C`MRO\*(C'\fR order.
8784 .IP 3. 4
8785 \&\f(CW\*(C`UNIVERSAL::\*(C'\fR is searched unless \f(CW\*(C`GV_NOUNIVERSAL\*(C'\fR is set.
8786 .IP 4. 4
8787 Autoloaded subroutines are then looked for, but only for the forms whose names
8788 end in \f(CW\*(C`_autoload\*(C'\fR, and when \f(CW\*(C`stash\*(C'\fR is not NULL and \f(CW\*(C`GV_SUPER\*(C'\fR is not set.
8789 .RE
8790 .RS 4
8791 .Sp
8792 The argument \f(CW\*(C`level\*(C'\fR should be either 0 or \-1.
8793 .IP "If \-1" 4
8794 .IX Item "If -1"
8795 No method caching is done.
8796 .IP "If 0" 4
8797 .IX Item "If 0"
8798 If \f(CW\*(C`GV_SUPER\*(C'\fR is not set in \f(CW\*(C`flags\*(C'\fR, the method found is cached in \f(CW\*(C`stash\*(C'\fR.
8799 .Sp
8800 If \f(CW\*(C`GV_SUPER\*(C'\fR is set in \f(CW\*(C`flags\*(C'\fR, the method is cached in the super
8801 cache for \f(CW\*(C`stash\*(C'\fR.
8802 .Sp
8803 If the method is not found a negative cache entry is added.
8804 .Sp
8805 Note that subroutines found in \f(CW\*(C`UNIVERSAL::\*(C'\fR are not cached,
8806 though this may change.
8807 .RE
8808 .RS 4
8809 .Sp
8810 The GV returned from these may be a method cache entry, which is not visible to
8811 Perl code. So when calling \f(CW"call_sv"\fR, you should not use the GV directly;
8812 instead, you should use the method\*(Aqs CV, which can be obtained from the GV with
8813 the \f(CW\*(C`GvCV\*(C'\fR macro. For an autoloaded subroutine without a stub, \f(CWGvCV()\fR of
8814 the result may be zero.
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. Since plain
8818 \&\f(CW\*(C`gv_fetchmeth\*(C'\fR and \f(CW\*(C`gv_fetchmeth_autoload\*(C'\fR lack a \f(CW\*(C`flags\*(C'\fR parameter, \f(CW\*(C`name\*(C'\fR
8819 is never UTF\-8.
8820 .Sp
8821 Otherwise, the functions behave identically, except as noted below.
8822 .Sp
8823 In \f(CW\*(C`gv_fetchmeth_pv\*(C'\fR and \f(CW\*(C`gv_fetchmeth_pv_autoload\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a C language
8824 NUL\-terminated string.
8825 .Sp
8826 In \f(CW\*(C`gv_fetchmeth\*(C'\fR, \f(CW\*(C`gv_fetchmeth_pvn\*(C'\fR, \f(CW\*(C`gv_fetchmeth_autoload\*(C'\fR, and
8827 \&\f(CW\*(C`gv_fetchmeth_pvn_autoload\*(C'\fR, \f(CW\*(C`name\*(C'\fR points to the first byte of the name, and
8828 an additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, the
8829 name may contain embedded\-NUL characters.
8830 .Sp
8831 In \f(CW\*(C`gv_fetchmeth_sv\*(C'\fR and \f(CW\*(C`gv_fetchmeth_sv_autoload\*(C'\fR, \f(CW*name\fR is an SV, and
8832 the name is the PV extracted from that, using \f(CW"SvPV"\fR. If the SV is marked
8833 as being in UTF\-8, the extracted PV will also be. Including \f(CW\*(C`SVf_UTF8\*(C'\fR in
8834 \&\f(CW\*(C`flags\*(C'\fR will force the name to be considered to be UTF\-8 even if the SV is
8835 not so marked.
8836 .Sp
8837 .Vb 10
8838 \& GV * gv_fetchmeth ( NOCHECK HV *stash,
8839 \& const char *name,
8840 \& STRLEN len, I32 level)
8841 \& GV * gv_fetchmeth_autoload ( NOCHECK HV *stash,
8842 \& const char *name,
8843 \& STRLEN len, I32 level)
8844 \& GV * gv_fetchmeth_pv ( NOCHECK HV *stash,
8845 \& const char *name,
8846 \& I32 level, U32 flags)
8847 \& GV * Perl_gv_fetchmeth_pv (pTHX_ NOCHECK HV *stash,
8848 \& const char *name,
8849 \& I32 level, U32 flags)
8850 \& GV * gv_fetchmeth_pv_autoload ( NOCHECK HV *stash,
8851 \& const char *name,
8852 \& I32 level, U32 flags)
8853 \& GV * Perl_gv_fetchmeth_pv_autoload (pTHX_ NOCHECK HV *stash,
8854 \& const char *name,
8855 \& I32 level, U32 flags)
8856 \& GV * gv_fetchmeth_pvn ( NOCHECK HV *stash,
8857 \& const char *name,
8858 \& STRLEN len, I32 level,
8859 \& U32 flags)
8860 \& GV * Perl_gv_fetchmeth_pvn (pTHX_ NOCHECK HV *stash,
8861 \& const char *name,
8862 \& STRLEN len, I32 level,
8863 \& U32 flags)
8864 \& GV * gv_fetchmeth_pvn_autoload( NOCHECK HV *stash,
8865 \& const char *name,
8866 \& STRLEN len, I32 level,
8867 \& U32 flags)
8868 \& GV * Perl_gv_fetchmeth_pvn_autoload(pTHX_ NOCHECK HV *stash,
8869 \& const char *name,
8870 \& STRLEN len, I32 level,
8871 \& U32 flags)
8872 \& GV * gv_fetchmeth_sv ( NOCHECK HV *stash,
8873 \& SV *namesv, I32 level,
8874 \& U32 flags)
8875 \& GV * Perl_gv_fetchmeth_sv (pTHX_ NOCHECK HV *stash,
8876 \& SV *namesv, I32 level,
8877 \& U32 flags)
8878 \& GV * gv_fetchmeth_sv_autoload ( NOCHECK HV *stash,
8879 \& SV *namesv, I32 level,
8880 \& U32 flags)
8881 \& GV * Perl_gv_fetchmeth_sv_autoload (pTHX_ NOCHECK HV *stash,
8882 \& SV *namesv, I32 level,
8883 \& U32 flags)
8884 .Ve
8885 .RE
8886 .RS 4
8887 .RE
8888 .ie n .IP """gv_fetchmethod""" 4
8889 .el .IP \f(CWgv_fetchmethod\fR 4
8890 .IX Item "gv_fetchmethod"
8891 .PD 0
8892 .ie n .IP """gv_fetchmethod_autoload""" 4
8893 .el .IP \f(CWgv_fetchmethod_autoload\fR 4
8894 .IX Xref "gv_fetchmethod gv_fetchmethod_autoload"
8895 .IX Item "gv_fetchmethod_autoload"
8896 .PD
8897 These each return the glob which contains the subroutine to call to invoke the
8898 method on the \f(CW\*(C`stash\*(C'\fR. In fact in the presence of autoloading this may be the
8899 glob for "AUTOLOAD". In this case the corresponding variable \f(CW$AUTOLOAD\fR is
8900 already setup.
8901 .Sp
8902 The third parameter of \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR determines whether
8903 AUTOLOAD lookup is performed if the given method is not present: non\-zero
8904 means yes, look for AUTOLOAD; zero means no, don\*(Aqt look for AUTOLOAD.
8905 Calling \f(CW\*(C`gv_fetchmethod\*(C'\fR is equivalent to calling \f(CW\*(C`gv_fetchmethod_autoload\*(C'\fR
8906 with a non\-zero \f(CW\*(C`autoload\*(C'\fR parameter.
8907 .Sp
8908 These functions grant \f(CW"SUPER"\fR token
8909 as a prefix of the method name. Note
8910 that if you want to keep the returned glob for a long time, you need to
8911 check for it being "AUTOLOAD", since at the later time the call may load a
8912 different subroutine due to \f(CW$AUTOLOAD\fR changing its value. Use the glob
8913 created as a side effect to do this.
8914 .Sp
8915 These functions have the same side\-effects as \f(CW\*(C`gv_fetchmeth\*(C'\fR with
8916 \&\f(CW\*(C`level==0\*(C'\fR. The warning against passing the GV returned by
8917 \&\f(CW\*(C`gv_fetchmeth\*(C'\fR to \f(CW\*(C`call_sv\*(C'\fR applies equally to these functions.
8918 .RS 4
8919 .Sp
8920 .Vb 10
8921 \& GV * gv_fetchmethod ( NOCHECK HV *stash,
8922 \& const char *name)
8923 \& GV * Perl_gv_fetchmethod (pTHX_ NOCHECK HV *stash,
8924 \& const char *name)
8925 \& GV * gv_fetchmethod_autoload( NOCHECK HV *stash,
8926 \& const char *name,
8927 \& I32 autoload)
8928 \& GV * Perl_gv_fetchmethod_autoload(pTHX_ NOCHECK HV *stash,
8929 \& const char *name,
8930 \& I32 autoload)
8931 .Ve
8932 .RE
8933 .RS 4
8934 .RE
8935 .ie n .IP """gv_fetchpv""" 4
8936 .el .IP \f(CWgv_fetchpv\fR 4
8937 .IX Item "gv_fetchpv"
8938 .PD 0
8939 .ie n .IP """gv_fetchpvn""" 4
8940 .el .IP \f(CWgv_fetchpvn\fR 4
8941 .IX Item "gv_fetchpvn"
8942 .ie n .IP """gv_fetchpvn_flags""" 4
8943 .el .IP \f(CWgv_fetchpvn_flags\fR 4
8944 .IX Item "gv_fetchpvn_flags"
8945 .ie n .IP """gv_fetchpvs""" 4
8946 .el .IP \f(CWgv_fetchpvs\fR 4
8947 .IX Item "gv_fetchpvs"
8948 .ie n .IP """gv_fetchsv""" 4
8949 .el .IP \f(CWgv_fetchsv\fR 4
8950 .IX Item "gv_fetchsv"
8951 .ie n .IP """gv_fetchsv_nomg""" 4
8952 .el .IP \f(CWgv_fetchsv_nomg\fR 4
8953 .IX Xref "gv_fetchpv gv_fetchpvn gv_fetchpvn_flags gv_fetchpvs gv_fetchsv gv_fetchsv_nomg"
8954 .IX Item "gv_fetchsv_nomg"
8955 .PD
8956 These all return the GV of type \f(CW\*(C`sv_type\*(C'\fR whose name is given by the inputs,
8957 or NULL if no GV of that name and type could be found. See "Stashes
8958 and Globs" in perlguts.
8959 .Sp
8960 The only differences are how the input name is specified, and if \*(Aqget\*(Aq magic is
8961 normally used in getting that name.
8962 .Sp
8963 Don\*(Aqt be fooled by the fact that only one form has \f(CW\*(C`flags\*(C'\fR in its name. They
8964 all have a \f(CW\*(C`flags\*(C'\fR parameter in fact, and all the flag bits have the same
8965 meanings for all
8966 .Sp
8967 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
8968 \&\f(CW\*(C`GV_NOINIT\*(C'\fR is set, a GV is created if none already exists for the input name
8969 and type. However, \f(CW\*(C`GV_ADDMG\*(C'\fR will only do the creation for magical GV\*(Aqs.
8970 For all of these flags except \f(CW\*(C`GV_NOINIT\*(C'\fR, \f(CW"gv_init_pvn"\fR is called after
8971 the addition. \f(CW\*(C`GV_ADDWARN\*(C'\fR is used when the caller expects that adding won\*(Aqt
8972 be necessary because the symbol should already exist; but if not, add it
8973 anyway, with a warning that it was unexpectedly absent. The \f(CW\*(C`GV_ADDMULTI\*(C'\fR
8974 flag means to pretend that the GV has been seen before (\fIi.e.\fR, suppress "Used
8975 once" warnings).
8976 .Sp
8977 The flag \f(CW\*(C`GV_NOADD_NOINIT\*(C'\fR causes \f(CW"gv_init_pvn"\fR not be to called if the
8978 GV existed but isn\*(Aqt PVGV.
8979 .Sp
8980 If the \f(CW\*(C`SVf_UTF8\*(C'\fR bit is set, the name is treated as being encoded in UTF\-8;
8981 otherwise the name won\*(Aqt be considered to be UTF\-8 in the \f(CW\*(C`pv\*(C'\fR\-named forms,
8982 and the UTF\-8ness of the underlying SVs will be used in the \f(CW\*(C`sv\*(C'\fR forms.
8983 .Sp
8984 If the flag \f(CW\*(C`GV_NOTQUAL\*(C'\fR is set, the caller warrants that the input name is a
8985 plain symbol name, not qualified with a package, otherwise the name is checked
8986 for being a qualified one.
8987 .Sp
8988 In \f(CW\*(C`gv_fetchpv\*(C'\fR, \f(CW\*(C`nambeg\*(C'\fR is a C string, NUL\-terminated with no intermediate
8989 NULs.
8990 .Sp
8991 In \f(CW\*(C`gv_fetchpvs\*(C'\fR, \f(CW\*(C`name\*(C'\fR is a literal C string, hence is enclosed in
8992 double quotes.
8993 .Sp
8994 \&\f(CW\*(C`gv_fetchpvn\*(C'\fR and \f(CW\*(C`gv_fetchpvn_flags\*(C'\fR are identical. In these, <nambeg> is
8995 a Perl string whose byte length is given by \f(CW\*(C`full_len\*(C'\fR, and may contain
8996 embedded NULs.
8997 .Sp
8998 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
8999 the input \f(CW\*(C`name\*(C'\fR SV. The only difference between these two forms is that
9000 \&\*(Aqget\*(Aq magic is normally done on \f(CW\*(C`name\*(C'\fR in \f(CW\*(C`gv_fetchsv\*(C'\fR, and always skipped
9001 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
9002 to \f(CW\*(C`gv_fetchsv\*(C'\fR makes it behave identically to \f(CW\*(C`gv_fetchsv_nomg\*(C'\fR.
9003 .RS 4
9004 .Sp
9005 .Vb 10
9006 \& GV * gv_fetchpv ( const char *nambeg, I32 flags,
9007 \& const svtype sv_type)
9008 \& GV * Perl_gv_fetchpv (pTHX_ const char *nambeg, I32 flags,
9009 \& const svtype sv_type)
9010 \& GV * gv_fetchpvn ( const char * nambeg,
9011 \& STRLEN full_len, I32 flags,
9012 \& const svtype sv_type)
9013 \& GV * gv_fetchpvn_flags( const char *name, STRLEN len,
9014 \& I32 flags,
9015 \& const svtype sv_type)
9016 \& GV * Perl_gv_fetchpvn_flags(pTHX_ const char *name, STRLEN len,
9017 \& I32 flags,
9018 \& const svtype sv_type)
9019 \& GV * gv_fetchpvs ( "name", I32 flags,
9020 \& const svtype sv_type)
9021 \& GV * gv_fetchsv ( SV *name, I32 flags,
9022 \& const svtype sv_type)
9023 \& GV * Perl_gv_fetchsv (pTHX_ SV *name, I32 flags,
9024 \& const svtype sv_type)
9025 \& GV * gv_fetchsv_nomg ( SV *name, I32 flags,
9026 \& const svtype sv_type)
9027 .Ve
9028 .RE
9029 .RS 4
9030 .RE
9031 .ie n .IP """gv_fullname3*""" 4
9032 .el .IP \f(CWgv_fullname3*\fR 4
9033 .IX Item "gv_fullname3*"
9034 .PD 0
9035 .ie n .IP """gv_fullname4*""" 4
9036 .el .IP \f(CWgv_fullname4*\fR 4
9037 .IX Item "gv_fullname4*"
9038 .PD
9039 Described under \f(CW"gv_efullname3"\fR
9040 .ie n .IP """gv_HVadd*""" 4
9041 .el .IP \f(CWgv_HVadd*\fR 4
9042 .IX Item "gv_HVadd*"
9043 Described under \f(CW"gv_AVadd"\fR
9044 .ie n .IP """gv_init""" 4
9045 .el .IP \f(CWgv_init\fR 4
9046 .IX Item "gv_init"
9047 .PD 0
9048 .ie n .IP """gv_init_pv""" 4
9049 .el .IP \f(CWgv_init_pv\fR 4
9050 .IX Item "gv_init_pv"
9051 .ie n .IP """gv_init_pvn""" 4
9052 .el .IP \f(CWgv_init_pvn\fR 4
9053 .IX Item "gv_init_pvn"
9054 .ie n .IP """gv_init_sv""" 4
9055 .el .IP \f(CWgv_init_sv\fR 4
9056 .IX Xref "gv_init gv_init_pv gv_init_pvn gv_init_sv"
9057 .IX Item "gv_init_sv"
9058 .PD
9059 These each convert a scalar into a typeglob. This is an incoercible typeglob;
9060 assigning a reference to it will assign to one of its slots, instead of
9061 overwriting it as happens with typeglobs created by \f(CW\*(C`SvSetSV\*(C'\fR. Converting
9062 any scalar that is \f(CWSvOK()\fR may produce unpredictable results and is reserved
9063 for perl\*(Aqs internal use.
9064 .Sp
9065 \&\f(CW\*(C`gv\*(C'\fR is the scalar to be converted.
9066 .Sp
9067 \&\f(CW\*(C`stash\*(C'\fR is the parent stash/package, if any.
9068 .Sp
9069 In \f(CW\*(C`gv_init\*(C'\fR and \f(CW\*(C`gv_init_pvn\*(C'\fR, \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`len\*(C'\fR give the name. The name
9070 must be unqualified; that is, it must not include the package name. If \f(CW\*(C`gv\*(C'\fR
9071 is a stash element, it is the caller\*(Aqs responsibility to ensure that the name
9072 passed to this function matches the name of the element. If it does not match,
9073 perl\*(Aqs internal bookkeeping will get out of sync. \f(CW\*(C`name\*(C'\fR may contain embedded
9074 NUL characters.
9075 .Sp
9076 \&\f(CW\*(C`gv_init_pv\*(C'\fR is identical to \f(CW\*(C`gv_init_pvn\*(C'\fR, but takes a NUL\-terminated string
9077 for the name instead of separate char * and length parameters.
9078 .Sp
9079 In \f(CW\*(C`gv_init_sv\*(C'\fR, the name is given by \f(CW\*(C`sv\*(C'\fR.
9080 .Sp
9081 All but \f(CW\*(C`gv_init\*(C'\fR take a \f(CW\*(C`flags\*(C'\fR parameter. Set \f(CW\*(C`flags\*(C'\fR to include
9082 \&\f(CW\*(C`SVf_UTF8\*(C'\fR if \f(CW\*(C`name\*(C'\fR is a UTF\-8 string. In \f(CW\*(C`gv_init_sv\*(C'\fR, if \f(CWSvUTF8(sv)\fR
9083 is non\-zero, name will be also be considered to be a UTF\-8 string. It\*(Aqs
9084 unlikely to be a good idea to pass this particular flag to \f(CW\*(C`gv_init_sv\*(C'\fR, as
9085 that would potentially override the (presumaby known) state of \f(CW\*(C`sv\*(C'\fR.
9086 .Sp
9087 \&\f(CW\*(C`flags\*(C'\fR can also take the \f(CW\*(C`GV_ADDMULTI\*(C'\fR flag, which means to pretend that the
9088 GV has been seen before (i.e., suppress "Used once" warnings).
9089 .Sp
9090 \&\f(CW\*(C`gv_init\*(C'\fR is the old form of \f(CW\*(C`gv_init_pvn\*(C'\fR. It does not work with UTF\-8
9091 strings, as it has no flags parameter. Setting the \f(CW\*(C`multi\*(C'\fR parameter to
9092 non\-zero has the same effect as setting the \f(CW\*(C`GV_ADDMULTI\*(C'\fR flag in the other
9093 forms.
9094 .RS 4
9095 .Sp
9096 .Vb 10
9097 \& void gv_init ( GV *gv, HV *stash, const char *name,
9098 \& STRLEN len, int multi)
9099 \& void gv_init_pv ( GV *gv, HV *stash, const char *name,
9100 \& U32 flags)
9101 \& void Perl_gv_init_pv (pTHX_ GV *gv, HV *stash, const char *name,
9102 \& U32 flags)
9103 \& void gv_init_pvn( GV *gv, HV *stash, const char *name,
9104 \& STRLEN len, U32 flags)
9105 \& void Perl_gv_init_pvn(pTHX_ GV *gv, HV *stash, const char *name,
9106 \& STRLEN len, U32 flags)
9107 \& void gv_init_sv ( GV *gv, HV *stash, SV *namesv,
9108 \& U32 flags)
9109 \& void Perl_gv_init_sv (pTHX_ GV *gv, HV *stash, SV *namesv,
9110 \& U32 flags)
9111 .Ve
9112 .RE
9113 .RS 4
9114 .RE
9115 .ie n .IP """gv_IOadd*""" 4
9116 .el .IP \f(CWgv_IOadd*\fR 4
9117 .IX Item "gv_IOadd*"
9118 Described under \f(CW"gv_AVadd"\fR
9119 .ie n .IP """gv_name_set""" 4
9120 .el .IP \f(CWgv_name_set\fR 4
9121 .IX Xref "gv_name_set"
9122 .IX Item "gv_name_set"
9123 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
9124 contain embedded NUL characters.
9125 .Sp
9126 If \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`SVf_UTF8\*(C'\fR, the name is treated as being encoded in
9127 UTF\-8; otherwise not.
9128 .RS 4
9129 .Sp
9130 .Vb 4
9131 \& void gv_name_set( GV *gv, const char *name, U32 len,
9132 \& U32 flags)
9133 \& void Perl_gv_name_set(pTHX_ GV *gv, const char *name, U32 len,
9134 \& U32 flags)
9135 .Ve
9136 .RE
9137 .RS 4
9138 .RE
9139 .ie n .IP """gv_stashpv""" 4
9140 .el .IP \f(CWgv_stashpv\fR 4
9141 .IX Item "gv_stashpv"
9142 .PD 0
9143 .ie n .IP """gv_stashpvn""" 4
9144 .el .IP \f(CWgv_stashpvn\fR 4
9145 .IX Item "gv_stashpvn"
9146 .ie n .IP """gv_stashpvs""" 4
9147 .el .IP \f(CWgv_stashpvs\fR 4
9148 .IX Item "gv_stashpvs"
9149 .ie n .IP """gv_stashsv""" 4
9150 .el .IP \f(CWgv_stashsv\fR 4
9151 .IX Xref "gv_stashpv gv_stashpvn gv_stashpvs gv_stashsv"
9152 .IX Item "gv_stashsv"
9153 .PD
9154 Note \f(CW\*(C`gv_stashsv\*(C'\fR is strongly preferred for performance reasons.
9155 .Sp
9156 These each return a pointer to the stash for a specified package.
9157 .Sp
9158 In \f(CW\*(C`gv_stashsv\*(C'\fR, the package is specified by \f(CW\*(C`sv\*(C'\fR.
9159 .Sp
9160 In \f(CW\*(C`gv_stashpvs\*(C'\fR, the package is specified by the literal C string enclosed in
9161 double quotes.
9162 .Sp
9163 In the other forms, \f(CW\*(C`name\*(C'\fR specifies the package. In \f(CW\*(C`gv_stashpvn\*(C'\fR,
9164 \&\f(CW\*(C`namelen\*(C'\fR gives the length of the name in bytes, so it may include embedded
9165 NUL characters. In \f(CW\*(C`gv_stashpv\*(C'\fR, \f(CW\*(C`name\*(C'\fR ends at the first NUL character.
9166 .Sp
9167 \&\f(CW\*(C`flags\*(C'\fR is passed to \f(CWgv_fetchpvn_flags()\fR, so if set to \f(CW\*(C`GV_ADD\*(C'\fR then the
9168 package will be created if it does not already exist. If the package does not
9169 exist and \f(CW\*(C`flags\*(C'\fR is 0 (or any other setting that does not create packages)
9170 then \f(CW\*(C`NULL\*(C'\fR is returned.
9171 .Sp
9172 Flags may be one of:
9173 .Sp
9174 .Vb 7
9175 \& GV_ADD Create and initialize the package if doesn\*(Aqt
9176 \& already exist
9177 \& GV_NOADD_NOINIT Don\*(Aqt create the package,
9178 \& GV_ADDMG GV_ADD iff the GV is magical
9179 \& GV_NOINIT GV_ADD, but don\*(Aqt initialize
9180 \& GV_NOEXPAND Don\*(Aqt expand SvOK() entries to PVGV
9181 \& SVf_UTF8 The name is in UTF\-8
9182 .Ve
9183 .Sp
9184 The most important of which are probably \f(CW\*(C`GV_ADD\*(C'\fR and \f(CW\*(C`SVf_UTF8\*(C'\fR.
9185 .RS 4
9186 .Sp
9187 .Vb 9
9188 \& HV * gv_stashpv ( const char *name, I32 flags)
9189 \& HV * Perl_gv_stashpv (pTHX_ const char *name, I32 flags)
9190 \& HV * gv_stashpvn( const char *name, U32 namelen,
9191 \& I32 flags)
9192 \& HV * Perl_gv_stashpvn(pTHX_ const char *name, U32 namelen,
9193 \& I32 flags)
9194 \& HV* gv_stashpvs( "name", I32 create)
9195 \& HV * gv_stashsv ( SV *sv, I32 flags)
9196 \& HV * Perl_gv_stashsv (pTHX_ SV *sv, I32 flags)
9197 .Ve
9198 .RE
9199 .RS 4
9200 .RE
9201 .ie n .IP """gv_SVadd*""" 4
9202 .el .IP \f(CWgv_SVadd*\fR 4
9203 .IX Item "gv_SVadd*"
9204 Described under \f(CW"gv_AVadd"\fR
9205 .ie n .IP """GvAV""" 4
9206 .el .IP \f(CWGvAV\fR 4
9207 .IX Xref "GvAV"
9208 .IX Item "GvAV"
9209 Return the AV from the GV.
9210 .RS 4
9211 .Sp
9212 .Vb 1
9213 \& AV* GvAV(GV* gv)
9214 .Ve
9215 .RE
9216 .RS 4
9217 .RE
9218 .ie n .IP """GvCV""" 4
9219 .el .IP \f(CWGvCV\fR 4
9220 .IX Xref "GvCV"
9221 .IX Item "GvCV"
9222 Return the CV from the GV.
9223 .RS 4
9224 .Sp
9225 .Vb 1
9226 \& CV* GvCV(GV* gv)
9227 .Ve
9228 .RE
9229 .RS 4
9230 .RE
9231 .ie n .IP """GvHV""" 4
9232 .el .IP \f(CWGvHV\fR 4
9233 .IX Xref "GvHV"
9234 .IX Item "GvHV"
9235 Return the HV from the GV.
9236 .RS 4
9237 .Sp
9238 .Vb 1
9239 \& HV* GvHV(GV* gv)
9240 .Ve
9241 .RE
9242 .RS 4
9243 .RE
9244 .ie n .IP """GvREFCNT_inc""" 4
9245 .el .IP \f(CWGvREFCNT_inc\fR 4
9246 .IX Item "GvREFCNT_inc"
9247 .PD 0
9248 .ie n .IP """GvREFCNT_inc_simple""" 4
9249 .el .IP \f(CWGvREFCNT_inc_simple\fR 4
9250 .IX Item "GvREFCNT_inc_simple"
9251 .ie n .IP """GvREFCNT_inc_simple_NN""" 4
9252 .el .IP \f(CWGvREFCNT_inc_simple_NN\fR 4
9253 .IX Xref "GvREFCNT_inc GvREFCNT_inc_simple GvREFCNT_inc_simple_NN"
9254 .IX Item "GvREFCNT_inc_simple_NN"
9255 .PD
9256 These all increment the reference count of the given SV, which must be a GV.
9257 They are useful when assigning the result into a typed pointer as they avoid
9258 the need to cast the result to the appropriate type.
9259 .RS 4
9260 .Sp
9261 .Vb 3
9262 \& GV * GvREFCNT_inc (GV *gv)
9263 \& GV * GvREFCNT_inc_simple (GV *gv)
9264 \& GV * GvREFCNT_inc_simple_NN(GV *gv)
9265 .Ve
9266 .RE
9267 .RS 4
9268 .RE
9269 .ie n .IP """GvSV""" 4
9270 .el .IP \f(CWGvSV\fR 4
9271 .IX Xref "GvSV"
9272 .IX Item "GvSV"
9273 Return the SV from the GV.
9274 .Sp
9275 Prior to Perl v5.9.3, this would add a scalar if none existed. Nowadays, use
9276 \&\f(CW"GvSVn"\fR for that, or compile perl with \f(CW\*(C`\-DPERL_CREATE_GVSV\*(C'\fR. See
9277 perl5100delta.
9278 .RS 4
9279 .Sp
9280 .Vb 1
9281 \& SV* GvSV(GV* gv)
9282 .Ve
9283 .RE
9284 .RS 4
9285 .RE
9286 .ie n .IP """GvSVn""" 4
9287 .el .IP \f(CWGvSVn\fR 4
9288 .IX Xref "GvSVn"
9289 .IX Item "GvSVn"
9290 Like \f(CW"GvSV"\fR, but creates an empty scalar if none already exists.
9291 .RS 4
9292 .Sp
9293 .Vb 1
9294 \& SV* GvSVn(GV* gv)
9295 .Ve
9296 .RE
9297 .RS 4
9298 .RE
9299 .ie n .IP """newGVgen""" 4
9300 .el .IP \f(CWnewGVgen\fR 4
9301 .IX Item "newGVgen"
9302 .PD 0
9303 .ie n .IP """newGVgen_flags""" 4
9304 .el .IP \f(CWnewGVgen_flags\fR 4
9305 .IX Xref "newGVgen newGVgen_flags"
9306 .IX Item "newGVgen_flags"
9307 .PD
9308 Create a new, guaranteed to be unique, GV in the package given by the
9309 NUL\-terminated C language string \f(CW\*(C`pack\*(C'\fR, and return a pointer to it.
9310 .Sp
9311 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
9312 considered to be encoded in Latin\-1. The only other legal \f(CW\*(C`flags\*(C'\fR value is
9313 \&\f(CW\*(C`SVf_UTF8\*(C'\fR, which indicates \f(CW\*(C`pack\*(C'\fR is to be considered to be encoded in
9314 UTF\-8.
9315 .RS 4
9316 .Sp
9317 .Vb 3
9318 \& GV * newGVgen ( const char *pack)
9319 \& GV * newGVgen_flags( const char *pack, U32 flags)
9320 \& GV * Perl_newGVgen_flags(pTHX_ const char *pack, U32 flags)
9321 .Ve
9322 .RE
9323 .RS 4
9324 .RE
9325 .ie n .IP """PL_curstash""" 4
9326 .el .IP \f(CWPL_curstash\fR 4
9327 .IX Xref "PL_curstash"
9328 .IX Item "PL_curstash"
9329 The stash for the package code will be compiled into.
9330 .Sp
9331 On threaded perls, each thread has an independent copy of this variable;
9332 each initialized at creation time with the current value of the creating
9333 thread\*(Aqs copy.
9334 .RS 4
9335 .Sp
9336 .Vb 1
9337 \& HV* PL_curstash
9338 .Ve
9339 .RE
9340 .RS 4
9341 .RE
9342 .ie n .IP """PL_defgv""" 4
9343 .el .IP \f(CWPL_defgv\fR 4
9344 .IX Xref "PL_defgv"
9345 .IX Item "PL_defgv"
9346 The GV representing \f(CW*_\fR. Useful for access to \f(CW$_\fR.
9347 .Sp
9348 On threaded perls, each thread has an independent copy of this variable;
9349 each initialized at creation time with the current value of the creating
9350 thread\*(Aqs copy.
9351 .RS 4
9352 .Sp
9353 .Vb 1
9354 \& GV * PL_defgv
9355 .Ve
9356 .RE
9357 .RS 4
9358 .RE
9359 .ie n .IP """PL_defoutgv""" 4
9360 .el .IP \f(CWPL_defoutgv\fR 4
9361 .IX Xref "PL_defoutgv"
9362 .IX Item "PL_defoutgv"
9363 See \f(CW"setdefout"\fR.
9364 .ie n .IP """PL_defstash""" 4
9365 .el .IP \f(CWPL_defstash\fR 4
9366 .IX Item "PL_defstash"
9367 Described in perlguts.
9368 .ie n .IP """save_gp""" 4
9369 .el .IP \f(CWsave_gp\fR 4
9370 .IX Xref "save_gp"
9371 .IX Item "save_gp"
9372 Saves the current GP of gv on the save stack to be restored on scope exit.
9373 .Sp
9374 If \f(CW\*(C`empty\*(C'\fR is true, replace the GP with a new GP.
9375 .Sp
9376 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
9377 assigned is localized, which is how \f(CW\*(C`\ local\ *foo\ =\ $someref;\ \*(C'\fR works.
9378 .RS 4
9379 .Sp
9380 .Vb 2
9381 \& void save_gp( GV *gv, I32 empty)
9382 \& void Perl_save_gp(pTHX_ GV *gv, I32 empty)
9383 .Ve
9384 .RE
9385 .RS 4
9386 .RE
9387 .ie n .IP """setdefout""" 4
9388 .el .IP \f(CWsetdefout\fR 4
9389 .IX Xref "setdefout"
9390 .IX Item "setdefout"
9391 Sets \f(CW\*(C`PL_defoutgv\*(C'\fR, the default file handle for output, to the passed in
9392 typeglob. As \f(CW\*(C`PL_defoutgv\*(C'\fR "owns" a reference on its typeglob, the reference
9393 count of the passed in typeglob is increased by one, and the reference count
9394 of the typeglob that \f(CW\*(C`PL_defoutgv\*(C'\fR points to is decreased by one.
9395 .RS 4
9396 .Sp
9397 .Vb 2
9398 \& void setdefout( GV *gv)
9399 \& void Perl_setdefout(pTHX_ GV *gv)
9400 .Ve
9401 .RE
9402 .RS 4
9403 .RE
9404 .SH "Hook manipulation"
9405 .IX Header "Hook manipulation"
9406 These functions provide convenient and thread\-safe means of manipulating
9407 hook variables.
9408 .ie n .IP """rcpv_copy""" 4
9409 .el .IP \f(CWrcpv_copy\fR 4
9410 .IX Xref "rcpv_copy"
9411 .IX Item "rcpv_copy"
9412 refcount increment a shared memory refcounted string, and when
9413 the refcount goes to 0 free it using \fBPerlMemShared_free()\fR.
9414 .Sp
9415 It is the callers responsibility to ensure that the pv is the
9416 result of a \fBrcpv_new()\fR call.
9417 .Sp
9418 Returns the same pointer that was passed in.
9419 .Sp
9420 .Vb 1
9421 \& new = rcpv_copy(pv);
9422 .Ve
9423 .RS 4
9424 .Sp
9425 .Vb 2
9426 \& char * rcpv_copy( char * const pv)
9427 \& char * Perl_rcpv_copy(pTHX_ char * const pv)
9428 .Ve
9429 .RE
9430 .RS 4
9431 .RE
9432 .ie n .IP """rcpv_free""" 4
9433 .el .IP \f(CWrcpv_free\fR 4
9434 .IX Xref "rcpv_free"
9435 .IX Item "rcpv_free"
9436 refcount decrement a shared memory refcounted string, and when
9437 the refcount goes to 0 free it using \fBperlmemshared_free()\fR.
9438 .Sp
9439 it is the callers responsibility to ensure that the pv is the
9440 result of a \fBrcpv_new()\fR call.
9441 .Sp
9442 Always returns NULL so it can be used like this:
9443 .Sp
9444 .Vb 1
9445 \& thing = rcpv_free(thing);
9446 .Ve
9447 .RS 4
9448 .Sp
9449 .Vb 2
9450 \& char * rcpv_free( char * const pv)
9451 \& char * Perl_rcpv_free(pTHX_ char * const pv)
9452 .Ve
9453 .RE
9454 .RS 4
9455 .RE
9456 .ie n .IP """rcpv_new""" 4
9457 .el .IP \f(CWrcpv_new\fR 4
9458 .IX Xref "rcpv_new"
9459 .IX Item "rcpv_new"
9460 Create a new shared memory refcounted string with the requested size, and
9461 with the requested initialization and a refcount of 1. The actual space
9462 allocated will be 1 byte more than requested and \fBrcpv_new()\fR will ensure that
9463 the extra byte is a null regardless of any flags settings.
9464 .Sp
9465 If the RCPVf_NO_COPY flag is set then the pv argument will be
9466 ignored, otherwise the contents of the pv pointer will be copied into
9467 the new buffer or if it is NULL the function will do nothing and return NULL.
9468 .Sp
9469 If the RCPVf_USE_STRLEN flag is set then the len argument is ignored and
9470 recomputed using \f(CWstrlen(pv)\fR. It is an error to combine RCPVf_USE_STRLEN
9471 and RCPVf_NO_COPY at the same time.
9472 .Sp
9473 Under DEBUGGING \fBrcpv_new()\fR will \fBassert()\fR if it is asked to create a 0 length
9474 shared string unless the RCPVf_ALLOW_EMPTY flag is set.
9475 .Sp
9476 The return value from the function is suitable for passing into \fBrcpv_copy()\fR and
9477 \&\fBrcpv_free()\fR. To access the RCPV * from the returned value use the \fBRCPVx()\fR macro.
9478 The \*(Aqlen\*(Aq member of the RCPV struct stores the allocated length (including the
9479 extra byte), but the \fBRCPV_LEN()\fR macro returns the requested length (not
9480 including the extra byte).
9481 .Sp
9482 Note that \fBrcpv_new()\fR does NOT use a hash table or anything like that to
9483 dedupe inputs given the same text content. Each call with a non\-null pv
9484 parameter will produce a distinct pointer with its own refcount regardless of
9485 the input content.
9486 .RS 4
9487 .Sp
9488 .Vb 4
9489 \& char * rcpv_new( const char * const pv, STRLEN len,
9490 \& U32 flags)
9491 \& char * Perl_rcpv_new(pTHX_ const char * const pv, STRLEN len,
9492 \& U32 flags)
9493 .Ve
9494 .RE
9495 .RS 4
9496 .RE
9497 .ie n .IP """wrap_op_checker""" 4
9498 .el .IP \f(CWwrap_op_checker\fR 4
9499 .IX Xref "wrap_op_checker"
9500 .IX Item "wrap_op_checker"
9501 Puts a C function into the chain of check functions for a specified op
9502 type. This is the preferred way to manipulate the "PL_check" array.
9503 \&\f(CW\*(C`opcode\*(C'\fR specifies which type of op is to be affected. \f(CW\*(C`new_checker\*(C'\fR
9504 is a pointer to the C function that is to be added to that opcode\*(Aqs
9505 check chain, and \f(CW\*(C`old_checker_p\*(C'\fR points to the storage location where a
9506 pointer to the next function in the chain will be stored. The value of
9507 \&\f(CW\*(C`new_checker\*(C'\fR is written into the "PL_check" array, while the value
9508 previously stored there is written to \f(CW*old_checker_p\fR.
9509 .Sp
9510 "PL_check" is global to an entire process, and a module wishing to
9511 hook op checking may find itself invoked more than once per process,
9512 typically in different threads. To handle that situation, this function
9513 is idempotent. The location \f(CW*old_checker_p\fR must initially (once
9514 per process) contain a null pointer. A C variable of static duration
9515 (declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give
9516 it internal linkage) will be implicitly initialised appropriately,
9517 if it does not have an explicit initialiser. This function will only
9518 actually modify the check chain if it finds \f(CW*old_checker_p\fR to be null.
9519 This function is also thread safe on the small scale. It uses appropriate
9520 locking to avoid race conditions in accessing "PL_check".
9521 .Sp
9522 When this function is called, the function referenced by \f(CW\*(C`new_checker\*(C'\fR
9523 must be ready to be called, except for \f(CW*old_checker_p\fR being unfilled.
9524 In a threading situation, \f(CW\*(C`new_checker\*(C'\fR may be called immediately,
9525 even before this function has returned. \f(CW*old_checker_p\fR will always
9526 be appropriately set before \f(CW\*(C`new_checker\*(C'\fR is called. If \f(CW\*(C`new_checker\*(C'\fR
9527 decides not to do anything special with an op that it is given (which
9528 is the usual case for most uses of op check hooking), it must chain the
9529 check function referenced by \f(CW*old_checker_p\fR.
9530 .Sp
9531 Taken all together, XS code to hook an op checker should typically look
9532 something like this:
9533 .Sp
9534 .Vb 9
9535 \& static Perl_check_t nxck_frob;
9536 \& static OP *myck_frob(pTHX_ OP *op) {
9537 \& ...
9538 \& op = nxck_frob(aTHX_ op);
9539 \& ...
9540 \& return op;
9541 \& }
9542 \& BOOT:
9543 \& wrap_op_checker(OP_FROB, myck_frob, &nxck_frob);
9544 .Ve
9545 .Sp
9546 If you want to influence compilation of calls to a specific subroutine,
9547 then use "cv_set_call_checker_flags" rather than hooking checking of
9548 all \f(CW\*(C`entersub\*(C'\fR ops.
9549 .RS 4
9550 .Sp
9551 .Vb 6
9552 \& void wrap_op_checker( Optype opcode,
9553 \& Perl_check_t new_checker,
9554 \& Perl_check_t *old_checker_p)
9555 \& void Perl_wrap_op_checker(pTHX_ Optype opcode,
9556 \& Perl_check_t new_checker,
9557 \& Perl_check_t *old_checker_p)
9558 .Ve
9559 .RE
9560 .RS 4
9561 .RE
9562 .SH "HV Handling"
9563 .IX Xref "HV_ITERNEXT_WANTPLACEHOLDERS HV_NAME_SETALL HvNAMELEN_get"
9564 .IX Header "HV Handling"
9565 A HV structure represents a Perl hash. It consists mainly of an array
9566 of pointers, each of which points to a linked list of HE structures. The
9567 array is indexed by the hash function of the key, so each linked list
9568 represents all the hash entries with the same hash value. Each HE contains
9569 a pointer to the actual value, plus a pointer to a HEK structure which
9570 holds the key and hash value.
9571 .ie n .IP """get_hv""" 4
9572 .el .IP \f(CWget_hv\fR 4
9573 .IX Xref "get_hv"
9574 .IX Item "get_hv"
9575 Returns the HV of the specified Perl hash. \f(CW\*(C`flags\*(C'\fR are passed to
9576 \&\f(CW\*(C`gv_fetchpv\*(C'\fR. If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
9577 Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero
9578 (ignoring \f(CW\*(C`SVf_UTF8\*(C'\fR) and the variable does not exist then \f(CW\*(C`NULL\*(C'\fR is
9579 returned.
9580 .Sp
9581 NOTE: the \f(CWperl_get_hv()\fR form is \fBdeprecated\fR.
9582 .RS 4
9583 .Sp
9584 .Vb 2
9585 \& HV * get_hv( const char *name, I32 flags)
9586 \& HV * Perl_get_hv(pTHX_ const char *name, I32 flags)
9587 .Ve
9588 .RE
9589 .RS 4
9590 .RE
9591 .ie n .IP """HE""" 4
9592 .el .IP \f(CWHE\fR 4
9593 .IX Item "HE"
9594 Described in perlguts.
9595 .ie n .IP """HEf_SVKEY""" 4
9596 .el .IP \f(CWHEf_SVKEY\fR 4
9597 .IX Xref "HEf_SVKEY"
9598 .IX Item "HEf_SVKEY"
9599 This flag, used in the length slot of hash entries and magic structures,
9600 specifies the structure contains an \f(CW\*(C`SV*\*(C'\fR pointer where a \f(CW\*(C`char*\*(C'\fR pointer
9601 is to be expected. (For information only\-\-not to be used).
9602 .ie n .IP """HeHASH""" 4
9603 .el .IP \f(CWHeHASH\fR 4
9604 .IX Xref "HeHASH"
9605 .IX Item "HeHASH"
9606 Returns the computed hash stored in the hash entry.
9607 .RS 4
9608 .Sp
9609 .Vb 1
9610 \& U32 HeHASH(HE* he)
9611 .Ve
9612 .RE
9613 .RS 4
9614 .RE
9615 .ie n .IP """HeKEY""" 4
9616 .el .IP \f(CWHeKEY\fR 4
9617 .IX Xref "HeKEY"
9618 .IX Item "HeKEY"
9619 Returns the actual pointer stored in the key slot of the hash entry. The
9620 pointer may be either \f(CW\*(C`char*\*(C'\fR or \f(CW\*(C`SV*\*(C'\fR, depending on the value of
9621 \&\f(CWHeKLEN()\fR. Can be assigned to. The \f(CWHePV()\fR or \f(CWHeSVKEY()\fR macros are
9622 usually preferable for finding the value of a key.
9623 .RS 4
9624 .Sp
9625 .Vb 1
9626 \& void* HeKEY(HE* he)
9627 .Ve
9628 .RE
9629 .RS 4
9630 .RE
9631 .ie n .IP """HeKLEN""" 4
9632 .el .IP \f(CWHeKLEN\fR 4
9633 .IX Xref "HeKLEN"
9634 .IX Item "HeKLEN"
9635 If this is negative, and amounts to \f(CW\*(C`HEf_SVKEY\*(C'\fR, it indicates the entry
9636 holds an \f(CW\*(C`SV*\*(C'\fR key. Otherwise, holds the actual length of the key. Can
9637 be assigned to. The \f(CWHePV()\fR macro is usually preferable for finding key
9638 lengths.
9639 .RS 4
9640 .Sp
9641 .Vb 1
9642 \& STRLEN HeKLEN(HE* he)
9643 .Ve
9644 .RE
9645 .RS 4
9646 .RE
9647 .ie n .IP """HePV""" 4
9648 .el .IP \f(CWHePV\fR 4
9649 .IX Xref "HePV"
9650 .IX Item "HePV"
9651 Returns the key slot of the hash entry as a \f(CW\*(C`char*\*(C'\fR value, doing any
9652 necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The length of the string
9653 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
9654 not care about what the length of the key is, you may use the global
9655 variable \f(CW\*(C`PL_na\*(C'\fR, though this is rather less efficient than using a local
9656 variable. Remember though, that hash keys in perl are free to contain
9657 embedded nulls, so using \f(CWstrlen()\fR or similar is not a good way to find
9658 the length of hash keys. This is very similar to the \f(CWSvPV()\fR macro
9659 described elsewhere in this document. See also \f(CW"HeUTF8"\fR.
9660 .Sp
9661 If you are using \f(CW\*(C`HePV\*(C'\fR to get values to pass to \f(CWnewSVpvn()\fR to create a
9662 new SV, you should consider using \f(CW\*(C`newSVhek(HeKEY_hek(he))\*(C'\fR as it is more
9663 efficient.
9664 .RS 4
9665 .Sp
9666 .Vb 1
9667 \& char* HePV(HE* he, STRLEN len)
9668 .Ve
9669 .RE
9670 .RS 4
9671 .RE
9672 .ie n .IP """HeSVKEY""" 4
9673 .el .IP \f(CWHeSVKEY\fR 4
9674 .IX Xref "HeSVKEY"
9675 .IX Item "HeSVKEY"
9676 Returns the key as an \f(CW\*(C`SV*\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if the hash entry does not
9677 contain an \f(CW\*(C`SV*\*(C'\fR key.
9678 .RS 4
9679 .Sp
9680 .Vb 1
9681 \& SV* HeSVKEY(HE* he)
9682 .Ve
9683 .RE
9684 .RS 4
9685 .RE
9686 .ie n .IP """HeSVKEY_force""" 4
9687 .el .IP \f(CWHeSVKEY_force\fR 4
9688 .IX Xref "HeSVKEY_force"
9689 .IX Item "HeSVKEY_force"
9690 Returns the key as an \f(CW\*(C`SV*\*(C'\fR. Will create and return a temporary mortal
9691 \&\f(CW\*(C`SV*\*(C'\fR if the hash entry contains only a \f(CW\*(C`char*\*(C'\fR key.
9692 .RS 4
9693 .Sp
9694 .Vb 1
9695 \& SV* HeSVKEY_force(HE* he)
9696 .Ve
9697 .RE
9698 .RS 4
9699 .RE
9700 .ie n .IP """HeSVKEY_set""" 4
9701 .el .IP \f(CWHeSVKEY_set\fR 4
9702 .IX Xref "HeSVKEY_set"
9703 .IX Item "HeSVKEY_set"
9704 Sets the key to a given \f(CW\*(C`SV*\*(C'\fR, taking care to set the appropriate flags to
9705 indicate the presence of an \f(CW\*(C`SV*\*(C'\fR key, and returns the same
9706 \&\f(CW\*(C`SV*\*(C'\fR.
9707 .RS 4
9708 .Sp
9709 .Vb 1
9710 \& SV* HeSVKEY_set(HE* he, SV* sv)
9711 .Ve
9712 .RE
9713 .RS 4
9714 .RE
9715 .ie n .IP """HeUTF8""" 4
9716 .el .IP \f(CWHeUTF8\fR 4
9717 .IX Xref "HeUTF8"
9718 .IX Item "HeUTF8"
9719 Returns whether the \f(CW\*(C`char *\*(C'\fR value returned by \f(CW\*(C`HePV\*(C'\fR is encoded in UTF\-8,
9720 doing any necessary dereferencing of possibly \f(CW\*(C`SV*\*(C'\fR keys. The value returned
9721 will be 0 or non\-0, not necessarily 1 (or even a value with any low bits set),
9722 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
9723 typedef for \f(CW\*(C`char\*(C'\fR.
9724 .RS 4
9725 .Sp
9726 .Vb 1
9727 \& U32 HeUTF8(HE* he)
9728 .Ve
9729 .RE
9730 .RS 4
9731 .RE
9732 .ie n .IP """HeVAL""" 4
9733 .el .IP \f(CWHeVAL\fR 4
9734 .IX Xref "HeVAL"
9735 .IX Item "HeVAL"
9736 Returns the value slot (type \f(CW\*(C`SV*\*(C'\fR)
9737 stored in the hash entry. Can be assigned
9738 to.
9739 .Sp
9740 .Vb 2
9741 \& SV *foo= HeVAL(hv);
9742 \& HeVAL(hv)= sv;
9743 .Ve
9744 .RS 4
9745 .Sp
9746 .Vb 1
9747 \& SV* HeVAL(HE* he)
9748 .Ve
9749 .RE
9750 .RS 4
9751 .RE
9752 .ie n .IP """HV""" 4
9753 .el .IP \f(CWHV\fR 4
9754 .IX Item "HV"
9755 Described in perlguts.
9756 .ie n .IP """hv_assert""" 4
9757 .el .IP \f(CWhv_assert\fR 4
9758 .IX Xref "hv_assert"
9759 .IX Item "hv_assert"
9760 Check that a hash is in an internally consistent state.
9761 .RS 4
9762 .Sp
9763 .Vb 1
9764 \& void Perl_hv_assert(pTHX_ HV *hv)
9765 .Ve
9766 .RE
9767 .RS 4
9768 .RE
9769 .ie n .IP """hv_bucket_ratio""" 4
9770 .el .IP \f(CWhv_bucket_ratio\fR 4
9771 .IX Xref "hv_bucket_ratio"
9772 .IX Item "hv_bucket_ratio"
9773 NOTE: \f(CW\*(C`hv_bucket_ratio\*(C'\fR is \fBexperimental\fR and may change or be
9774 removed without notice.
9775 .Sp
9776 If the hash is tied dispatches through to the SCALAR tied method,
9777 otherwise if the hash contains no keys returns 0, otherwise returns
9778 a mortal sv containing a string specifying the number of used buckets,
9779 followed by a slash, followed by the number of available buckets.
9780 .Sp
9781 This function is expensive, it must scan all of the buckets
9782 to determine which are used, and the count is NOT cached.
9783 In a large hash this could be a lot of buckets.
9784 .RS 4
9785 .Sp
9786 .Vb 2
9787 \& SV * hv_bucket_ratio( HV *hv)
9788 \& SV * Perl_hv_bucket_ratio(pTHX_ HV *hv)
9789 .Ve
9790 .RE
9791 .RS 4
9792 .RE
9793 .ie n .IP """hv_clear""" 4
9794 .el .IP \f(CWhv_clear\fR 4
9795 .IX Xref "hv_clear"
9796 .IX Item "hv_clear"
9797 Frees all the elements of a hash, leaving it empty.
9798 The XS equivalent of \f(CW\*(C`%hash = ()\*(C'\fR. See also "hv_undef".
9799 .Sp
9800 See "av_clear" for a note about the hash possibly being invalid on
9801 return.
9802 .RS 4
9803 .Sp
9804 .Vb 2
9805 \& void hv_clear( HV *hv)
9806 \& void Perl_hv_clear(pTHX_ HV *hv)
9807 .Ve
9808 .RE
9809 .RS 4
9810 .RE
9811 .ie n .IP """hv_clear_placeholders""" 4
9812 .el .IP \f(CWhv_clear_placeholders\fR 4
9813 .IX Xref "hv_clear_placeholders"
9814 .IX Item "hv_clear_placeholders"
9815 Clears any placeholders from a hash. If a restricted hash has any of its keys
9816 marked as readonly and the key is subsequently deleted, the key is not actually
9817 deleted but is marked by assigning it a value of \f(CW&PL_sv_placeholder\fR. This tags
9818 it so it will be ignored by future operations such as iterating over the hash,
9819 but will still allow the hash to have a value reassigned to the key at some
9820 future point. This function clears any such placeholder keys from the hash.
9821 See \f(CWHash::Util::lock_keys()\fR for an example of its
9822 use.
9823 .RS 4
9824 .Sp
9825 .Vb 2
9826 \& void hv_clear_placeholders( HV *hv)
9827 \& void Perl_hv_clear_placeholders(pTHX_ HV *hv)
9828 .Ve
9829 .RE
9830 .RS 4
9831 .RE
9832 .ie n .IP """hv_copy_hints_hv""" 4
9833 .el .IP \f(CWhv_copy_hints_hv\fR 4
9834 .IX Xref "hv_copy_hints_hv"
9835 .IX Item "hv_copy_hints_hv"
9836 A specialised version of "newHVhv" for copying \f(CW\*(C`%^H\*(C'\fR. \f(CW\*(C`ohv\*(C'\fR must be
9837 a pointer to a hash (which may have \f(CW\*(C`%^H\*(C'\fR magic, but should be generally
9838 non\-magical), or \f(CW\*(C`NULL\*(C'\fR (interpreted as an empty hash). The content
9839 of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash, which has the \f(CW\*(C`%^H\*(C'\fR\-specific magic
9840 added to it. A pointer to the new hash is returned.
9841 .RS 4
9842 .Sp
9843 .Vb 2
9844 \& HV * hv_copy_hints_hv( HV * const ohv)
9845 \& HV * Perl_hv_copy_hints_hv(pTHX_ HV * const ohv)
9846 .Ve
9847 .RE
9848 .RS 4
9849 .RE
9850 .ie n .IP """hv_delete""" 4
9851 .el .IP \f(CWhv_delete\fR 4
9852 .IX Item "hv_delete"
9853 .PD 0
9854 .ie n .IP """hv_deletes""" 4
9855 .el .IP \f(CWhv_deletes\fR 4
9856 .IX Item "hv_deletes"
9857 .ie n .IP """hv_delete_ent""" 4
9858 .el .IP \f(CWhv_delete_ent\fR 4
9859 .IX Xref "hv_delete hv_delete_ent hv_deletes"
9860 .IX Item "hv_delete_ent"
9861 .PD
9862 These each delete a key/value pair in the hash. The value\*(Aqs SV is removed from
9863 the hash, made mortal, and returned to the caller.
9864 .Sp
9865 In \f(CW\*(C`hv_deletes\*(C'\fR, the key must be a C language string literal, enclosed in
9866 double quotes. It is never treated as being in UTF\-8. There is no
9867 length_parameter.
9868 .Sp
9869 In \f(CW\*(C`hv_delete\*(C'\fR, the absolute value of \f(CW\*(C`klen\*(C'\fR is the length of the key; hence
9870 the key may contain embedded NUL characters. If \f(CW\*(C`klen\*(C'\fR is negative the key
9871 is assumed to be in UTF\-8\-encoded Unicode.
9872 .Sp
9873 In \f(CW\*(C`hv_delete_ent\*(C'\fR, the key is the PV in \f(CW\*(C`keysv\*(C'\fR, including its length and
9874 UTF8ness. \f(CW\*(C`hash\*(C'\fR can be a valid precomputed hash value, or 0 to ask for it to
9875 be computed.
9876 .Sp
9877 In all three, the \f(CW\*(C`flags\*(C'\fR value will normally be zero; if set to \f(CW\*(C`G_DISCARD\*(C'\fR
9878 then \f(CW\*(C`NULL\*(C'\fR will be returned. \f(CW\*(C`NULL\*(C'\fR will also be returned if the key is not
9879 found.
9880 .RS 4
9881 .Sp
9882 .Vb 9
9883 \& SV * hv_delete ( HV *hv, const char *key, I32 klen,
9884 \& I32 flags)
9885 \& SV * Perl_hv_delete (pTHX_ HV *hv, const char *key, I32 klen,
9886 \& I32 flags)
9887 \& SV * hv_deletes ( HV *hv, "key", U32 flags)
9888 \& SV * hv_delete_ent( HV *hv, SV *keysv, I32 flags,
9889 \& U32 hash)
9890 \& SV * Perl_hv_delete_ent(pTHX_ HV *hv, SV *keysv, I32 flags,
9891 \& U32 hash)
9892 .Ve
9893 .RE
9894 .RS 4
9895 .RE
9896 .ie n .IP """hv_exists""" 4
9897 .el .IP \f(CWhv_exists\fR 4
9898 .IX Item "hv_exists"
9899 .PD 0
9900 .ie n .IP """hv_existss""" 4
9901 .el .IP \f(CWhv_existss\fR 4
9902 .IX Item "hv_existss"
9903 .ie n .IP """hv_exists_ent""" 4
9904 .el .IP \f(CWhv_exists_ent\fR 4
9905 .IX Xref "hv_exists hv_exists_ent hv_existss"
9906 .IX Item "hv_exists_ent"
9907 .PD
9908 These each return a boolean indicating whether the specified hash key exists.
9909 They differ only in how the key is specified.
9910 .Sp
9911 In \f(CW\*(C`hv_existss\*(C'\fR, the key must be a C language string literal, enclosed in
9912 double quotes. It is never treated as being in UTF\-8. There is no
9913 length_parameter.
9914 .Sp
9915 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
9916 \&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode.
9917 \&\f(CW\*(C`key\*(C'\fR may contain embedded NUL characters.
9918 .Sp
9919 In \f(CW\*(C`hv_exists_ent\*(C'\fR, the key is specified by the SV \f(CW\*(C`keysv\*(C'\fR; its UTF8ness is
9920 the same as that SV. There is an additional parameter, \f(CW\*(C`hash\*(C'\fR, which can be a
9921 valid precomputed hash value, or 0 to ask for it to be computed.
9922 .RS 4
9923 .Sp
9924 .Vb 5
9925 \& bool hv_exists ( HV *hv, const char *key, I32 klen)
9926 \& bool Perl_hv_exists (pTHX_ HV *hv, const char *key, I32 klen)
9927 \& bool hv_existss ( HV *hv, "key")
9928 \& bool hv_exists_ent( HV *hv, SV *keysv, U32 hash)
9929 \& bool Perl_hv_exists_ent(pTHX_ HV *hv, SV *keysv, U32 hash)
9930 .Ve
9931 .RE
9932 .RS 4
9933 .RE
9934 .ie n .IP """hv_fetch""" 4
9935 .el .IP \f(CWhv_fetch\fR 4
9936 .IX Item "hv_fetch"
9937 .PD 0
9938 .ie n .IP """hv_fetchs""" 4
9939 .el .IP \f(CWhv_fetchs\fR 4
9940 .IX Xref "hv_fetch hv_fetchs"
9941 .IX Item "hv_fetchs"
9942 .PD
9943 These each return the SV which corresponds to the specified key in the hash.
9944 They differ only in how the key is specified.
9945 .Sp
9946 In \f(CW\*(C`hv_fetchs\*(C'\fR, the key must be a C language string literal, enclosed in
9947 double quotes. It is never treated as being in UTF\-8. There is no
9948 length_parameter.
9949 .Sp
9950 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
9951 \&\f(CW\*(C`klen\*(C'\fR is negative the key is assumed to be in UTF\-8\-encoded Unicode.
9952 \&\f(CW\*(C`key\*(C'\fR may contain embedded NUL characters.
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 5
9965 \& SV ** hv_fetch ( HV *hv, const char *key, I32 klen,
9966 \& I32 lval)
9967 \& SV ** Perl_hv_fetch (pTHX_ HV *hv, const char *key, I32 klen,
9968 \& I32 lval)
9969 \& SV** hv_fetchs( HV* hv, "key", I32 lval)
9970 .Ve
9971 .RE
9972 .RS 4
9973 .RE
9974 .ie n .IP """hv_fetch_ent""" 4
9975 .el .IP \f(CWhv_fetch_ent\fR 4
9976 .IX Xref "hv_fetch_ent"
9977 .IX Item "hv_fetch_ent"
9978 Returns the hash entry which corresponds to the specified key in the hash.
9979 \&\f(CW\*(C`hash\*(C'\fR must be a valid precomputed hash number for the given \f(CW\*(C`key\*(C'\fR, or 0
9980 if you want the function to compute it. IF \f(CW\*(C`lval\*(C'\fR is set then the fetch
9981 will be part of a store. Make sure the return value is non\-null before
9982 accessing it. The return value when \f(CW\*(C`hv\*(C'\fR is a tied hash is a pointer to a
9983 static location, so be sure to make a copy of the structure if you need to
9984 store it somewhere.
9985 .Sp
9986 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
9987 information on how to use this function on tied hashes.
9988 .RS 4
9989 .Sp
9990 .Vb 4
9991 \& HE * hv_fetch_ent( HV *hv, SV *keysv, I32 lval,
9992 \& U32 hash)
9993 \& HE * Perl_hv_fetch_ent(pTHX_ HV *hv, SV *keysv, I32 lval,
9994 \& U32 hash)
9995 .Ve
9996 .RE
9997 .RS 4
9998 .RE
9999 .ie n .IP """hv_fetchs*""" 4
10000 .el .IP \f(CWhv_fetchs*\fR 4
10001 .IX Item "hv_fetchs*"
10002 Described under \f(CW"hv_fetch"\fR
10003 .ie n .IP """hv_iterinit""" 4
10004 .el .IP \f(CWhv_iterinit\fR 4
10005 .IX Xref "hv_iterinit"
10006 .IX Item "hv_iterinit"
10007 Prepares a starting point to traverse a hash table. Returns the number of
10008 keys in the hash, including placeholders (i.e. the same as \f(CWHvTOTALKEYS(hv)\fR).
10009 The return value is currently only meaningful for hashes without tie magic.
10010 .Sp
10011 NOTE: Before version 5.004_65, \f(CW\*(C`hv_iterinit\*(C'\fR used to return the number of
10012 hash buckets that happen to be in use. If you still need that esoteric
10013 value, you can get it through the macro \f(CWHvFILL(hv)\fR.
10014 .RS 4
10015 .Sp
10016 .Vb 2
10017 \& I32 hv_iterinit( HV *hv)
10018 \& I32 Perl_hv_iterinit(pTHX_ HV *hv)
10019 .Ve
10020 .RE
10021 .RS 4
10022 .RE
10023 .ie n .IP """hv_iterkey""" 4
10024 .el .IP \f(CWhv_iterkey\fR 4
10025 .IX Xref "hv_iterkey"
10026 .IX Item "hv_iterkey"
10027 Returns the key from the current position of the hash iterator. See
10028 \&\f(CW"hv_iterinit"\fR.
10029 .RS 4
10030 .Sp
10031 .Vb 2
10032 \& char * hv_iterkey( HE *entry, I32 *retlen)
10033 \& char * Perl_hv_iterkey(pTHX_ HE *entry, I32 *retlen)
10034 .Ve
10035 .RE
10036 .RS 4
10037 .RE
10038 .ie n .IP """hv_iterkeysv""" 4
10039 .el .IP \f(CWhv_iterkeysv\fR 4
10040 .IX Xref "hv_iterkeysv"
10041 .IX Item "hv_iterkeysv"
10042 Returns the key as an \f(CW\*(C`SV*\*(C'\fR from the current position of the hash
10043 iterator. The return value will always be a mortal copy of the key. Also
10044 see \f(CW"hv_iterinit"\fR.
10045 .RS 4
10046 .Sp
10047 .Vb 2
10048 \& SV * hv_iterkeysv( HE *entry)
10049 \& SV * Perl_hv_iterkeysv(pTHX_ HE *entry)
10050 .Ve
10051 .RE
10052 .RS 4
10053 .RE
10054 .ie n .IP """hv_iternext""" 4
10055 .el .IP \f(CWhv_iternext\fR 4
10056 .IX Xref "hv_iternext"
10057 .IX Item "hv_iternext"
10058 Returns entries from a hash iterator. See \f(CW"hv_iterinit"\fR.
10059 .Sp
10060 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
10061 iterator currently points to, without losing your place or invalidating your
10062 iterator. Note that in this case the current entry is deleted from the hash
10063 with your iterator holding the last reference to it. Your iterator is flagged
10064 to free the entry on the next call to \f(CW\*(C`hv_iternext\*(C'\fR, so you must not discard
10065 your iterator immediately else the entry will leak \- call \f(CW\*(C`hv_iternext\*(C'\fR to
10066 trigger the resource deallocation.
10067 .RS 4
10068 .Sp
10069 .Vb 2
10070 \& HE * hv_iternext( HV *hv)
10071 \& HE * Perl_hv_iternext(pTHX_ HV *hv)
10072 .Ve
10073 .RE
10074 .RS 4
10075 .RE
10076 .ie n .IP """hv_iternext_flags""" 4
10077 .el .IP \f(CWhv_iternext_flags\fR 4
10078 .IX Xref "hv_iternext_flags"
10079 .IX Item "hv_iternext_flags"
10080 NOTE: \f(CW\*(C`hv_iternext_flags\*(C'\fR is \fBexperimental\fR and may change or be
10081 removed without notice.
10082 .Sp
10083 Returns entries from a hash iterator. See \f(CW"hv_iterinit"\fR and
10084 \&\f(CW"hv_iternext"\fR.
10085 The \f(CW\*(C`flags\*(C'\fR value will normally be zero; if \f(CW\*(C`HV_ITERNEXT_WANTPLACEHOLDERS\*(C'\fR is
10086 set the placeholders keys (for restricted hashes) will be returned in addition
10087 to normal keys. By default placeholders are automatically skipped over.
10088 Currently a placeholder is implemented with a value that is
10089 \&\f(CW&PL_sv_placeholder\fR. Note that the implementation of placeholders and
10090 restricted hashes may change, and the implementation currently is
10091 insufficiently abstracted for any change to be tidy.
10092 .RS 4
10093 .Sp
10094 .Vb 2
10095 \& HE * hv_iternext_flags( HV *hv, I32 flags)
10096 \& HE * Perl_hv_iternext_flags(pTHX_ HV *hv, I32 flags)
10097 .Ve
10098 .RE
10099 .RS 4
10100 .RE
10101 .ie n .IP """hv_iternextsv""" 4
10102 .el .IP \f(CWhv_iternextsv\fR 4
10103 .IX Xref "hv_iternextsv"
10104 .IX Item "hv_iternextsv"
10105 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
10106 operation.
10107 .RS 4
10108 .Sp
10109 .Vb 2
10110 \& SV * hv_iternextsv( HV *hv, char **key, I32 *retlen)
10111 \& SV * Perl_hv_iternextsv(pTHX_ HV *hv, char **key, I32 *retlen)
10112 .Ve
10113 .RE
10114 .RS 4
10115 .RE
10116 .ie n .IP """hv_iterval""" 4
10117 .el .IP \f(CWhv_iterval\fR 4
10118 .IX Xref "hv_iterval"
10119 .IX Item "hv_iterval"
10120 Returns the value from the current position of the hash iterator. See
10121 \&\f(CW"hv_iterkey"\fR.
10122 .RS 4
10123 .Sp
10124 .Vb 2
10125 \& SV * hv_iterval( HV *hv, HE *entry)
10126 \& SV * Perl_hv_iterval(pTHX_ HV *hv, HE *entry)
10127 .Ve
10128 .RE
10129 .RS 4
10130 .RE
10131 .ie n .IP """hv_ksplit""" 4
10132 .el .IP \f(CWhv_ksplit\fR 4
10133 .IX Xref "hv_ksplit"
10134 .IX Item "hv_ksplit"
10135 Attempt to grow the hash \f(CW\*(C`hv\*(C'\fR so it has at least \f(CW\*(C`newmax\*(C'\fR buckets available.
10136 Perl chooses the actual number for its convenience.
10137 .Sp
10138 This is the same as doing the following in Perl code:
10139 .Sp
10140 .Vb 1
10141 \& keys %hv = newmax;
10142 .Ve
10143 .RS 4
10144 .Sp
10145 .Vb 2
10146 \& void hv_ksplit( HV *hv, IV newmax)
10147 \& void Perl_hv_ksplit(pTHX_ HV *hv, IV newmax)
10148 .Ve
10149 .RE
10150 .RS 4
10151 .RE
10152 .ie n .IP """hv_magic""" 4
10153 .el .IP \f(CWhv_magic\fR 4
10154 .IX Xref "hv_magic"
10155 .IX Item "hv_magic"
10156 Adds magic to a hash. See \f(CW"sv_magic"\fR.
10157 .RS 4
10158 .Sp
10159 .Vb 2
10160 \& void hv_magic( HV *hv, GV *gv, int how)
10161 \& void Perl_hv_magic(pTHX_ HV *hv, GV *gv, int how)
10162 .Ve
10163 .RE
10164 .RS 4
10165 .RE
10166 .ie n .IP """hv_name_set""" 4
10167 .el .IP \f(CWhv_name_set\fR 4
10168 .IX Item "hv_name_set"
10169 .PD 0
10170 .ie n .IP """hv_name_sets""" 4
10171 .el .IP \f(CWhv_name_sets\fR 4
10172 .IX Xref "hv_name_set hv_name_sets"
10173 .IX Item "hv_name_sets"
10174 .PD
10175 These each set the name of stash \f(CW\*(C`hv\*(C'\fR to the specified name.
10176 .Sp
10177 They differ only in how the name is specified.
10178 .Sp
10179 In \f(CW\*(C`hv_name_sets\*(C'\fR, the name is a literal C string, enclosed in double quotes.
10180 .Sp
10181 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
10182 additional parameter, \f(CW\*(C`len\*(C'\fR, specifies its length in bytes. Hence, the name
10183 may contain embedded\-NUL characters.
10184 .Sp
10185 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;
10186 otherwise not.
10187 .Sp
10188 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
10189 are set.
10190 .RS 4
10191 .Sp
10192 .Vb 5
10193 \& void hv_name_set ( HV *hv, const char *name, U32 len,
10194 \& U32 flags)
10195 \& void Perl_hv_name_set (pTHX_ HV *hv, const char *name, U32 len,
10196 \& U32 flags)
10197 \& void hv_name_sets( HV *hv, "name", U32 flags)
10198 .Ve
10199 .RE
10200 .RS 4
10201 .RE
10202 .ie n .IP """hv_scalar""" 4
10203 .el .IP \f(CWhv_scalar\fR 4
10204 .IX Xref "hv_scalar"
10205 .IX Item "hv_scalar"
10206 Evaluates the hash in scalar context and returns the result.
10207 .Sp
10208 When the hash is tied dispatches through to the SCALAR method,
10209 otherwise returns a mortal SV containing the number of keys
10210 in the hash.
10211 .Sp
10212 Note, prior to 5.25 this function returned what is now
10213 returned by the \fBhv_bucket_ratio()\fR function.
10214 .RS 4
10215 .Sp
10216 .Vb 2
10217 \& SV * hv_scalar( HV *hv)
10218 \& SV * Perl_hv_scalar(pTHX_ HV *hv)
10219 .Ve
10220 .RE
10221 .RS 4
10222 .RE
10223 .ie n .IP """hv_store""" 4
10224 .el .IP \f(CWhv_store\fR 4
10225 .IX Item "hv_store"
10226 .PD 0
10227 .ie n .IP """hv_stores""" 4
10228 .el .IP \f(CWhv_stores\fR 4
10229 .IX Xref "hv_store hv_stores"
10230 .IX Item "hv_stores"
10231 .PD
10232 These each store SV \f(CW\*(C`val\*(C'\fR with the specified key in hash \f(CW\*(C`hv\*(C'\fR, returning NULL
10233 if the operation failed or if the value did not need to be actually stored
10234 within the hash (as in the case of tied hashes). Otherwise it can be
10235 dereferenced to get the original \f(CW\*(C`SV*\*(C'\fR.
10236 .Sp
10237 They differ only in how the hash key is specified.
10238 .Sp
10239 In \f(CW\*(C`hv_stores\*(C'\fR, the key must be a C language string literal, enclosed in
10240 double quotes. It is never treated as being in UTF\-8. There is no
10241 length_parameter.
10242 .Sp
10243 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
10244 specifying the key, and its length in bytes is given by the absolute value of
10245 an additional parameter, \f(CW\*(C`klen\*(C'\fR. A NULL key indicates the key is to be
10246 treated as \f(CW\*(C`undef\*(C'\fR, and \f(CW\*(C`klen\*(C'\fR is ignored; otherwise the key string may
10247 contain embedded\-NUL bytes. If \f(CW\*(C`klen\*(C'\fR is negative, the string is treated as
10248 being encoded in UTF\-8; otherwise not.
10249 .Sp
10250 \&\f(CW\*(C`hv_store\*(C'\fR has another extra parameter, \f(CW\*(C`hash\*(C'\fR, a precomputed hash of the key
10251 string, or zero if it has not been precomputed. This parameter is omitted from
10252 \&\f(CW\*(C`hv_stores\*(C'\fR, as it is computed automatically at compile time.
10253 .Sp
10254 If \f(CW\*(C`hv\*(C'\fR is NULL, NULL is returned and no action is taken.
10255 .Sp
10256 If \f(CW\*(C`val\*(C'\fR is NULL, it is treated as being \f(CW\*(C`undef\*(C'\fR; otherwise the caller is
10257 responsible for suitably incrementing the reference count of \f(CW\*(C`val\*(C'\fR before
10258 the call, and decrementing it if the function returned \f(CW\*(C`NULL\*(C'\fR. Effectively
10259 a successful \f(CW\*(C`hv_store\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is
10260 usually what you want; a newly created SV has a reference count of one, so
10261 if all your code does is create SVs and store them in a hash, \f(CW\*(C`hv_store\*(C'\fR
10262 will own the only reference to the new SV, and your code doesn\*(Aqt need to do
10263 anything further to tidy up.
10264 .Sp
10265 \&\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
10266 create a temporary SV for the key, so if your key data is not already in SV
10267 form, then use \f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR.
10268 .Sp
10269 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
10270 information on how to use this function on tied hashes.
10271 .RS 4
10272 .Sp
10273 .Vb 5
10274 \& SV ** hv_store ( HV *hv, const char *key, I32 klen,
10275 \& SV *val, U32 hash)
10276 \& SV ** Perl_hv_store (pTHX_ HV *hv, const char *key, I32 klen,
10277 \& SV *val, U32 hash)
10278 \& SV ** hv_stores( HV *hv, "key", SV *val)
10279 .Ve
10280 .RE
10281 .RS 4
10282 .RE
10283 .ie n .IP """hv_store_ent""" 4
10284 .el .IP \f(CWhv_store_ent\fR 4
10285 .IX Xref "hv_store_ent"
10286 .IX Item "hv_store_ent"
10287 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
10288 parameter is the precomputed hash value; if it is zero, then Perl will
10289 compute it. The return value is the new hash entry so created. It will be
10290 \&\f(CW\*(C`NULL\*(C'\fR if the operation failed or if the value did not need to be actually
10291 stored within the hash (as in the case of tied hashes). Otherwise the
10292 contents of the return value can be accessed using the \f(CW\*(C`He?\*(C'\fR macros
10293 described here. Note that the caller is responsible for suitably
10294 incrementing the reference count of \f(CW\*(C`val\*(C'\fR before the call, and
10295 decrementing it if the function returned NULL. Effectively a successful
10296 \&\f(CW\*(C`hv_store_ent\*(C'\fR takes ownership of one reference to \f(CW\*(C`val\*(C'\fR. This is
10297 usually what you want; a newly created SV has a reference count of one, so
10298 if all your code does is create SVs and store them in a hash, \f(CW\*(C`hv_store\*(C'\fR
10299 will own the only reference to the new SV, and your code doesn\*(Aqt need to do
10300 anything further to tidy up. Note that \f(CW\*(C`hv_store_ent\*(C'\fR only reads the \f(CW\*(C`key\*(C'\fR;
10301 unlike \f(CW\*(C`val\*(C'\fR it does not take ownership of it, so maintaining the correct
10302 reference count on \f(CW\*(C`key\*(C'\fR is entirely the caller\*(Aqs responsibility. The reason
10303 it does not take ownership is that \f(CW\*(C`key\*(C'\fR is not used after this function
10304 returns, and so can be freed immediately. \f(CW\*(C`hv_store\*(C'\fR
10305 is not implemented as a call to \f(CW\*(C`hv_store_ent\*(C'\fR, and does not create a temporary
10306 SV for the key, so if your key data is not already in SV form, then use
10307 \&\f(CW\*(C`hv_store\*(C'\fR in preference to \f(CW\*(C`hv_store_ent\*(C'\fR.
10308 .Sp
10309 See "Understanding the Magic of Tied Hashes and Arrays" in perlguts for more
10310 information on how to use this function on tied hashes.
10311 .RS 4
10312 .Sp
10313 .Vb 2
10314 \& HE * hv_store_ent( HV *hv, SV *key, SV *val, U32 hash)
10315 \& HE * Perl_hv_store_ent(pTHX_ HV *hv, SV *key, SV *val, U32 hash)
10316 .Ve
10317 .RE
10318 .RS 4
10319 .RE
10320 .ie n .IP """hv_stores*""" 4
10321 .el .IP \f(CWhv_stores*\fR 4
10322 .IX Item "hv_stores*"
10323 Described under \f(CW"hv_store"\fR
10324 .ie n .IP """hv_undef""" 4
10325 .el .IP \f(CWhv_undef\fR 4
10326 .IX Xref "hv_undef"
10327 .IX Item "hv_undef"
10328 Undefines the hash. The XS equivalent of \f(CWundef(%hash)\fR.
10329 .Sp
10330 As well as freeing all the elements of the hash (like \f(CWhv_clear()\fR), this
10331 also frees any auxiliary data and storage associated with the hash.
10332 .Sp
10333 See "av_clear" for a note about the hash possibly being invalid on
10334 return.
10335 .RS 4
10336 .Sp
10337 .Vb 1
10338 \& void hv_undef(HV *hv)
10339 .Ve
10340 .RE
10341 .RS 4
10342 .RE
10343 .ie n .IP """HvENAME""" 4
10344 .el .IP \f(CWHvENAME\fR 4
10345 .IX Xref "HvENAME"
10346 .IX Item "HvENAME"
10347 Returns the effective name of a stash, or NULL if there is none. The
10348 effective name represents a location in the symbol table where this stash
10349 resides. It is updated automatically when packages are aliased or deleted.
10350 A stash that is no longer in the symbol table has no effective name. This
10351 name is preferable to \f(CW\*(C`HvNAME\*(C'\fR for use in MRO linearisations and isa
10352 caches.
10353 .RS 4
10354 .Sp
10355 .Vb 1
10356 \& char* HvENAME(HV* stash)
10357 .Ve
10358 .RE
10359 .RS 4
10360 .RE
10361 .ie n .IP """HvENAMELEN""" 4
10362 .el .IP \f(CWHvENAMELEN\fR 4
10363 .IX Xref "HvENAMELEN"
10364 .IX Item "HvENAMELEN"
10365 Returns the length of the stash\*(Aqs effective name.
10366 .RS 4
10367 .Sp
10368 .Vb 1
10369 \& STRLEN HvENAMELEN(HV *stash)
10370 .Ve
10371 .RE
10372 .RS 4
10373 .RE
10374 .ie n .IP """HvENAMEUTF8""" 4
10375 .el .IP \f(CWHvENAMEUTF8\fR 4
10376 .IX Xref "HvENAMEUTF8"
10377 .IX Item "HvENAMEUTF8"
10378 Returns true if the effective name is in UTF\-8 encoding.
10379 .RS 4
10380 .Sp
10381 .Vb 1
10382 \& unsigned char HvENAMEUTF8(HV *stash)
10383 .Ve
10384 .RE
10385 .RS 4
10386 .RE
10387 .ie n .IP """HvFILL""" 4
10388 .el .IP \f(CWHvFILL\fR 4
10389 .IX Xref "HvFILL"
10390 .IX Item "HvFILL"
10391 Returns the number of hash buckets that happen to be in use.
10392 .Sp
10393 As of perl 5.25 this function is used only for debugging
10394 purposes, and the number of used hash buckets is not
10395 in any way cached, thus this function can be costly
10396 to execute as it must iterate over all the buckets in the
10397 hash.
10398 .RS 4
10399 .Sp
10400 .Vb 1
10401 \& STRLEN HvFILL(HV *const hv)
10402 .Ve
10403 .RE
10404 .RS 4
10405 .RE
10406 .ie n .IP """HvHasAUX""" 4
10407 .el .IP \f(CWHvHasAUX\fR 4
10408 .IX Xref "HvHasAUX"
10409 .IX Item "HvHasAUX"
10410 Returns true if the HV has a \f(CW\*(C`struct xpvhv_aux\*(C'\fR extension. Use this to check
10411 whether it is valid to call \f(CWHvAUX()\fR.
10412 .RS 4
10413 .Sp
10414 .Vb 1
10415 \& bool HvHasAUX(HV *const hv)
10416 .Ve
10417 .RE
10418 .RS 4
10419 .RE
10420 .ie n .IP """HvNAME""" 4
10421 .el .IP \f(CWHvNAME\fR 4
10422 .IX Xref "HvNAME"
10423 .IX Item "HvNAME"
10424 Returns the package name of a stash, or \f(CW\*(C`NULL\*(C'\fR if \f(CW\*(C`stash\*(C'\fR isn\*(Aqt a stash.
10425 See \f(CW"SvSTASH"\fR, \f(CW"CvSTASH"\fR.
10426 .RS 4
10427 .Sp
10428 .Vb 1
10429 \& char* HvNAME(HV* stash)
10430 .Ve
10431 .RE
10432 .RS 4
10433 .RE
10434 .ie n .IP """HvNAMELEN""" 4
10435 .el .IP \f(CWHvNAMELEN\fR 4
10436 .IX Xref "HvNAMELEN"
10437 .IX Item "HvNAMELEN"
10438 Returns the length of the stash\*(Aqs name.
10439 .Sp
10440 Disfavored forms of HvNAME and HvNAMELEN; suppress mention of them
10441 .RS 4
10442 .Sp
10443 .Vb 1
10444 \& STRLEN HvNAMELEN(HV *stash)
10445 .Ve
10446 .RE
10447 .RS 4
10448 .RE
10449 .ie n .IP """HvNAMEUTF8""" 4
10450 .el .IP \f(CWHvNAMEUTF8\fR 4
10451 .IX Xref "HvNAMEUTF8"
10452 .IX Item "HvNAMEUTF8"
10453 Returns true if the name is in UTF\-8 encoding.
10454 .RS 4
10455 .Sp
10456 .Vb 1
10457 \& unsigned char HvNAMEUTF8(HV *stash)
10458 .Ve
10459 .RE
10460 .RS 4
10461 .RE
10462 .ie n .IP """HvREFCNT_inc""" 4
10463 .el .IP \f(CWHvREFCNT_inc\fR 4
10464 .IX Item "HvREFCNT_inc"
10465 .PD 0
10466 .ie n .IP """HvREFCNT_inc_simple""" 4
10467 .el .IP \f(CWHvREFCNT_inc_simple\fR 4
10468 .IX Item "HvREFCNT_inc_simple"
10469 .ie n .IP """HvREFCNT_inc_simple_NN""" 4
10470 .el .IP \f(CWHvREFCNT_inc_simple_NN\fR 4
10471 .IX Xref "HvREFCNT_inc HvREFCNT_inc_simple HvREFCNT_inc_simple_NN"
10472 .IX Item "HvREFCNT_inc_simple_NN"
10473 .PD
10474 These all increment the reference count of the given SV, which must be a HV.
10475 They are useful when assigning the result into a typed pointer as they avoid
10476 the need to cast the result to the appropriate type.
10477 .RS 4
10478 .Sp
10479 .Vb 3
10480 \& HV * HvREFCNT_inc (HV *hv)
10481 \& HV * HvREFCNT_inc_simple (HV *hv)
10482 \& HV * HvREFCNT_inc_simple_NN(HV *hv)
10483 .Ve
10484 .RE
10485 .RS 4
10486 .RE
10487 .ie n .IP """newHV""" 4
10488 .el .IP \f(CWnewHV\fR 4
10489 .IX Xref "newHV"
10490 .IX Item "newHV"
10491 Creates a new HV. The reference count is set to 1.
10492 .RS 4
10493 .Sp
10494 .Vb 2
10495 \& HV * newHV()
10496 \& HV * Perl_newHV(pTHX)
10497 .Ve
10498 .RE
10499 .RS 4
10500 .RE
10501 .ie n .IP """newHVhv""" 4
10502 .el .IP \f(CWnewHVhv\fR 4
10503 .IX Xref "newHVhv"
10504 .IX Item "newHVhv"
10505 The content of \f(CW\*(C`ohv\*(C'\fR is copied to a new hash. A pointer to the new hash is
10506 returned.
10507 .RS 4
10508 .Sp
10509 .Vb 2
10510 \& HV * newHVhv( HV *hv)
10511 \& HV * Perl_newHVhv(pTHX_ HV *hv)
10512 .Ve
10513 .RE
10514 .RS 4
10515 .RE
10516 .ie n .IP """Nullhv""" 4
10517 .el .IP \f(CWNullhv\fR 4
10518 .IX Xref "Nullhv"
10519 .IX Item "Nullhv"
10520 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`Nullhv\*(C'\fR
10521 from a future release of Perl. Do not use it for
10522 new code; remove it from existing code.
10523 .Sp
10524 Null HV pointer.
10525 .Sp
10526 (deprecated \- use \f(CW\*(C`(HV *)NULL\*(C'\fR instead)
10527 .ie n .IP """PERL_HASH""" 4
10528 .el .IP \f(CWPERL_HASH\fR 4
10529 .IX Item "PERL_HASH"
10530 Described in perlguts.
10531 .RS 4
10532 .Sp
10533 .Vb 1
10534 \& void PERL_HASH(U32 hash, char *key, STRLEN klen)
10535 .Ve
10536 .RE
10537 .RS 4
10538 .RE
10539 .ie n .IP """PL_modglobal""" 4
10540 .el .IP \f(CWPL_modglobal\fR 4
10541 .IX Xref "PL_modglobal"
10542 .IX Item "PL_modglobal"
10543 \&\f(CW\*(C`PL_modglobal\*(C'\fR is a general purpose, interpreter global HV for use by
10544 extensions that need to keep information on a per\-interpreter basis.
10545 In a pinch, it can also be used as a symbol table for extensions
10546 to share data among each other. It is a good idea to use keys
10547 prefixed by the package name of the extension that owns the data.
10548 .Sp
10549 On threaded perls, each thread has an independent copy of this variable;
10550 each initialized at creation time with the current value of the creating
10551 thread\*(Aqs copy.
10552 .RS 4
10553 .Sp
10554 .Vb 1
10555 \& HV* PL_modglobal
10556 .Ve
10557 .RE
10558 .RS 4
10559 .RE
10560 .SH Input/Output
10561 .IX Header "Input/Output"
10562 .ie n .IP """do_close""" 4
10563 .el .IP \f(CWdo_close\fR 4
10564 .IX Xref "do_close"
10565 .IX Item "do_close"
10566 Close an I/O stream. This implements Perl "\f(CW\*(C`close\*(C'\fR" in perlfunc.
10567 .Sp
10568 \&\f(CW\*(C`gv\*(C'\fR is the glob associated with the stream.
10569 .Sp
10570 \&\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
10571 if it is part of another operation, such as closing a pipe (which involves
10572 implicitly closing both ends).
10573 .Sp
10574 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
10575 indicate the cause.
10576 .RS 4
10577 .Sp
10578 .Vb 2
10579 \& bool do_close( GV *gv, bool is_explicit)
10580 \& bool Perl_do_close(pTHX_ GV *gv, bool is_explicit)
10581 .Ve
10582 .RE
10583 .RS 4
10584 .RE
10585 .ie n .IP """IoDIRP""" 4
10586 .el .IP \f(CWIoDIRP\fR 4
10587 .IX Item "IoDIRP"
10588 .PD 0
10589 .ie n .IP """IOf_FLUSH""" 4
10590 .el .IP \f(CWIOf_FLUSH\fR 4
10591 .IX Item "IOf_FLUSH"
10592 .ie n .IP """IOf_UNTAINT""" 4
10593 .el .IP \f(CWIOf_UNTAINT\fR 4
10594 .IX Item "IOf_UNTAINT"
10595 .ie n .IP """IoFLAGS""" 4
10596 .el .IP \f(CWIoFLAGS\fR 4
10597 .IX Item "IoFLAGS"
10598 .ie n .IP """IoIFP""" 4
10599 .el .IP \f(CWIoIFP\fR 4
10600 .IX Item "IoIFP"
10601 .ie n .IP """IoOFP""" 4
10602 .el .IP \f(CWIoOFP\fR 4
10603 .IX Item "IoOFP"
10604 .ie n .IP """IoTYPE""" 4
10605 .el .IP \f(CWIoTYPE\fR 4
10606 .IX Item "IoTYPE"
10607 .PD
10608 Described in perlguts.
10609 .RS 4
10610 .Sp
10611 .Vb 5
10612 \& DIR * IoDIRP (IO *io)
10613 \& U8 IoFLAGS(IO *io)
10614 \& PerlIO * IoIFP (IO *io)
10615 \& PerlIO * IoOFP (IO *io)
10616 \& char IoTYPE (IO *io)
10617 .Ve
10618 .RE
10619 .RS 4
10620 .RE
10621 .ie n .IP """my_chsize""" 4
10622 .el .IP \f(CWmy_chsize\fR 4
10623 .IX Xref "my_chsize"
10624 .IX Item "my_chsize"
10625 The C library \fBchsize\fR\|(3) if available, or a Perl implementation of it.
10626 .RS 4
10627 .Sp
10628 .Vb 2
10629 \& I32 my_chsize( int fd, Off_t length)
10630 \& I32 Perl_my_chsize(pTHX_ int fd, Off_t length)
10631 .Ve
10632 .RE
10633 .RS 4
10634 .RE
10635 .ie n .IP """my_dirfd""" 4
10636 .el .IP \f(CWmy_dirfd\fR 4
10637 .IX Xref "my_dirfd"
10638 .IX Item "my_dirfd"
10639 The C library \f(CW\*(C`\fR\f(CBdirfd\fR\f(CW\|(3)\*(C'\fR if available, or a Perl implementation of it, or die
10640 if not easily emulatable.
10641 .RS 4
10642 .Sp
10643 .Vb 2
10644 \& int my_dirfd(DIR *dir)
10645 \& int Perl_my_dirfd(DIR *dir)
10646 .Ve
10647 .RE
10648 .RS 4
10649 .RE
10650 .ie n .IP """my_pclose""" 4
10651 .el .IP \f(CWmy_pclose\fR 4
10652 .IX Xref "my_pclose"
10653 .IX Item "my_pclose"
10654 A wrapper for the C library \fBpclose\fR\|(3). Don\*(Aqt use the latter, as the Perl
10655 version knows things that interact with the rest of the perl interpreter.
10656 .RS 4
10657 .Sp
10658 .Vb 2
10659 \& I32 my_pclose( PerlIO *ptr)
10660 \& I32 Perl_my_pclose(pTHX_ PerlIO *ptr)
10661 .Ve
10662 .RE
10663 .RS 4
10664 .RE
10665 .ie n .IP """my_popen""" 4
10666 .el .IP \f(CWmy_popen\fR 4
10667 .IX Xref "my_popen"
10668 .IX Item "my_popen"
10669 A wrapper for the C library \fBpopen\fR\|(3). Don\*(Aqt use the latter, as the Perl
10670 version knows things that interact with the rest of the perl interpreter.
10671 .RS 4
10672 .Sp
10673 .Vb 2
10674 \& PerlIO * my_popen( const char *cmd, const char *mode)
10675 \& PerlIO * Perl_my_popen(pTHX_ const char *cmd, const char *mode)
10676 .Ve
10677 .RE
10678 .RS 4
10679 .RE
10680 .ie n .IP """newIO""" 4
10681 .el .IP \f(CWnewIO\fR 4
10682 .IX Xref "newIO"
10683 .IX Item "newIO"
10684 Create a new IO, setting the reference count to 1.
10685 .RS 4
10686 .Sp
10687 .Vb 2
10688 \& IO * newIO()
10689 \& IO * Perl_newIO(pTHX)
10690 .Ve
10691 .RE
10692 .RS 4
10693 .RE
10694 .ie n .IP """PERL_FLUSHALL_FOR_CHILD""" 4
10695 .el .IP \f(CWPERL_FLUSHALL_FOR_CHILD\fR 4
10696 .IX Xref "PERL_FLUSHALL_FOR_CHILD"
10697 .IX Item "PERL_FLUSHALL_FOR_CHILD"
10698 This defines a way to flush all output buffers. This may be a
10699 performance issue, so we allow people to disable it. Also, if
10700 we are using stdio, there are broken implementations of fflush(NULL)
10701 out there, Solaris being the most prominent.
10702 .RS 4
10703 .Sp
10704 .Vb 1
10705 \& void PERL_FLUSHALL_FOR_CHILD
10706 .Ve
10707 .RE
10708 .RS 4
10709 .RE
10710 .ie n .IP """PerlIO_apply_layers""" 4
10711 .el .IP \f(CWPerlIO_apply_layers\fR 4
10712 .IX Item "PerlIO_apply_layers"
10713 .PD 0
10714 .ie n .IP """PerlIO_binmode""" 4
10715 .el .IP \f(CWPerlIO_binmode\fR 4
10716 .IX Item "PerlIO_binmode"
10717 .ie n .IP """PerlIO_canset_cnt""" 4
10718 .el .IP \f(CWPerlIO_canset_cnt\fR 4
10719 .IX Item "PerlIO_canset_cnt"
10720 .ie n .IP """PerlIO_clearerr""" 4
10721 .el .IP \f(CWPerlIO_clearerr\fR 4
10722 .IX Item "PerlIO_clearerr"
10723 .ie n .IP """PerlIO_close""" 4
10724 .el .IP \f(CWPerlIO_close\fR 4
10725 .IX Item "PerlIO_close"
10726 .ie n .IP """PerlIO_debug""" 4
10727 .el .IP \f(CWPerlIO_debug\fR 4
10728 .IX Item "PerlIO_debug"
10729 .ie n .IP """PerlIO_eof""" 4
10730 .el .IP \f(CWPerlIO_eof\fR 4
10731 .IX Item "PerlIO_eof"
10732 .ie n .IP """PerlIO_error""" 4
10733 .el .IP \f(CWPerlIO_error\fR 4
10734 .IX Item "PerlIO_error"
10735 .ie n .IP """PerlIO_exportFILE""" 4
10736 .el .IP \f(CWPerlIO_exportFILE\fR 4
10737 .IX Item "PerlIO_exportFILE"
10738 .ie n .IP """PerlIO_fast_gets""" 4
10739 .el .IP \f(CWPerlIO_fast_gets\fR 4
10740 .IX Item "PerlIO_fast_gets"
10741 .ie n .IP """PerlIO_fdopen""" 4
10742 .el .IP \f(CWPerlIO_fdopen\fR 4
10743 .IX Item "PerlIO_fdopen"
10744 .ie n .IP """PerlIO_fileno""" 4
10745 .el .IP \f(CWPerlIO_fileno\fR 4
10746 .IX Item "PerlIO_fileno"
10747 .ie n .IP """PerlIO_fill""" 4
10748 .el .IP \f(CWPerlIO_fill\fR 4
10749 .IX Item "PerlIO_fill"
10750 .ie n .IP """PerlIO_findFILE""" 4
10751 .el .IP \f(CWPerlIO_findFILE\fR 4
10752 .IX Item "PerlIO_findFILE"
10753 .ie n .IP """PerlIO_flush""" 4
10754 .el .IP \f(CWPerlIO_flush\fR 4
10755 .IX Item "PerlIO_flush"
10756 .ie n .IP """PerlIO_get_base""" 4
10757 .el .IP \f(CWPerlIO_get_base\fR 4
10758 .IX Item "PerlIO_get_base"
10759 .ie n .IP """PerlIO_get_bufsiz""" 4
10760 .el .IP \f(CWPerlIO_get_bufsiz\fR 4
10761 .IX Item "PerlIO_get_bufsiz"
10762 .ie n .IP """PerlIO_get_cnt""" 4
10763 .el .IP \f(CWPerlIO_get_cnt\fR 4
10764 .IX Item "PerlIO_get_cnt"
10765 .ie n .IP """PerlIO_get_ptr""" 4
10766 .el .IP \f(CWPerlIO_get_ptr\fR 4
10767 .IX Item "PerlIO_get_ptr"
10768 .ie n .IP """PerlIO_getc""" 4
10769 .el .IP \f(CWPerlIO_getc\fR 4
10770 .IX Item "PerlIO_getc"
10771 .ie n .IP """PerlIO_getpos""" 4
10772 .el .IP \f(CWPerlIO_getpos\fR 4
10773 .IX Item "PerlIO_getpos"
10774 .ie n .IP """PerlIO_has_base""" 4
10775 .el .IP \f(CWPerlIO_has_base\fR 4
10776 .IX Item "PerlIO_has_base"
10777 .ie n .IP """PerlIO_has_cntptr""" 4
10778 .el .IP \f(CWPerlIO_has_cntptr\fR 4
10779 .IX Item "PerlIO_has_cntptr"
10780 .ie n .IP """PerlIO_importFILE""" 4
10781 .el .IP \f(CWPerlIO_importFILE\fR 4
10782 .IX Item "PerlIO_importFILE"
10783 .ie n .IP """PerlIO_open""" 4
10784 .el .IP \f(CWPerlIO_open\fR 4
10785 .IX Item "PerlIO_open"
10786 .ie n .IP """PerlIO_printf""" 4
10787 .el .IP \f(CWPerlIO_printf\fR 4
10788 .IX Item "PerlIO_printf"
10789 .ie n .IP """PerlIO_putc""" 4
10790 .el .IP \f(CWPerlIO_putc\fR 4
10791 .IX Item "PerlIO_putc"
10792 .ie n .IP """PerlIO_puts""" 4
10793 .el .IP \f(CWPerlIO_puts\fR 4
10794 .IX Item "PerlIO_puts"
10795 .ie n .IP """PerlIO_read""" 4
10796 .el .IP \f(CWPerlIO_read\fR 4
10797 .IX Item "PerlIO_read"
10798 .ie n .IP """PerlIO_releaseFILE""" 4
10799 .el .IP \f(CWPerlIO_releaseFILE\fR 4
10800 .IX Item "PerlIO_releaseFILE"
10801 .ie n .IP """PerlIO_reopen""" 4
10802 .el .IP \f(CWPerlIO_reopen\fR 4
10803 .IX Item "PerlIO_reopen"
10804 .ie n .IP """PerlIO_rewind""" 4
10805 .el .IP \f(CWPerlIO_rewind\fR 4
10806 .IX Item "PerlIO_rewind"
10807 .ie n .IP """PerlIO_seek""" 4
10808 .el .IP \f(CWPerlIO_seek\fR 4
10809 .IX Item "PerlIO_seek"
10810 .ie n .IP """PerlIO_set_cnt""" 4
10811 .el .IP \f(CWPerlIO_set_cnt\fR 4
10812 .IX Item "PerlIO_set_cnt"
10813 .ie n .IP """PerlIO_set_ptrcnt""" 4
10814 .el .IP \f(CWPerlIO_set_ptrcnt\fR 4
10815 .IX Item "PerlIO_set_ptrcnt"
10816 .ie n .IP """PerlIO_setlinebuf""" 4
10817 .el .IP \f(CWPerlIO_setlinebuf\fR 4
10818 .IX Item "PerlIO_setlinebuf"
10819 .ie n .IP """PerlIO_setpos""" 4
10820 .el .IP \f(CWPerlIO_setpos\fR 4
10821 .IX Item "PerlIO_setpos"
10822 .ie n .IP """PerlIO_stderr""" 4
10823 .el .IP \f(CWPerlIO_stderr\fR 4
10824 .IX Item "PerlIO_stderr"
10825 .ie n .IP """PerlIO_stdin""" 4
10826 .el .IP \f(CWPerlIO_stdin\fR 4
10827 .IX Item "PerlIO_stdin"
10828 .ie n .IP """PerlIO_stdout""" 4
10829 .el .IP \f(CWPerlIO_stdout\fR 4
10830 .IX Item "PerlIO_stdout"
10831 .ie n .IP """PerlIO_stdoutf""" 4
10832 .el .IP \f(CWPerlIO_stdoutf\fR 4
10833 .IX Item "PerlIO_stdoutf"
10834 .ie n .IP """PerlIO_tell""" 4
10835 .el .IP \f(CWPerlIO_tell\fR 4
10836 .IX Item "PerlIO_tell"
10837 .ie n .IP """PerlIO_ungetc""" 4
10838 .el .IP \f(CWPerlIO_ungetc\fR 4
10839 .IX Item "PerlIO_ungetc"
10840 .ie n .IP """PerlIO_unread""" 4
10841 .el .IP \f(CWPerlIO_unread\fR 4
10842 .IX Item "PerlIO_unread"
10843 .ie n .IP """PerlIO_vprintf""" 4
10844 .el .IP \f(CWPerlIO_vprintf\fR 4
10845 .IX Item "PerlIO_vprintf"
10846 .ie n .IP """PerlIO_write""" 4
10847 .el .IP \f(CWPerlIO_write\fR 4
10848 .IX Xref "PerlIO_fill PerlIO_unread"
10849 .IX Item "PerlIO_write"
10850 .PD
10851 Described in perlapio.
10852 .RS 4
10853 .Sp
10854 .Vb 10
10855 \& int PerlIO_apply_layers(pTHX_ PerlIO *f,
10856 \& const char *mode,
10857 \& const char *layers)
10858 \& int PerlIO_binmode (pTHX_ PerlIO *f, int ptype,
10859 \& int imode,
10860 \& const char *layers)
10861 \& int PerlIO_canset_cnt ( PerlIO *f)
10862 \& void PerlIO_clearerr ( PerlIO *f)
10863 \& void Perl_PerlIO_clearerr (pTHX_ PerlIO *f)
10864 \& int PerlIO_close ( PerlIO *f)
10865 \& int Perl_PerlIO_close (pTHX_ PerlIO *f)
10866 \& void PerlIO_debug ( const char *fmt, ...)
10867 \& int PerlIO_eof ( PerlIO *f)
10868 \& int Perl_PerlIO_eof (pTHX_ PerlIO *f)
10869 \& int PerlIO_error ( PerlIO *f)
10870 \& int Perl_PerlIO_error (pTHX_ PerlIO *f)
10871 \& FILE * PerlIO_exportFILE ( PerlIO *f,
10872 \& const char *mode)
10873 \& int PerlIO_fast_gets ( PerlIO *f)
10874 \& PerlIO * PerlIO_fdopen ( int fd,
10875 \& const char *mode)
10876 \& int PerlIO_fileno ( PerlIO *f)
10877 \& int Perl_PerlIO_fileno (pTHX_ PerlIO *f)
10878 \& int PerlIO_fill ( PerlIO *f)
10879 \& int Perl_PerlIO_fill (pTHX_ PerlIO *f)
10880 \& FILE * PerlIO_findFILE ( PerlIO *f)
10881 \& int PerlIO_flush ( PerlIO *f)
10882 \& int Perl_PerlIO_flush (pTHX_ PerlIO *f)
10883 \& STDCHAR * PerlIO_get_base ( PerlIO *f)
10884 \& STDCHAR * Perl_PerlIO_get_base (pTHX_ PerlIO *f)
10885 \& SSize_t PerlIO_get_bufsiz ( PerlIO *f)
10886 \& SSize_t Perl_PerlIO_get_bufsiz (pTHX_ PerlIO *f)
10887 \& SSize_t PerlIO_get_cnt ( PerlIO *f)
10888 \& SSize_t Perl_PerlIO_get_cnt (pTHX_ PerlIO *f)
10889 \& STDCHAR * PerlIO_get_ptr ( PerlIO *f)
10890 \& STDCHAR * Perl_PerlIO_get_ptr (pTHX_ PerlIO *f)
10891 \& int PerlIO_getc ( PerlIO *d)
10892 \& int PerlIO_getpos ( PerlIO *f, SV *save)
10893 \& int PerlIO_has_base ( PerlIO *f)
10894 \& int PerlIO_has_cntptr ( PerlIO *f)
10895 \& PerlIO * PerlIO_importFILE ( FILE *stdio,
10896 \& const char *mode)
10897 \& PerlIO * PerlIO_open ( const char *path,
10898 \& const char *mode)
10899 \& int PerlIO_printf ( PerlIO *f,
10900 \& const char *fmt, ...)
10901 \& int PerlIO_putc ( PerlIO *f, int ch)
10902 \& int PerlIO_puts ( PerlIO *f,
10903 \& const char *string)
10904 \& SSize_t PerlIO_read ( PerlIO *f, void *vbuf,
10905 \& Size_t count)
10906 \& SSize_t Perl_PerlIO_read (pTHX_ PerlIO *f, void *vbuf,
10907 \& Size_t count)
10908 \& void PerlIO_releaseFILE ( PerlIO *f, FILE *stdio)
10909 \& PerlIO * PerlIO_reopen ( const char *path,
10910 \& const char *mode,
10911 \& PerlIO *old)
10912 \& void PerlIO_rewind ( PerlIO *f)
10913 \& int PerlIO_seek ( PerlIO *f,
10914 \& Off_t offset,
10915 \& int whence)
10916 \& int Perl_PerlIO_seek (pTHX_ PerlIO *f,
10917 \& Off_t offset,
10918 \& int whence)
10919 \& void PerlIO_set_cnt ( PerlIO *f, SSize_t cnt)
10920 \& void Perl_PerlIO_set_cnt (pTHX_ PerlIO *f, SSize_t cnt)
10921 \& void PerlIO_set_ptrcnt ( PerlIO *f,
10922 \& STDCHAR *ptr,
10923 \& SSize_t cnt)
10924 \& void Perl_PerlIO_set_ptrcnt (pTHX_ PerlIO *f,
10925 \& STDCHAR *ptr,
10926 \& SSize_t cnt)
10927 \& void PerlIO_setlinebuf ( PerlIO *f)
10928 \& void Perl_PerlIO_setlinebuf (pTHX_ PerlIO *f)
10929 \& int PerlIO_setpos ( PerlIO *f, SV *saved)
10930 \& PerlIO * PerlIO_stderr ()
10931 \& PerlIO * Perl_PerlIO_stderr (pTHX)
10932 \& PerlIO * PerlIO_stdin ()
10933 \& PerlIO * Perl_PerlIO_stdin (pTHX)
10934 \& PerlIO * PerlIO_stdout ()
10935 \& PerlIO * Perl_PerlIO_stdout (pTHX)
10936 \& int PerlIO_stdoutf ( const char *fmt, ...)
10937 \& Off_t PerlIO_tell ( PerlIO *f)
10938 \& Off_t Perl_PerlIO_tell (pTHX_ PerlIO *f)
10939 \& int PerlIO_ungetc ( PerlIO *f, int ch)
10940 \& SSize_t PerlIO_unread ( PerlIO *f,
10941 \& const void *vbuf,
10942 \& Size_t count)
10943 \& SSize_t Perl_PerlIO_unread (pTHX_ PerlIO *f,
10944 \& const void *vbuf,
10945 \& Size_t count)
10946 \& int PerlIO_vprintf ( PerlIO *f,
10947 \& const char *fmt,
10948 \& va_list args)
10949 \& SSize_t PerlIO_write ( PerlIO *f,
10950 \& const void *vbuf,
10951 \& Size_t count)
10952 \& SSize_t Perl_PerlIO_write (pTHX_ PerlIO *f,
10953 \& const void *vbuf,
10954 \& Size_t count)
10955 .Ve
10956 .RE
10957 .RS 4
10958 .RE
10959 .ie n .IP """PERLIO_F_APPEND""" 4
10960 .el .IP \f(CWPERLIO_F_APPEND\fR 4
10961 .IX Item "PERLIO_F_APPEND"
10962 .PD 0
10963 .ie n .IP """PERLIO_F_CANREAD""" 4
10964 .el .IP \f(CWPERLIO_F_CANREAD\fR 4
10965 .IX Item "PERLIO_F_CANREAD"
10966 .ie n .IP """PERLIO_F_CANWRITE""" 4
10967 .el .IP \f(CWPERLIO_F_CANWRITE\fR 4
10968 .IX Item "PERLIO_F_CANWRITE"
10969 .ie n .IP """PERLIO_F_CRLF""" 4
10970 .el .IP \f(CWPERLIO_F_CRLF\fR 4
10971 .IX Item "PERLIO_F_CRLF"
10972 .ie n .IP """PERLIO_F_EOF""" 4
10973 .el .IP \f(CWPERLIO_F_EOF\fR 4
10974 .IX Item "PERLIO_F_EOF"
10975 .ie n .IP """PERLIO_F_ERROR""" 4
10976 .el .IP \f(CWPERLIO_F_ERROR\fR 4
10977 .IX Item "PERLIO_F_ERROR"
10978 .ie n .IP """PERLIO_F_FASTGETS""" 4
10979 .el .IP \f(CWPERLIO_F_FASTGETS\fR 4
10980 .IX Item "PERLIO_F_FASTGETS"
10981 .ie n .IP """PERLIO_F_LINEBUF""" 4
10982 .el .IP \f(CWPERLIO_F_LINEBUF\fR 4
10983 .IX Item "PERLIO_F_LINEBUF"
10984 .ie n .IP """PERLIO_F_OPEN""" 4
10985 .el .IP \f(CWPERLIO_F_OPEN\fR 4
10986 .IX Item "PERLIO_F_OPEN"
10987 .ie n .IP """PERLIO_F_RDBUF""" 4
10988 .el .IP \f(CWPERLIO_F_RDBUF\fR 4
10989 .IX Item "PERLIO_F_RDBUF"
10990 .ie n .IP """PERLIO_F_TEMP""" 4
10991 .el .IP \f(CWPERLIO_F_TEMP\fR 4
10992 .IX Item "PERLIO_F_TEMP"
10993 .ie n .IP """PERLIO_F_TRUNCATE""" 4
10994 .el .IP \f(CWPERLIO_F_TRUNCATE\fR 4
10995 .IX Item "PERLIO_F_TRUNCATE"
10996 .ie n .IP """PERLIO_F_UNBUF""" 4
10997 .el .IP \f(CWPERLIO_F_UNBUF\fR 4
10998 .IX Item "PERLIO_F_UNBUF"
10999 .ie n .IP """PERLIO_F_UTF8""" 4
11000 .el .IP \f(CWPERLIO_F_UTF8\fR 4
11001 .IX Item "PERLIO_F_UTF8"
11002 .ie n .IP """PERLIO_F_WRBUF""" 4
11003 .el .IP \f(CWPERLIO_F_WRBUF\fR 4
11004 .IX Item "PERLIO_F_WRBUF"
11005 .PD
11006 Described in perliol.
11007 .ie n .IP """PerlIO_fast_gets*""" 4
11008 .el .IP \f(CWPerlIO_fast_gets*\fR 4
11009 .IX Item "PerlIO_fast_gets*"
11010 .PD 0
11011 .ie n .IP """PerlIO_fdopen*""" 4
11012 .el .IP \f(CWPerlIO_fdopen*\fR 4
11013 .IX Item "PerlIO_fdopen*"
11014 .ie n .IP """PerlIO_fileno*""" 4
11015 .el .IP \f(CWPerlIO_fileno*\fR 4
11016 .IX Item "PerlIO_fileno*"
11017 .ie n .IP """PerlIO_fill*""" 4
11018 .el .IP \f(CWPerlIO_fill*\fR 4
11019 .IX Item "PerlIO_fill*"
11020 .ie n .IP """PerlIO_findFILE*""" 4
11021 .el .IP \f(CWPerlIO_findFILE*\fR 4
11022 .IX Item "PerlIO_findFILE*"
11023 .ie n .IP """PerlIO_flush*""" 4
11024 .el .IP \f(CWPerlIO_flush*\fR 4
11025 .IX Item "PerlIO_flush*"
11026 .PD
11027 Described in perlapio.
11028 .ie n .IP """PERLIO_FUNCS_CAST""" 4
11029 .el .IP \f(CWPERLIO_FUNCS_CAST\fR 4
11030 .IX Xref "PERLIO_FUNCS_CAST"
11031 .IX Item "PERLIO_FUNCS_CAST"
11032 Cast the pointer \f(CW\*(C`func\*(C'\fR to be of type \f(CW\*(C`PerlIO_funcs\ *\*(C'\fR.
11033 .RS 4
11034 .Sp
11035 .Vb 1
11036 \& PerlIO_funcs * PERLIO_FUNCS_CAST(PerlIO * func)
11037 .Ve
11038 .RE
11039 .RS 4
11040 .RE
11041 .ie n .IP """PERLIO_FUNCS_DECL""" 4
11042 .el .IP \f(CWPERLIO_FUNCS_DECL\fR 4
11043 .IX Xref "PERLIO_FUNCS_DECL"
11044 .IX Item "PERLIO_FUNCS_DECL"
11045 Declare \f(CW\*(C`ftab\*(C'\fR to be a PerlIO function table, that is, of type
11046 \&\f(CW\*(C`PerlIO_funcs\*(C'\fR.
11047 .RS 4
11048 .Sp
11049 .Vb 1
11050 \& PERLIO_FUNCS_DECL(PerlIO * ftab)
11051 .Ve
11052 .RE
11053 .RS 4
11054 .RE
11055 .ie n .IP """PerlIO_get_base*""" 4
11056 .el .IP \f(CWPerlIO_get_base*\fR 4
11057 .IX Item "PerlIO_get_base*"
11058 .PD 0
11059 .ie n .IP """PerlIO_get_bufsiz*""" 4
11060 .el .IP \f(CWPerlIO_get_bufsiz*\fR 4
11061 .IX Item "PerlIO_get_bufsiz*"
11062 .ie n .IP """PerlIO_get_cnt*""" 4
11063 .el .IP \f(CWPerlIO_get_cnt*\fR 4
11064 .IX Item "PerlIO_get_cnt*"
11065 .ie n .IP """PerlIO_get_ptr*""" 4
11066 .el .IP \f(CWPerlIO_get_ptr*\fR 4
11067 .IX Item "PerlIO_get_ptr*"
11068 .ie n .IP """PerlIO_getc*""" 4
11069 .el .IP \f(CWPerlIO_getc*\fR 4
11070 .IX Item "PerlIO_getc*"
11071 .ie n .IP """PerlIO_getpos*""" 4
11072 .el .IP \f(CWPerlIO_getpos*\fR 4
11073 .IX Item "PerlIO_getpos*"
11074 .ie n .IP """PerlIO_has_base*""" 4
11075 .el .IP \f(CWPerlIO_has_base*\fR 4
11076 .IX Item "PerlIO_has_base*"
11077 .ie n .IP """PerlIO_has_cntptr*""" 4
11078 .el .IP \f(CWPerlIO_has_cntptr*\fR 4
11079 .IX Item "PerlIO_has_cntptr*"
11080 .ie n .IP """PerlIO_importFILE*""" 4
11081 .el .IP \f(CWPerlIO_importFILE*\fR 4
11082 .IX Item "PerlIO_importFILE*"
11083 .PD
11084 Described in perlapio.
11085 .ie n .IP """PERLIO_K_BUFFERED""" 4
11086 .el .IP \f(CWPERLIO_K_BUFFERED\fR 4
11087 .IX Item "PERLIO_K_BUFFERED"
11088 .PD 0
11089 .ie n .IP """PERLIO_K_CANCRLF""" 4
11090 .el .IP \f(CWPERLIO_K_CANCRLF\fR 4
11091 .IX Item "PERLIO_K_CANCRLF"
11092 .ie n .IP """PERLIO_K_FASTGETS""" 4
11093 .el .IP \f(CWPERLIO_K_FASTGETS\fR 4
11094 .IX Item "PERLIO_K_FASTGETS"
11095 .ie n .IP """PERLIO_K_MULTIARG""" 4
11096 .el .IP \f(CWPERLIO_K_MULTIARG\fR 4
11097 .IX Item "PERLIO_K_MULTIARG"
11098 .ie n .IP """PERLIO_K_RAW""" 4
11099 .el .IP \f(CWPERLIO_K_RAW\fR 4
11100 .IX Item "PERLIO_K_RAW"
11101 .PD
11102 Described in perliol.
11103 .ie n .IP """PERLIO_NOT_STDIO""" 4
11104 .el .IP \f(CWPERLIO_NOT_STDIO\fR 4
11105 .IX Item "PERLIO_NOT_STDIO"
11106 .PD 0
11107 .ie n .IP """PerlIO_open*""" 4
11108 .el .IP \f(CWPerlIO_open*\fR 4
11109 .IX Item "PerlIO_open*"
11110 .ie n .IP """PerlIO_printf*""" 4
11111 .el .IP \f(CWPerlIO_printf*\fR 4
11112 .IX Item "PerlIO_printf*"
11113 .ie n .IP """PerlIO_putc*""" 4
11114 .el .IP \f(CWPerlIO_putc*\fR 4
11115 .IX Item "PerlIO_putc*"
11116 .ie n .IP """PerlIO_puts*""" 4
11117 .el .IP \f(CWPerlIO_puts*\fR 4
11118 .IX Item "PerlIO_puts*"
11119 .ie n .IP """PerlIO_read*""" 4
11120 .el .IP \f(CWPerlIO_read*\fR 4
11121 .IX Item "PerlIO_read*"
11122 .ie n .IP """PerlIO_releaseFILE*""" 4
11123 .el .IP \f(CWPerlIO_releaseFILE*\fR 4
11124 .IX Item "PerlIO_releaseFILE*"
11125 .ie n .IP """PerlIO_reopen*""" 4
11126 .el .IP \f(CWPerlIO_reopen*\fR 4
11127 .IX Item "PerlIO_reopen*"
11128 .ie n .IP """PerlIO_rewind*""" 4
11129 .el .IP \f(CWPerlIO_rewind*\fR 4
11130 .IX Item "PerlIO_rewind*"
11131 .ie n .IP """PerlIO_seek*""" 4
11132 .el .IP \f(CWPerlIO_seek*\fR 4
11133 .IX Item "PerlIO_seek*"
11134 .ie n .IP """PerlIO_set_cnt*""" 4
11135 .el .IP \f(CWPerlIO_set_cnt*\fR 4
11136 .IX Item "PerlIO_set_cnt*"
11137 .ie n .IP """PerlIO_set_ptrcnt*""" 4
11138 .el .IP \f(CWPerlIO_set_ptrcnt*\fR 4
11139 .IX Item "PerlIO_set_ptrcnt*"
11140 .ie n .IP """PerlIO_setlinebuf*""" 4
11141 .el .IP \f(CWPerlIO_setlinebuf*\fR 4
11142 .IX Item "PerlIO_setlinebuf*"
11143 .ie n .IP """PerlIO_setpos*""" 4
11144 .el .IP \f(CWPerlIO_setpos*\fR 4
11145 .IX Item "PerlIO_setpos*"
11146 .ie n .IP """PerlIO_stderr*""" 4
11147 .el .IP \f(CWPerlIO_stderr*\fR 4
11148 .IX Item "PerlIO_stderr*"
11149 .ie n .IP """PerlIO_stdin*""" 4
11150 .el .IP \f(CWPerlIO_stdin*\fR 4
11151 .IX Item "PerlIO_stdin*"
11152 .ie n .IP """PerlIO_stdout*""" 4
11153 .el .IP \f(CWPerlIO_stdout*\fR 4
11154 .IX Item "PerlIO_stdout*"
11155 .ie n .IP """PerlIO_stdoutf*""" 4
11156 .el .IP \f(CWPerlIO_stdoutf*\fR 4
11157 .IX Item "PerlIO_stdoutf*"
11158 .ie n .IP """PerlIO_tell*""" 4
11159 .el .IP \f(CWPerlIO_tell*\fR 4
11160 .IX Item "PerlIO_tell*"
11161 .ie n .IP """PerlIO_ungetc*""" 4
11162 .el .IP \f(CWPerlIO_ungetc*\fR 4
11163 .IX Item "PerlIO_ungetc*"
11164 .ie n .IP """PerlIO_unread*""" 4
11165 .el .IP \f(CWPerlIO_unread*\fR 4
11166 .IX Item "PerlIO_unread*"
11167 .ie n .IP """PerlIO_vprintf*""" 4
11168 .el .IP \f(CWPerlIO_vprintf*\fR 4
11169 .IX Item "PerlIO_vprintf*"
11170 .ie n .IP """PerlIO_write*""" 4
11171 .el .IP \f(CWPerlIO_write*\fR 4
11172 .IX Item "PerlIO_write*"
11173 .PD
11174 Described in perlapio.
11175 .ie n .IP """PL_maxsysfd""" 4
11176 .el .IP \f(CWPL_maxsysfd\fR 4
11177 .IX Item "PL_maxsysfd"
11178 Described in perliol.
11179 .ie n .IP """repeatcpy""" 4
11180 .el .IP \f(CWrepeatcpy\fR 4
11181 .IX Xref "repeatcpy"
11182 .IX Item "repeatcpy"
11183 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
11184 into memory beginning at \f(CW\*(C`to\*(C'\fR, which must be big enough to accommodate them
11185 all.
11186 .RS 4
11187 .Sp
11188 .Vb 4
11189 \& void repeatcpy(char *to, const char *from, SSize_t len,
11190 \& IV count)
11191 \& void Perl_repeatcpy(char *to, const char *from, SSize_t len,
11192 \& IV count)
11193 .Ve
11194 .RE
11195 .RS 4
11196 .RE
11197 .ie n .IP """SvVSTRING""" 4
11198 .el .IP \f(CWSvVSTRING\fR 4
11199 .IX Xref "SvVSTRING"
11200 .IX Item "SvVSTRING"
11201 If the given SV has vstring magic, stores the length of it into the variable
11202 \&\f(CW\*(C`len\*(C'\fR, and returns the string pointer. If not, returns \f(CW\*(C`NULL\*(C'\fR.
11203 .Sp
11204 This is a wrapper around the \f(CW\*(C`sv_vstring_get\*(C'\fR function that conveniently
11205 takes the address of the \f(CW\*(C`len\*(C'\fR variable, in a form similar to the \f(CW\*(C`SvPV\*(C'\fR
11206 macro family.
11207 .RS 4
11208 .Sp
11209 .Vb 1
11210 \& const char * SvVSTRING(SV* sv, STRLEN len)
11211 .Ve
11212 .RE
11213 .RS 4
11214 .RE
11215 .ie n .IP """USE_STDIO""" 4
11216 .el .IP \f(CWUSE_STDIO\fR 4
11217 .IX Item "USE_STDIO"
11218 Described in perlapio.
11219 .RS 4
11220 .Sp
11221 .Vb 1
11222 \& #ifdef USE_STDIO
11223 .Ve
11224 .RE
11225 .RS 4
11226 .RE
11227 .SH Integer
11228 .IX Header "Integer"
11229 .ie n .IP """CASTI32""" 4
11230 .el .IP \f(CWCASTI32\fR 4
11231 .IX Xref "CASTI32"
11232 .IX Item "CASTI32"
11233 This symbol is defined if the C compiler can cast negative
11234 or large floating point numbers to 32\-bit ints.
11235 .ie n .IP """HAS_INT64_T""" 4
11236 .el .IP \f(CWHAS_INT64_T\fR 4
11237 .IX Xref "HAS_INT64_T"
11238 .IX Item "HAS_INT64_T"
11239 This symbol will defined if the C compiler supports \f(CW\*(C`int64_t\*(C'\fR.
11240 Usually the \fIinttypes.h\fR needs to be included, but sometimes
11241 \&\fIsys/types.h\fR is enough.
11242 .ie n .IP """HAS_LONG_LONG""" 4
11243 .el .IP \f(CWHAS_LONG_LONG\fR 4
11244 .IX Xref "HAS_LONG_LONG"
11245 .IX Item "HAS_LONG_LONG"
11246 This symbol will be defined if the C compiler supports long long.
11247 .ie n .IP """HAS_QUAD""" 4
11248 .el .IP \f(CWHAS_QUAD\fR 4
11249 .IX Xref "HAS_QUAD"
11250 .IX Item "HAS_QUAD"
11251 This symbol, if defined, tells that there\*(Aqs a 64\-bit integer type,
11252 \&\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
11253 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,
11254 or \f(CW\*(C`QUAD_IS_\|_\|_INT64\*(C'\fR.
11255 .ie n .IP """INTMAX_C""" 4
11256 .el .IP \f(CWINTMAX_C\fR 4
11257 .IX Xref "INTMAX_C"
11258 .IX Item "INTMAX_C"
11259 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11260 widest integer type on the machine. For example, if the machine has \f(CW\*(C`long
11261 long\*(C'\fRs, \f(CWINTMAX_C(\-1)\fR would yield
11262 .Sp
11263 .Vb 1
11264 \& \-1LL
11265 .Ve
11266 .Sp
11267 See also, for example, \f(CW"INT32_C"\fR.
11268 .Sp
11269 Use "IV" to declare variables of the maximum usable size on this platform.
11270 .RS 4
11271 .Sp
11272 .Vb 1
11273 \& INTMAX_C(number)
11274 .Ve
11275 .RE
11276 .RS 4
11277 .RE
11278 .ie n .IP """INTSIZE""" 4
11279 .el .IP \f(CWINTSIZE\fR 4
11280 .IX Xref "INTSIZE"
11281 .IX Item "INTSIZE"
11282 This symbol contains the value of \f(CWsizeof(int)\fR so that the C
11283 preprocessor can make decisions based on it.
11284 .ie n .IP """INT16_C""" 4
11285 .el .IP \f(CWINT16_C\fR 4
11286 .IX Item "INT16_C"
11287 .PD 0
11288 .ie n .IP """INT32_C""" 4
11289 .el .IP \f(CWINT32_C\fR 4
11290 .IX Item "INT32_C"
11291 .ie n .IP """INT64_C""" 4
11292 .el .IP \f(CWINT64_C\fR 4
11293 .IX Xref "INT16_C INT32_C INT64_C"
11294 .IX Item "INT64_C"
11295 .PD
11296 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11297 corresponding integer type on the machine.
11298 .Sp
11299 If the machine does not have a 64\-bit type, \f(CW\*(C`INT64_C\*(C'\fR is undefined.
11300 Use \f(CW"INTMAX_C"\fR to get the largest type available on the platform.
11301 .RS 4
11302 .Sp
11303 .Vb 3
11304 \& I16 INT16_C(number)
11305 \& I32 INT32_C(number)
11306 \& I64 INT64_C(number)
11307 .Ve
11308 .RE
11309 .RS 4
11310 .RE
11311 .ie n .IP """IV""" 4
11312 .el .IP \f(CWIV\fR 4
11313 .IX Item "IV"
11314 .PD 0
11315 .ie n .IP """I8""" 4
11316 .el .IP \f(CWI8\fR 4
11317 .IX Item "I8"
11318 .ie n .IP """I16""" 4
11319 .el .IP \f(CWI16\fR 4
11320 .IX Item "I16"
11321 .ie n .IP """I32""" 4
11322 .el .IP \f(CWI32\fR 4
11323 .IX Item "I32"
11324 .ie n .IP """I64""" 4
11325 .el .IP \f(CWI64\fR 4
11326 .IX Item "I64"
11327 .PD
11328 Described in perlguts.
11329 .ie n .IP """IV_MAX""" 4
11330 .el .IP \f(CWIV_MAX\fR 4
11331 .IX Xref "IV_MAX"
11332 .IX Item "IV_MAX"
11333 The largest signed integer that fits in an IV on this platform.
11334 .RS 4
11335 .Sp
11336 .Vb 1
11337 \& IV IV_MAX
11338 .Ve
11339 .RE
11340 .RS 4
11341 .RE
11342 .ie n .IP """IV_MIN""" 4
11343 .el .IP \f(CWIV_MIN\fR 4
11344 .IX Xref "IV_MIN"
11345 .IX Item "IV_MIN"
11346 The negative signed integer furthest away from 0 that fits in an IV on this
11347 platform.
11348 .Sp
11349 It is easy to get undefined C behavior with this value. The macros (currently
11350 only available for internal use) "\f(CW\*(C`NEGATE_2UV\*(C'\fR" in perlintern,
11351 "\f(CW\*(C`ABS_IV_MIN\*(C'\fR" in perlintern, and "\f(CW\*(C`NEGATE_2IV\*(C'\fR" in perlintern avoid
11352 undefined behavior when finding the opposite signed equivalent value.
11353 .RS 4
11354 .Sp
11355 .Vb 1
11356 \& IV IV_MIN
11357 .Ve
11358 .RE
11359 .RS 4
11360 .RE
11361 .ie n .IP """IVSIZE""" 4
11362 .el .IP \f(CWIVSIZE\fR 4
11363 .IX Xref "IVSIZE"
11364 .IX Item "IVSIZE"
11365 This symbol contains the \f(CWsizeof(IV)\fR.
11366 .ie n .IP """IVTYPE""" 4
11367 .el .IP \f(CWIVTYPE\fR 4
11368 .IX Xref "IVTYPE"
11369 .IX Item "IVTYPE"
11370 This symbol defines the C type used for Perl\*(Aqs IV.
11371 .ie n .IP """I8*""" 4
11372 .el .IP \f(CWI8*\fR 4
11373 .IX Item "I8*"
11374 Described in perlguts.
11375 .ie n .IP """I8SIZE""" 4
11376 .el .IP \f(CWI8SIZE\fR 4
11377 .IX Xref "I8SIZE"
11378 .IX Item "I8SIZE"
11379 This symbol contains the \f(CWsizeof(I8)\fR.
11380 .ie n .IP """I8TYPE""" 4
11381 .el .IP \f(CWI8TYPE\fR 4
11382 .IX Xref "I8TYPE"
11383 .IX Item "I8TYPE"
11384 This symbol defines the C type used for Perl\*(Aqs I8.
11385 .ie n .IP """I16*""" 4
11386 .el .IP \f(CWI16*\fR 4
11387 .IX Item "I16*"
11388 Described in perlguts.
11389 .ie n .IP """I16SIZE""" 4
11390 .el .IP \f(CWI16SIZE\fR 4
11391 .IX Xref "I16SIZE"
11392 .IX Item "I16SIZE"
11393 This symbol contains the \f(CWsizeof(I16)\fR.
11394 .ie n .IP """I16TYPE""" 4
11395 .el .IP \f(CWI16TYPE\fR 4
11396 .IX Xref "I16TYPE"
11397 .IX Item "I16TYPE"
11398 This symbol defines the C type used for Perl\*(Aqs I16.
11399 .ie n .IP """I32*""" 4
11400 .el .IP \f(CWI32*\fR 4
11401 .IX Item "I32*"
11402 Described in perlguts.
11403 .ie n .IP """I32df""" 4
11404 .el .IP \f(CWI32df\fR 4
11405 .IX Xref "I32df"
11406 .IX Item "I32df"
11407 This symbol defines the format string used for printing a Perl I32
11408 as a signed decimal integer.
11409 .ie n .IP """I32SIZE""" 4
11410 .el .IP \f(CWI32SIZE\fR 4
11411 .IX Xref "I32SIZE"
11412 .IX Item "I32SIZE"
11413 This symbol contains the \f(CWsizeof(I32)\fR.
11414 .ie n .IP """I32TYPE""" 4
11415 .el .IP \f(CWI32TYPE\fR 4
11416 .IX Xref "I32TYPE"
11417 .IX Item "I32TYPE"
11418 This symbol defines the C type used for Perl\*(Aqs I32.
11419 .ie n .IP """I64*""" 4
11420 .el .IP \f(CWI64*\fR 4
11421 .IX Item "I64*"
11422 Described in perlguts.
11423 .ie n .IP """I64SIZE""" 4
11424 .el .IP \f(CWI64SIZE\fR 4
11425 .IX Xref "I64SIZE"
11426 .IX Item "I64SIZE"
11427 This symbol contains the \f(CWsizeof(I64)\fR.
11428 .ie n .IP """I64TYPE""" 4
11429 .el .IP \f(CWI64TYPE\fR 4
11430 .IX Xref "I64TYPE"
11431 .IX Item "I64TYPE"
11432 This symbol defines the C type used for Perl\*(Aqs I64.
11433 .ie n .IP """line_t""" 4
11434 .el .IP \f(CWline_t\fR 4
11435 .IX Xref "line_t"
11436 .IX Item "line_t"
11437 The typedef to use to declare variables that are to hold line numbers.
11438 .ie n .IP """LONGLONGSIZE""" 4
11439 .el .IP \f(CWLONGLONGSIZE\fR 4
11440 .IX Xref "LONGLONGSIZE"
11441 .IX Item "LONGLONGSIZE"
11442 This symbol contains the size of a long long, so that the
11443 C preprocessor can make decisions based on it. It is only
11444 defined if the system supports long long.
11445 .ie n .IP """LONGSIZE""" 4
11446 .el .IP \f(CWLONGSIZE\fR 4
11447 .IX Xref "LONGSIZE"
11448 .IX Item "LONGSIZE"
11449 This symbol contains the value of \f(CWsizeof(long)\fR so that the C
11450 preprocessor can make decisions based on it.
11451 .ie n .IP """memzero""" 4
11452 .el .IP \f(CWmemzero\fR 4
11453 .IX Xref "memzero"
11454 .IX Item "memzero"
11455 Set the \f(CW\*(C`l\*(C'\fR bytes starting at \f(CW*d\fR to all zeroes.
11456 .RS 4
11457 .Sp
11458 .Vb 1
11459 \& void memzero(void * d, Size_t l)
11460 .Ve
11461 .RE
11462 .RS 4
11463 .RE
11464 .ie n .IP """PERL_INT_FAST8_T""" 4
11465 .el .IP \f(CWPERL_INT_FAST8_T\fR 4
11466 .IX Item "PERL_INT_FAST8_T"
11467 .PD 0
11468 .ie n .IP """PERL_INT_FAST16_T""" 4
11469 .el .IP \f(CWPERL_INT_FAST16_T\fR 4
11470 .IX Item "PERL_INT_FAST16_T"
11471 .ie n .IP """PERL_UINT_FAST8_T""" 4
11472 .el .IP \f(CWPERL_UINT_FAST8_T\fR 4
11473 .IX Item "PERL_UINT_FAST8_T"
11474 .ie n .IP """PERL_UINT_FAST16_T""" 4
11475 .el .IP \f(CWPERL_UINT_FAST16_T\fR 4
11476 .IX Xref "PERL_INT_FAST8_T PERL_INT_FAST16_T PERL_UINT_FAST8_T PERL_UINT_FAST16_T"
11477 .IX Item "PERL_UINT_FAST16_T"
11478 .PD
11479 These are equivalent to the correspondingly\-named C99 typedefs on platforms
11480 that have those; they evaluate to \f(CW\*(C`int\*(C'\fR and \f(CW\*(C`unsigned int\*(C'\fR on platforms that
11481 don\*(Aqt, so that you can portably take advantage of this C99 feature.
11482 .ie n .IP """PERL_INT_MAX""" 4
11483 .el .IP \f(CWPERL_INT_MAX\fR 4
11484 .IX Item "PERL_INT_MAX"
11485 .PD 0
11486 .ie n .IP """PERL_INT_MIN""" 4
11487 .el .IP \f(CWPERL_INT_MIN\fR 4
11488 .IX Item "PERL_INT_MIN"
11489 .ie n .IP """PERL_LONG_MAX""" 4
11490 .el .IP \f(CWPERL_LONG_MAX\fR 4
11491 .IX Item "PERL_LONG_MAX"
11492 .ie n .IP """PERL_LONG_MIN""" 4
11493 .el .IP \f(CWPERL_LONG_MIN\fR 4
11494 .IX Item "PERL_LONG_MIN"
11495 .ie n .IP """PERL_QUAD_MAX""" 4
11496 .el .IP \f(CWPERL_QUAD_MAX\fR 4
11497 .IX Item "PERL_QUAD_MAX"
11498 .ie n .IP """PERL_QUAD_MIN""" 4
11499 .el .IP \f(CWPERL_QUAD_MIN\fR 4
11500 .IX Item "PERL_QUAD_MIN"
11501 .ie n .IP """PERL_SHORT_MAX""" 4
11502 .el .IP \f(CWPERL_SHORT_MAX\fR 4
11503 .IX Item "PERL_SHORT_MAX"
11504 .ie n .IP """PERL_SHORT_MIN""" 4
11505 .el .IP \f(CWPERL_SHORT_MIN\fR 4
11506 .IX Item "PERL_SHORT_MIN"
11507 .ie n .IP """PERL_UCHAR_MAX""" 4
11508 .el .IP \f(CWPERL_UCHAR_MAX\fR 4
11509 .IX Item "PERL_UCHAR_MAX"
11510 .ie n .IP """PERL_UCHAR_MIN""" 4
11511 .el .IP \f(CWPERL_UCHAR_MIN\fR 4
11512 .IX Item "PERL_UCHAR_MIN"
11513 .ie n .IP """PERL_UINT_MAX""" 4
11514 .el .IP \f(CWPERL_UINT_MAX\fR 4
11515 .IX Item "PERL_UINT_MAX"
11516 .ie n .IP """PERL_UINT_MIN""" 4
11517 .el .IP \f(CWPERL_UINT_MIN\fR 4
11518 .IX Item "PERL_UINT_MIN"
11519 .ie n .IP """PERL_ULONG_MAX""" 4
11520 .el .IP \f(CWPERL_ULONG_MAX\fR 4
11521 .IX Item "PERL_ULONG_MAX"
11522 .ie n .IP """PERL_ULONG_MIN""" 4
11523 .el .IP \f(CWPERL_ULONG_MIN\fR 4
11524 .IX Item "PERL_ULONG_MIN"
11525 .ie n .IP """PERL_UQUAD_MAX""" 4
11526 .el .IP \f(CWPERL_UQUAD_MAX\fR 4
11527 .IX Item "PERL_UQUAD_MAX"
11528 .ie n .IP """PERL_UQUAD_MIN""" 4
11529 .el .IP \f(CWPERL_UQUAD_MIN\fR 4
11530 .IX Item "PERL_UQUAD_MIN"
11531 .ie n .IP """PERL_USHORT_MAX""" 4
11532 .el .IP \f(CWPERL_USHORT_MAX\fR 4
11533 .IX Item "PERL_USHORT_MAX"
11534 .ie n .IP """PERL_USHORT_MIN""" 4
11535 .el .IP \f(CWPERL_USHORT_MIN\fR 4
11536 .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"
11537 .IX Item "PERL_USHORT_MIN"
11538 .PD
11539 These give the largest and smallest number representable in the current
11540 platform in variables of the corresponding types.
11541 .Sp
11542 For signed types, the smallest representable number is the most negative
11543 number, the one furthest away from zero.
11544 .Sp
11545 For C99 and later compilers, these correspond to things like \f(CW\*(C`INT_MAX\*(C'\fR, which
11546 are available to the C code. But these constants, furnished by Perl,
11547 allow code compiled on earlier compilers to portably have access to the same
11548 constants.
11549 .RS 4
11550 .Sp
11551 .Vb 10
11552 \& int PERL_INT_MAX
11553 \& int PERL_INT_MIN
11554 \& long PERL_LONG_MAX
11555 \& long PERL_LONG_MIN
11556 \& IV PERL_QUAD_MAX
11557 \& IV PERL_QUAD_MIN
11558 \& short PERL_SHORT_MAX
11559 \& short PERL_SHORT_MIN
11560 \& U8 PERL_UCHAR_MAX
11561 \& U8 PERL_UCHAR_MIN
11562 \& unsigned int PERL_UINT_MAX
11563 \& unsigned int PERL_UINT_MIN
11564 \& unsigned long PERL_ULONG_MAX
11565 \& unsigned long PERL_ULONG_MIN
11566 \& UV PERL_UQUAD_MAX
11567 \& UV PERL_UQUAD_MIN
11568 \& unsigned short PERL_USHORT_MAX
11569 \& unsigned short PERL_USHORT_MIN
11570 .Ve
11571 .RE
11572 .RS 4
11573 .RE
11574 .ie n .IP """PERL_UINT_FAST8_T*""" 4
11575 .el .IP \f(CWPERL_UINT_FAST8_T*\fR 4
11576 .IX Item "PERL_UINT_FAST8_T*"
11577 .PD 0
11578 .ie n .IP """PERL_UINT_FAST16_T*""" 4
11579 .el .IP \f(CWPERL_UINT_FAST16_T*\fR 4
11580 .IX Item "PERL_UINT_FAST16_T*"
11581 .PD
11582 Described under \f(CW"PERL_INT_FAST8_T"\fR
11583 .ie n .IP """SHORTSIZE""" 4
11584 .el .IP \f(CWSHORTSIZE\fR 4
11585 .IX Xref "SHORTSIZE"
11586 .IX Item "SHORTSIZE"
11587 This symbol contains the value of \f(CWsizeof(short)\fR so that the C
11588 preprocessor can make decisions based on it.
11589 .ie n .IP """UINTMAX_C""" 4
11590 .el .IP \f(CWUINTMAX_C\fR 4
11591 .IX Xref "UINTMAX_C"
11592 .IX Item "UINTMAX_C"
11593 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11594 widest unsigned integer type on the machine. For example, if the machine has
11595 \&\f(CW\*(C`long\*(C'\fRs, \f(CWUINTMAX_C(1)\fR would yield
11596 .Sp
11597 .Vb 1
11598 \& 1UL
11599 .Ve
11600 .Sp
11601 See also, for example, \f(CW"UINT32_C"\fR.
11602 .Sp
11603 Use "UV" to declare variables of the maximum usable size on this platform.
11604 .RS 4
11605 .Sp
11606 .Vb 1
11607 \& UINTMAX_C(number)
11608 .Ve
11609 .RE
11610 .RS 4
11611 .RE
11612 .ie n .IP """UINT16_C""" 4
11613 .el .IP \f(CWUINT16_C\fR 4
11614 .IX Item "UINT16_C"
11615 .PD 0
11616 .ie n .IP """UINT32_C""" 4
11617 .el .IP \f(CWUINT32_C\fR 4
11618 .IX Item "UINT32_C"
11619 .ie n .IP """UINT64_C""" 4
11620 .el .IP \f(CWUINT64_C\fR 4
11621 .IX Xref "UINT16_C UINT32_C UINT64_C"
11622 .IX Item "UINT64_C"
11623 .PD
11624 Returns a token the C compiler recognizes for the constant \f(CW\*(C`number\*(C'\fR of the
11625 corresponding unsigned integer type on the machine.
11626 .Sp
11627 If the machine does not have a 64\-bit type, \f(CW\*(C`UINT64_C\*(C'\fR is undefined.
11628 Use \f(CW"UINTMAX_C"\fR to get the largest type available on the platform.
11629 .RS 4
11630 .Sp
11631 .Vb 3
11632 \& U16 UINT16_C(number)
11633 \& U32 UINT32_C(number)
11634 \& U64 UINT64_C(number)
11635 .Ve
11636 .RE
11637 .RS 4
11638 .RE
11639 .ie n .IP """UV""" 4
11640 .el .IP \f(CWUV\fR 4
11641 .IX Item "UV"
11642 .PD 0
11643 .ie n .IP """U8""" 4
11644 .el .IP \f(CWU8\fR 4
11645 .IX Item "U8"
11646 .ie n .IP """U16""" 4
11647 .el .IP \f(CWU16\fR 4
11648 .IX Item "U16"
11649 .ie n .IP """U32""" 4
11650 .el .IP \f(CWU32\fR 4
11651 .IX Item "U32"
11652 .ie n .IP """U64""" 4
11653 .el .IP \f(CWU64\fR 4
11654 .IX Item "U64"
11655 .PD
11656 Described in perlguts.
11657 .ie n .IP """UV_MAX""" 4
11658 .el .IP \f(CWUV_MAX\fR 4
11659 .IX Xref "UV_MAX"
11660 .IX Item "UV_MAX"
11661 The largest unsigned integer that fits in a UV on this platform.
11662 .RS 4
11663 .Sp
11664 .Vb 1
11665 \& UV UV_MAX
11666 .Ve
11667 .RE
11668 .RS 4
11669 .RE
11670 .ie n .IP """UV_MIN""" 4
11671 .el .IP \f(CWUV_MIN\fR 4
11672 .IX Xref "UV_MIN"
11673 .IX Item "UV_MIN"
11674 The smallest unsigned integer that fits in a UV on this platform. It should
11675 equal zero.
11676 .RS 4
11677 .Sp
11678 .Vb 1
11679 \& UV UV_MIN
11680 .Ve
11681 .RE
11682 .RS 4
11683 .RE
11684 .ie n .IP """UVSIZE""" 4
11685 .el .IP \f(CWUVSIZE\fR 4
11686 .IX Xref "UVSIZE"
11687 .IX Item "UVSIZE"
11688 This symbol contains the \f(CWsizeof(UV)\fR.
11689 .ie n .IP """UVTYPE""" 4
11690 .el .IP \f(CWUVTYPE\fR 4
11691 .IX Xref "UVTYPE"
11692 .IX Item "UVTYPE"
11693 This symbol defines the C type used for Perl\*(Aqs UV.
11694 .ie n .IP """U8*""" 4
11695 .el .IP \f(CWU8*\fR 4
11696 .IX Item "U8*"
11697 Described in perlguts.
11698 .ie n .IP """U8SIZE""" 4
11699 .el .IP \f(CWU8SIZE\fR 4
11700 .IX Xref "U8SIZE"
11701 .IX Item "U8SIZE"
11702 This symbol contains the \f(CWsizeof(U8)\fR.
11703 .ie n .IP """U8TYPE""" 4
11704 .el .IP \f(CWU8TYPE\fR 4
11705 .IX Xref "U8TYPE"
11706 .IX Item "U8TYPE"
11707 This symbol defines the C type used for Perl\*(Aqs U8.
11708 .ie n .IP """U16*""" 4
11709 .el .IP \f(CWU16*\fR 4
11710 .IX Item "U16*"
11711 Described in perlguts.
11712 .ie n .IP """U16SIZE""" 4
11713 .el .IP \f(CWU16SIZE\fR 4
11714 .IX Xref "U16SIZE"
11715 .IX Item "U16SIZE"
11716 This symbol contains the \f(CWsizeof(U16)\fR.
11717 .ie n .IP """U16TYPE""" 4
11718 .el .IP \f(CWU16TYPE\fR 4
11719 .IX Xref "U16TYPE"
11720 .IX Item "U16TYPE"
11721 This symbol defines the C type used for Perl\*(Aqs U16.
11722 .ie n .IP """U32*""" 4
11723 .el .IP \f(CWU32*\fR 4
11724 .IX Item "U32*"
11725 Described in perlguts.
11726 .ie n .IP """U32of""" 4
11727 .el .IP \f(CWU32of\fR 4
11728 .IX Xref "U32of"
11729 .IX Item "U32of"
11730 This symbol defines the format string used for printing a Perl U32
11731 as an unsigned octal integer.
11732 .ie n .IP """U32SIZE""" 4
11733 .el .IP \f(CWU32SIZE\fR 4
11734 .IX Xref "U32SIZE"
11735 .IX Item "U32SIZE"
11736 This symbol contains the \f(CWsizeof(U32)\fR.
11737 .ie n .IP """U32TYPE""" 4
11738 .el .IP \f(CWU32TYPE\fR 4
11739 .IX Xref "U32TYPE"
11740 .IX Item "U32TYPE"
11741 This symbol defines the C type used for Perl\*(Aqs U32.
11742 .ie n .IP """U32uf""" 4
11743 .el .IP \f(CWU32uf\fR 4
11744 .IX Xref "U32uf"
11745 .IX Item "U32uf"
11746 This symbol defines the format string used for printing a Perl U32
11747 as an unsigned decimal integer.
11748 .ie n .IP """U32Xf""" 4
11749 .el .IP \f(CWU32Xf\fR 4
11750 .IX Xref "U32Xf"
11751 .IX Item "U32Xf"
11752 This symbol defines the format string used for printing a Perl U32
11753 as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR.
11754 .ie n .IP """U32xf""" 4
11755 .el .IP \f(CWU32xf\fR 4
11756 .IX Xref "U32xf"
11757 .IX Item "U32xf"
11758 This symbol defines the format string used for printing a Perl U32
11759 as an unsigned hexadecimal integer in lowercase abcdef.
11760 .ie n .IP """U64*""" 4
11761 .el .IP \f(CWU64*\fR 4
11762 .IX Item "U64*"
11763 Described in perlguts.
11764 .ie n .IP """U64SIZE""" 4
11765 .el .IP \f(CWU64SIZE\fR 4
11766 .IX Xref "U64SIZE"
11767 .IX Item "U64SIZE"
11768 This symbol contains the \f(CWsizeof(U64)\fR.
11769 .ie n .IP """U64TYPE""" 4
11770 .el .IP \f(CWU64TYPE\fR 4
11771 .IX Xref "U64TYPE"
11772 .IX Item "U64TYPE"
11773 This symbol defines the C type used for Perl\*(Aqs U64.
11774 .ie n .IP """WIDEST_UTYPE""" 4
11775 .el .IP \f(CWWIDEST_UTYPE\fR 4
11776 .IX Xref "WIDEST_UTYPE"
11777 .IX Item "WIDEST_UTYPE"
11778 Yields the widest unsigned integer type on the platform, currently either
11779 \&\f(CW\*(C`U32\*(C'\fR or \f(CW\*(C`U64\*(C'\fR. This can be used in declarations such as
11780 .Sp
11781 .Vb 1
11782 \& WIDEST_UTYPE my_uv;
11783 .Ve
11784 .Sp
11785 or casts
11786 .Sp
11787 .Vb 1
11788 \& my_uv = (WIDEST_UTYPE) val;
11789 .Ve
11790 .SH "I/O Formats"
11791 .IX Header "I/O Formats"
11792 These are used for formatting the corresponding type For example,
11793 instead of saying
11794 .PP
11795 .Vb 1
11796 \& Perl_newSVpvf(pTHX_ "Create an SV with a %d in it\en", iv);
11797 .Ve
11798 .PP
11799 use
11800 .PP
11801 .Vb 1
11802 \& Perl_newSVpvf(pTHX_ "Create an SV with a " IVdf " in it\en", iv);
11803 .Ve
11804 .PP
11805 This keeps you from having to know if, say an IV, needs to be
11806 printed as \f(CW%d\fR, \f(CW%ld\fR, or something else.
11807 .ie n .IP """HvNAMEf""" 4
11808 .el .IP \f(CWHvNAMEf\fR 4
11809 .IX Item "HvNAMEf"
11810 .PD 0
11811 .ie n .IP """HvNAMEf_QUOTEDPREFIX""" 4
11812 .el .IP \f(CWHvNAMEf_QUOTEDPREFIX\fR 4
11813 .IX Item "HvNAMEf_QUOTEDPREFIX"
11814 .PD
11815 Described in perlguts.
11816 .ie n .IP """IVdf""" 4
11817 .el .IP \f(CWIVdf\fR 4
11818 .IX Xref "IVdf"
11819 .IX Item "IVdf"
11820 This symbol defines the format string used for printing a Perl IV
11821 as a signed decimal integer.
11822 .ie n .IP """NVef""" 4
11823 .el .IP \f(CWNVef\fR 4
11824 .IX Xref "NVef"
11825 .IX Item "NVef"
11826 This symbol defines the format string used for printing a Perl NV
11827 using \f(CW%e\fR\-ish floating point format.
11828 .ie n .IP """NVff""" 4
11829 .el .IP \f(CWNVff\fR 4
11830 .IX Xref "NVff"
11831 .IX Item "NVff"
11832 This symbol defines the format string used for printing a Perl NV
11833 using \f(CW%f\fR\-ish floating point format.
11834 .ie n .IP """NVgf""" 4
11835 .el .IP \f(CWNVgf\fR 4
11836 .IX Xref "NVgf"
11837 .IX Item "NVgf"
11838 This symbol defines the format string used for printing a Perl NV
11839 using \f(CW%g\fR\-ish floating point format.
11840 .ie n .IP """PERL_PRIeldbl""" 4
11841 .el .IP \f(CWPERL_PRIeldbl\fR 4
11842 .IX Xref "PERL_PRIeldbl"
11843 .IX Item "PERL_PRIeldbl"
11844 This symbol, if defined, contains the string used by stdio to
11845 format long doubles (format \*(Aqe\*(Aq) for output.
11846 .ie n .IP """PERL_PRIfldbl""" 4
11847 .el .IP \f(CWPERL_PRIfldbl\fR 4
11848 .IX Xref "PERL_PRIfldbl"
11849 .IX Item "PERL_PRIfldbl"
11850 This symbol, if defined, contains the string used by stdio to
11851 format long doubles (format \*(Aqf\*(Aq) for output.
11852 .ie n .IP """PERL_PRIgldbl""" 4
11853 .el .IP \f(CWPERL_PRIgldbl\fR 4
11854 .IX Xref "PERL_PRIgldbl"
11855 .IX Item "PERL_PRIgldbl"
11856 This symbol, if defined, contains the string used by stdio to
11857 format long doubles (format \*(Aqg\*(Aq) for output.
11858 .ie n .IP """PERL_SCNfldbl""" 4
11859 .el .IP \f(CWPERL_SCNfldbl\fR 4
11860 .IX Xref "PERL_SCNfldbl"
11861 .IX Item "PERL_SCNfldbl"
11862 This symbol, if defined, contains the string used by stdio to
11863 format long doubles (format \*(Aqf\*(Aq) for input.
11864 .ie n .IP """PRINTF_FORMAT_NULL_OK""" 4
11865 .el .IP \f(CWPRINTF_FORMAT_NULL_OK\fR 4
11866 .IX Xref "PRINTF_FORMAT_NULL_OK"
11867 .IX Item "PRINTF_FORMAT_NULL_OK"
11868 Allows \f(CW\*(C`_\|_printf_\|_\*(C'\fR format to be null when checking printf\-style
11869 .ie n .IP """SVf""" 4
11870 .el .IP \f(CWSVf\fR 4
11871 .IX Item "SVf"
11872 .PD 0
11873 .ie n .IP """SVf_QUOTEDPREFIX""" 4
11874 .el .IP \f(CWSVf_QUOTEDPREFIX\fR 4
11875 .IX Item "SVf_QUOTEDPREFIX"
11876 .ie n .IP """SVfARG""" 4
11877 .el .IP \f(CWSVfARG\fR 4
11878 .IX Item "SVfARG"
11879 .ie n .IP """UTF8f""" 4
11880 .el .IP \f(CWUTF8f\fR 4
11881 .IX Item "UTF8f"
11882 .ie n .IP """UTF8f_QUOTEDPREFIX""" 4
11883 .el .IP \f(CWUTF8f_QUOTEDPREFIX\fR 4
11884 .IX Item "UTF8f_QUOTEDPREFIX"
11885 .ie n .IP """UTF8fARG""" 4
11886 .el .IP \f(CWUTF8fARG\fR 4
11887 .IX Item "UTF8fARG"
11888 .PD
11889 Described in perlguts.
11890 .RS 4
11891 .Sp
11892 .Vb 2
11893 \& SVfARG (SV *sv)
11894 \& UTF8fARG(bool is_utf8, Size_t byte_len, char *str)
11895 .Ve
11896 .RE
11897 .RS 4
11898 .RE
11899 .ie n .IP """UVf""" 4
11900 .el .IP \f(CWUVf\fR 4
11901 .IX Xref "UVf"
11902 .IX Item "UVf"
11903 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`UVf\*(C'\fR
11904 from a future release of Perl. Do not use it for
11905 new code; remove it from existing code.
11906 .Sp
11907 Obsolete form of \f(CW\*(C`UVuf\*(C'\fR, which you should convert to instead use
11908 .RS 4
11909 .Sp
11910 .Vb 1
11911 \& const char * UVf
11912 .Ve
11913 .RE
11914 .RS 4
11915 .RE
11916 .ie n .IP """UVof""" 4
11917 .el .IP \f(CWUVof\fR 4
11918 .IX Xref "UVof"
11919 .IX Item "UVof"
11920 This symbol defines the format string used for printing a Perl UV
11921 as an unsigned octal integer.
11922 .ie n .IP """UVuf""" 4
11923 .el .IP \f(CWUVuf\fR 4
11924 .IX Xref "UVuf"
11925 .IX Item "UVuf"
11926 This symbol defines the format string used for printing a Perl UV
11927 as an unsigned decimal integer.
11928 .ie n .IP """UVXf""" 4
11929 .el .IP \f(CWUVXf\fR 4
11930 .IX Xref "UVXf"
11931 .IX Item "UVXf"
11932 This symbol defines the format string used for printing a Perl UV
11933 as an unsigned hexadecimal integer in uppercase \f(CW\*(C`ABCDEF\*(C'\fR.
11934 .ie n .IP """UVxf""" 4
11935 .el .IP \f(CWUVxf\fR 4
11936 .IX Xref "UVxf"
11937 .IX Item "UVxf"
11938 This symbol defines the format string used for printing a Perl UV
11939 as an unsigned hexadecimal integer in lowercase abcdef.
11940 .SH "Lexer interface"
11941 .IX Xref "LEX_KEEP_PREVIOUS LEX_STUFF_UTF8 PARSE_OPTIONAL"
11942 .IX Header "Lexer interface"
11943 This is the lower layer of the Perl parser, managing characters and tokens.
11944 .ie n .IP """BHK""" 4
11945 .el .IP \f(CWBHK\fR 4
11946 .IX Item "BHK"
11947 Described in perlguts.
11948 .ie n .IP """lex_bufutf8""" 4
11949 .el .IP \f(CWlex_bufutf8\fR 4
11950 .IX Xref "lex_bufutf8"
11951 .IX Item "lex_bufutf8"
11952 NOTE: \f(CW\*(C`lex_bufutf8\*(C'\fR is \fBexperimental\fR and may change or be
11953 removed without notice.
11954 .Sp
11955 Indicates whether the octets in the lexer buffer
11956 ("PL_parser\->linestr") should be interpreted as the UTF\-8 encoding
11957 of Unicode characters. If not, they should be interpreted as Latin\-1
11958 characters. This is analogous to the \f(CW\*(C`SvUTF8\*(C'\fR flag for scalars.
11959 .Sp
11960 In UTF\-8 mode, it is not guaranteed that the lexer buffer actually
11961 contains valid UTF\-8. Lexing code must be robust in the face of invalid
11962 encoding.
11963 .Sp
11964 The actual \f(CW\*(C`SvUTF8\*(C'\fR flag of the "PL_parser\->linestr" scalar
11965 is significant, but not the whole story regarding the input character
11966 encoding. Normally, when a file is being read, the scalar contains octets
11967 and its \f(CW\*(C`SvUTF8\*(C'\fR flag is off, but the octets should be interpreted as
11968 UTF\-8 if the \f(CW\*(C`use utf8\*(C'\fR pragma is in effect. During a string eval,
11969 however, the scalar may have the \f(CW\*(C`SvUTF8\*(C'\fR flag on, and in this case its
11970 octets should be interpreted as UTF\-8 unless the \f(CW\*(C`use bytes\*(C'\fR pragma
11971 is in effect. This logic may change in the future; use this function
11972 instead of implementing the logic yourself.
11973 .RS 4
11974 .Sp
11975 .Vb 2
11976 \& bool lex_bufutf8()
11977 \& bool Perl_lex_bufutf8(pTHX)
11978 .Ve
11979 .RE
11980 .RS 4
11981 .RE
11982 .ie n .IP """lex_discard_to""" 4
11983 .el .IP \f(CWlex_discard_to\fR 4
11984 .IX Xref "lex_discard_to"
11985 .IX Item "lex_discard_to"
11986 NOTE: \f(CW\*(C`lex_discard_to\*(C'\fR is \fBexperimental\fR and may change or be
11987 removed without notice.
11988 .Sp
11989 Discards the first part of the "PL_parser\->linestr" buffer,
11990 up to \f(CW\*(C`ptr\*(C'\fR. The remaining content of the buffer will be moved, and
11991 all pointers into the buffer updated appropriately. \f(CW\*(C`ptr\*(C'\fR must not
11992 be later in the buffer than the position of "PL_parser\->bufptr":
11993 it is not permitted to discard text that has yet to be lexed.
11994 .Sp
11995 Normally it is not necessarily to do this directly, because it suffices to
11996 use the implicit discarding behaviour of "lex_next_chunk" and things
11997 based on it. However, if a token stretches across multiple lines,
11998 and the lexing code has kept multiple lines of text in the buffer for
11999 that purpose, then after completion of the token it would be wise to
12000 explicitly discard the now\-unneeded earlier lines, to avoid future
12001 multi\-line tokens growing the buffer without bound.
12002 .RS 4
12003 .Sp
12004 .Vb 2
12005 \& void lex_discard_to( char *ptr)
12006 \& void Perl_lex_discard_to(pTHX_ char *ptr)
12007 .Ve
12008 .RE
12009 .RS 4
12010 .RE
12011 .ie n .IP """lex_grow_linestr""" 4
12012 .el .IP \f(CWlex_grow_linestr\fR 4
12013 .IX Xref "lex_grow_linestr"
12014 .IX Item "lex_grow_linestr"
12015 NOTE: \f(CW\*(C`lex_grow_linestr\*(C'\fR is \fBexperimental\fR and may change or be
12016 removed without notice.
12017 .Sp
12018 Reallocates the lexer buffer ("PL_parser\->linestr") to accommodate
12019 at least \f(CW\*(C`len\*(C'\fR octets (including terminating \f(CW\*(C`NUL\*(C'\fR). Returns a
12020 pointer to the reallocated buffer. This is necessary before making
12021 any direct modification of the buffer that would increase its length.
12022 "lex_stuff_pvn" provides a more convenient way to insert text into
12023 the buffer.
12024 .Sp
12025 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;
12026 this function updates all of the lexer\*(Aqs variables that point directly
12027 into the buffer.
12028 .RS 4
12029 .Sp
12030 .Vb 2
12031 \& char * lex_grow_linestr( STRLEN len)
12032 \& char * Perl_lex_grow_linestr(pTHX_ STRLEN len)
12033 .Ve
12034 .RE
12035 .RS 4
12036 .RE
12037 .ie n .IP """lex_next_chunk""" 4
12038 .el .IP \f(CWlex_next_chunk\fR 4
12039 .IX Xref "lex_next_chunk"
12040 .IX Item "lex_next_chunk"
12041 NOTE: \f(CW\*(C`lex_next_chunk\*(C'\fR is \fBexperimental\fR and may change or be
12042 removed without notice.
12043 .Sp
12044 Reads in the next chunk of text to be lexed, appending it to
12045 "PL_parser\->linestr". This should be called when lexing code has
12046 looked to the end of the current chunk and wants to know more. It is
12047 usual, but not necessary, for lexing to have consumed the entirety of
12048 the current chunk at this time.
12049 .Sp
12050 If "PL_parser\->bufptr" is pointing to the very end of the current
12051 chunk (i.e., the current chunk has been entirely consumed), normally the
12052 current chunk will be discarded at the same time that the new chunk is
12053 read in. If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, the current chunk
12054 will not be discarded. If the current chunk has not been entirely
12055 consumed, then it will not be discarded regardless of the flag.
12056 .Sp
12057 Returns true if some new text was added to the buffer, or false if the
12058 buffer has reached the end of the input text.
12059 .RS 4
12060 .Sp
12061 .Vb 2
12062 \& bool lex_next_chunk( U32 flags)
12063 \& bool Perl_lex_next_chunk(pTHX_ U32 flags)
12064 .Ve
12065 .RE
12066 .RS 4
12067 .RE
12068 .ie n .IP """lex_peek_unichar""" 4
12069 .el .IP \f(CWlex_peek_unichar\fR 4
12070 .IX Xref "lex_peek_unichar"
12071 .IX Item "lex_peek_unichar"
12072 NOTE: \f(CW\*(C`lex_peek_unichar\*(C'\fR is \fBexperimental\fR and may change or be
12073 removed without notice.
12074 .Sp
12075 Looks ahead one (Unicode) character in the text currently being lexed.
12076 Returns the codepoint (unsigned integer value) of the next character,
12077 or \-1 if lexing has reached the end of the input text. To consume the
12078 peeked character, use "lex_read_unichar".
12079 .Sp
12080 If the next character is in (or extends into) the next chunk of input
12081 text, the next chunk will be read in. Normally the current chunk will be
12082 discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR
12083 bit set, then the current chunk will not be discarded.
12084 .Sp
12085 If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error
12086 is encountered, an exception is generated.
12087 .RS 4
12088 .Sp
12089 .Vb 2
12090 \& I32 lex_peek_unichar( U32 flags)
12091 \& I32 Perl_lex_peek_unichar(pTHX_ U32 flags)
12092 .Ve
12093 .RE
12094 .RS 4
12095 .RE
12096 .ie n .IP """lex_read_space""" 4
12097 .el .IP \f(CWlex_read_space\fR 4
12098 .IX Xref "lex_read_space"
12099 .IX Item "lex_read_space"
12100 NOTE: \f(CW\*(C`lex_read_space\*(C'\fR is \fBexperimental\fR and may change or be
12101 removed without notice.
12102 .Sp
12103 Reads optional spaces, in Perl style, in the text currently being
12104 lexed. The spaces may include ordinary whitespace characters and
12105 Perl\-style comments. \f(CW\*(C`#line\*(C'\fR directives are processed if encountered.
12106 "PL_parser\->bufptr" is moved past the spaces, so that it points
12107 at a non\-space character (or the end of the input text).
12108 .Sp
12109 If spaces extend into the next chunk of input text, the next chunk will
12110 be read in. Normally the current chunk will be discarded at the same
12111 time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR bit set, then the current
12112 chunk will not be discarded.
12113 .RS 4
12114 .Sp
12115 .Vb 2
12116 \& void lex_read_space( U32 flags)
12117 \& void Perl_lex_read_space(pTHX_ U32 flags)
12118 .Ve
12119 .RE
12120 .RS 4
12121 .RE
12122 .ie n .IP """lex_read_to""" 4
12123 .el .IP \f(CWlex_read_to\fR 4
12124 .IX Xref "lex_read_to"
12125 .IX Item "lex_read_to"
12126 NOTE: \f(CW\*(C`lex_read_to\*(C'\fR is \fBexperimental\fR and may change or be
12127 removed without notice.
12128 .Sp
12129 Consume text in the lexer buffer, from "PL_parser\->bufptr" up
12130 to \f(CW\*(C`ptr\*(C'\fR. This advances "PL_parser\->bufptr" to match \f(CW\*(C`ptr\*(C'\fR,
12131 performing the correct bookkeeping whenever a newline character is passed.
12132 This is the normal way to consume lexed text.
12133 .Sp
12134 Interpretation of the buffer\*(Aqs octets can be abstracted out by
12135 using the slightly higher\-level functions "lex_peek_unichar" and
12136 "lex_read_unichar".
12137 .RS 4
12138 .Sp
12139 .Vb 2
12140 \& void lex_read_to( char *ptr)
12141 \& void Perl_lex_read_to(pTHX_ char *ptr)
12142 .Ve
12143 .RE
12144 .RS 4
12145 .RE
12146 .ie n .IP """lex_read_unichar""" 4
12147 .el .IP \f(CWlex_read_unichar\fR 4
12148 .IX Xref "lex_read_unichar"
12149 .IX Item "lex_read_unichar"
12150 NOTE: \f(CW\*(C`lex_read_unichar\*(C'\fR is \fBexperimental\fR and may change or be
12151 removed without notice.
12152 .Sp
12153 Reads the next (Unicode) character in the text currently being lexed.
12154 Returns the codepoint (unsigned integer value) of the character read,
12155 and moves "PL_parser\->bufptr" past the character, or returns \-1
12156 if lexing has reached the end of the input text. To non\-destructively
12157 examine the next character, use "lex_peek_unichar" instead.
12158 .Sp
12159 If the next character is in (or extends into) the next chunk of input
12160 text, the next chunk will be read in. Normally the current chunk will be
12161 discarded at the same time, but if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`LEX_KEEP_PREVIOUS\*(C'\fR
12162 bit set, then the current chunk will not be discarded.
12163 .Sp
12164 If the input is being interpreted as UTF\-8 and a UTF\-8 encoding error
12165 is encountered, an exception is generated.
12166 .RS 4
12167 .Sp
12168 .Vb 2
12169 \& I32 lex_read_unichar( U32 flags)
12170 \& I32 Perl_lex_read_unichar(pTHX_ U32 flags)
12171 .Ve
12172 .RE
12173 .RS 4
12174 .RE
12175 .ie n .IP """lex_start""" 4
12176 .el .IP \f(CWlex_start\fR 4
12177 .IX Xref "lex_start"
12178 .IX Item "lex_start"
12179 NOTE: \f(CW\*(C`lex_start\*(C'\fR is \fBexperimental\fR and may change or be
12180 removed without notice.
12181 .Sp
12182 Creates and initialises a new lexer/parser state object, supplying
12183 a context in which to lex and parse from a new source of Perl code.
12184 A pointer to the new state object is placed in "PL_parser". An entry
12185 is made on the save stack so that upon unwinding, the new state object
12186 will be destroyed and the former value of "PL_parser" will be restored.
12187 Nothing else need be done to clean up the parsing context.
12188 .Sp
12189 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
12190 non\-null, provides a string (in SV form) containing code to be parsed.
12191 A copy of the string is made, so subsequent modification of \f(CW\*(C`line\*(C'\fR
12192 does not affect parsing. \f(CW\*(C`rsfp\*(C'\fR, if non\-null, provides an input stream
12193 from which code will be read to be parsed. If both are non\-null, the
12194 code in \f(CW\*(C`line\*(C'\fR comes first and must consist of complete lines of input,
12195 and \f(CW\*(C`rsfp\*(C'\fR supplies the remainder of the source.
12196 .Sp
12197 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use. Currently it is only
12198 used by perl internally, so extensions should always pass zero.
12199 .RS 4
12200 .Sp
12201 .Vb 2
12202 \& void lex_start( SV *line, PerlIO *rsfp, U32 flags)
12203 \& void Perl_lex_start(pTHX_ SV *line, PerlIO *rsfp, U32 flags)
12204 .Ve
12205 .RE
12206 .RS 4
12207 .RE
12208 .ie n .IP """lex_stuff_pv""" 4
12209 .el .IP \f(CWlex_stuff_pv\fR 4
12210 .IX Item "lex_stuff_pv"
12211 .PD 0
12212 .ie n .IP """lex_stuff_pvn""" 4
12213 .el .IP \f(CWlex_stuff_pvn\fR 4
12214 .IX Item "lex_stuff_pvn"
12215 .ie n .IP """lex_stuff_pvs""" 4
12216 .el .IP \f(CWlex_stuff_pvs\fR 4
12217 .IX Item "lex_stuff_pvs"
12218 .ie n .IP """lex_stuff_sv""" 4
12219 .el .IP \f(CWlex_stuff_sv\fR 4
12220 .IX Xref "lex_stuff_pv lex_stuff_pvn lex_stuff_pvs lex_stuff_sv"
12221 .IX Item "lex_stuff_sv"
12222 .PD
12223 NOTE: all these forms are \fBexperimental\fR and may change or be
12224 removed without notice.
12225 .Sp
12226 These each insert characters into the lexer buffer
12227 ("PL_parser\->linestr"),
12228 immediately after the current lexing point ("PL_parser\->bufptr"),
12229 reallocating the buffer if necessary. This means that lexing code that
12230 runs later will see the characters as if they had appeared in the input.
12231 It is not recommended to do this as part of normal parsing, and most
12232 uses of this facility run the risk of the inserted characters being
12233 interpreted in an unintended manner.
12234 .Sp
12235 In \f(CW\*(C`lex_stuff_pvs\*(C'\fR, the string to be inserted is a literal C string, enclosed
12236 in double quotes.
12237 .Sp
12238 In \f(CW\*(C`lex_stuff_pv\*(C'\fR and \f(CW\*(C`lex_stuff_pvn\*(C'\fR, the string to be inserted is
12239 represented by the octets starting at \f(CW\*(C`pv\*(C'\fR. In \f(CW\*(C`lex_stuff_pv\*(C'\fR, the first NUL
12240 octet terminates the string. In \f(CW\*(C`lex_stuff_pvn\*(C'\fR, \f(CW\*(C`len\*(C'\fR octets will be used,
12241 hence the string may contain embedded NUL characters.
12242 .Sp
12243 In all three cases, these octets are interpreted as either UTF\-8 or Latin\-1,
12244 according to whether or not the \f(CW\*(C`LEX_STUFF_UTF8\*(C'\fR flag is set in \f(CW\*(C`flags\*(C'\fR.
12245 .Sp
12246 In \f(CW\*(C`lex_stuff_sv\*(C'\fR, the string to be inserted is the string value of \f(CW\*(C`sv\*(C'\fR.
12247 \&\f(CW\*(C`flags\*(C'\fR must be 0. The string is interpreted as either UTF\-8 or Latin\-1,
12248 according to whether or not \f(CW\*(C`sv\*(C'\fR has its UTF\-8 flag set.
12249 .Sp
12250 In all three forms, the characters are recoded for the lexer buffer, according
12251 to how the buffer is currently being interpreted ("lex_bufutf8").
12252 .RS 4
12253 .Sp
12254 .Vb 9
12255 \& void lex_stuff_pv ( const char *pv, U32 flags)
12256 \& void Perl_lex_stuff_pv (pTHX_ const char *pv, U32 flags)
12257 \& void lex_stuff_pvn( const char *pv, STRLEN len,
12258 \& U32 flags)
12259 \& void Perl_lex_stuff_pvn(pTHX_ const char *pv, STRLEN len,
12260 \& U32 flags)
12261 \& void lex_stuff_pvs( "pv", U32 flags)
12262 \& void lex_stuff_sv ( SV *sv, U32 flags)
12263 \& void Perl_lex_stuff_sv (pTHX_ SV *sv, U32 flags)
12264 .Ve
12265 .RE
12266 .RS 4
12267 .RE
12268 .ie n .IP """lex_unstuff""" 4
12269 .el .IP \f(CWlex_unstuff\fR 4
12270 .IX Xref "lex_unstuff"
12271 .IX Item "lex_unstuff"
12272 NOTE: \f(CW\*(C`lex_unstuff\*(C'\fR is \fBexperimental\fR and may change or be
12273 removed without notice.
12274 .Sp
12275 Discards text about to be lexed, from "PL_parser\->bufptr" up to
12276 \&\f(CW\*(C`ptr\*(C'\fR. Text following \f(CW\*(C`ptr\*(C'\fR will be moved, and the buffer shortened.
12277 This hides the discarded text from any lexing code that runs later,
12278 as if the text had never appeared.
12279 .Sp
12280 This is not the normal way to consume lexed text. For that, use
12281 "lex_read_to".
12282 .RS 4
12283 .Sp
12284 .Vb 2
12285 \& void lex_unstuff( char *ptr)
12286 \& void Perl_lex_unstuff(pTHX_ char *ptr)
12287 .Ve
12288 .RE
12289 .RS 4
12290 .RE
12291 .ie n .IP """parse_arithexpr""" 4
12292 .el .IP \f(CWparse_arithexpr\fR 4
12293 .IX Xref "parse_arithexpr"
12294 .IX Item "parse_arithexpr"
12295 NOTE: \f(CW\*(C`parse_arithexpr\*(C'\fR is \fBexperimental\fR and may change or be
12296 removed without notice.
12297 .Sp
12298 Parse a Perl arithmetic expression. This may contain operators of precedence
12299 down to the bit shift operators. The expression must be followed (and thus
12300 terminated) either by a comparison or lower\-precedence operator or by
12301 something that would normally terminate an expression such as semicolon.
12302 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
12303 otherwise it is mandatory. It is up to the caller to ensure that the
12304 dynamic parser state ("PL_parser" et al) is correctly set to reflect
12305 the source of the code to be parsed and the lexical context for the
12306 expression.
12307 .Sp
12308 The op tree representing the expression is returned. If an optional
12309 expression is absent, a null pointer is returned, otherwise the pointer
12310 will be non\-null.
12311 .Sp
12312 If an error occurs in parsing or compilation, in most cases a valid op
12313 tree is returned anyway. The error is reflected in the parser state,
12314 normally resulting in a single exception at the top level of parsing
12315 which covers all the compilation errors that occurred. Some compilation
12316 errors, however, will throw an exception immediately.
12317 .RS 4
12318 .Sp
12319 .Vb 2
12320 \& OP * parse_arithexpr( U32 flags)
12321 \& OP * Perl_parse_arithexpr(pTHX_ U32 flags)
12322 .Ve
12323 .RE
12324 .RS 4
12325 .RE
12326 .ie n .IP """parse_barestmt""" 4
12327 .el .IP \f(CWparse_barestmt\fR 4
12328 .IX Xref "parse_barestmt"
12329 .IX Item "parse_barestmt"
12330 NOTE: \f(CW\*(C`parse_barestmt\*(C'\fR is \fBexperimental\fR and may change or be
12331 removed without notice.
12332 .Sp
12333 Parse a single unadorned Perl statement. This may be a normal imperative
12334 statement or a declaration that has compile\-time effect. It does not
12335 include any label or other affixture. It is up to the caller to ensure
12336 that the dynamic parser state ("PL_parser" et al) is correctly set to
12337 reflect the source of the code to be parsed and the lexical context for
12338 the statement.
12339 .Sp
12340 The op tree representing the statement is returned. This may be a
12341 null pointer if the statement is null, for example if it was actually
12342 a subroutine definition (which has compile\-time side effects). If not
12343 null, it will be ops directly implementing the statement, suitable to
12344 pass to "newSTATEOP". It will not normally include a \f(CW\*(C`nextstate\*(C'\fR or
12345 equivalent op (except for those embedded in a scope contained entirely
12346 within the statement).
12347 .Sp
12348 If an error occurs in parsing or compilation, in most cases a valid op
12349 tree (most likely null) is returned anyway. The error is reflected in
12350 the parser state, normally resulting in a single exception at the top
12351 level of parsing which covers all the compilation errors that occurred.
12352 Some compilation errors, however, will throw an exception immediately.
12353 .Sp
12354 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12355 be zero.
12356 .RS 4
12357 .Sp
12358 .Vb 2
12359 \& OP * parse_barestmt( U32 flags)
12360 \& OP * Perl_parse_barestmt(pTHX_ U32 flags)
12361 .Ve
12362 .RE
12363 .RS 4
12364 .RE
12365 .ie n .IP """parse_block""" 4
12366 .el .IP \f(CWparse_block\fR 4
12367 .IX Xref "parse_block"
12368 .IX Item "parse_block"
12369 NOTE: \f(CW\*(C`parse_block\*(C'\fR is \fBexperimental\fR and may change or be
12370 removed without notice.
12371 .Sp
12372 Parse a single complete Perl code block. This consists of an opening
12373 brace, a sequence of statements, and a closing brace. The block
12374 constitutes a lexical scope, so \f(CW\*(C`my\*(C'\fR variables and various compile\-time
12375 effects can be contained within it. It is up to the caller to ensure
12376 that the dynamic parser state ("PL_parser" et al) is correctly set to
12377 reflect the source of the code to be parsed and the lexical context for
12378 the statement.
12379 .Sp
12380 The op tree representing the code block is returned. This is always a
12381 real op, never a null pointer. It will normally be a \f(CW\*(C`lineseq\*(C'\fR list,
12382 including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops. No ops to construct any kind
12383 of runtime scope are included by virtue of it being a block.
12384 .Sp
12385 If an error occurs in parsing or compilation, in most cases a valid op
12386 tree (most likely null) is returned anyway. The error is reflected in
12387 the parser state, normally resulting in a single exception at the top
12388 level of parsing which covers all the compilation errors that occurred.
12389 Some compilation errors, however, will throw an exception immediately.
12390 .Sp
12391 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12392 be zero.
12393 .RS 4
12394 .Sp
12395 .Vb 2
12396 \& OP * parse_block( U32 flags)
12397 \& OP * Perl_parse_block(pTHX_ U32 flags)
12398 .Ve
12399 .RE
12400 .RS 4
12401 .RE
12402 .ie n .IP """parse_fullexpr""" 4
12403 .el .IP \f(CWparse_fullexpr\fR 4
12404 .IX Xref "parse_fullexpr"
12405 .IX Item "parse_fullexpr"
12406 NOTE: \f(CW\*(C`parse_fullexpr\*(C'\fR is \fBexperimental\fR and may change or be
12407 removed without notice.
12408 .Sp
12409 Parse a single complete Perl expression. This allows the full
12410 expression grammar, including the lowest\-precedence operators such
12411 as \f(CW\*(C`or\*(C'\fR. The expression must be followed (and thus terminated) by a
12412 token that an expression would normally be terminated by: end\-of\-file,
12413 closing bracketing punctuation, semicolon, or one of the keywords that
12414 signals a postfix expression\-statement modifier. If \f(CW\*(C`flags\*(C'\fR has the
12415 \&\f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional, otherwise it is
12416 mandatory. It is up to the caller to ensure that the dynamic parser
12417 state ("PL_parser" et al) is correctly set to reflect the source of
12418 the code to be parsed and the lexical context for the expression.
12419 .Sp
12420 The op tree representing the expression is returned. If an optional
12421 expression is absent, a null pointer is returned, otherwise the pointer
12422 will be non\-null.
12423 .Sp
12424 If an error occurs in parsing or compilation, in most cases a valid op
12425 tree is returned anyway. The error is reflected in the parser state,
12426 normally resulting in a single exception at the top level of parsing
12427 which covers all the compilation errors that occurred. Some compilation
12428 errors, however, will throw an exception immediately.
12429 .RS 4
12430 .Sp
12431 .Vb 2
12432 \& OP * parse_fullexpr( U32 flags)
12433 \& OP * Perl_parse_fullexpr(pTHX_ U32 flags)
12434 .Ve
12435 .RE
12436 .RS 4
12437 .RE
12438 .ie n .IP """parse_fullstmt""" 4
12439 .el .IP \f(CWparse_fullstmt\fR 4
12440 .IX Xref "parse_fullstmt"
12441 .IX Item "parse_fullstmt"
12442 NOTE: \f(CW\*(C`parse_fullstmt\*(C'\fR is \fBexperimental\fR and may change or be
12443 removed without notice.
12444 .Sp
12445 Parse a single complete Perl statement. This may be a normal imperative
12446 statement or a declaration that has compile\-time effect, and may include
12447 optional labels. It is up to the caller to ensure that the dynamic
12448 parser state ("PL_parser" et al) is correctly set to reflect the source
12449 of the code to be parsed and the lexical context for the statement.
12450 .Sp
12451 The op tree representing the statement is returned. This may be a
12452 null pointer if the statement is null, for example if it was actually
12453 a subroutine definition (which has compile\-time side effects). If not
12454 null, it will be the result of a "newSTATEOP" call, normally including
12455 a \f(CW\*(C`nextstate\*(C'\fR or equivalent op.
12456 .Sp
12457 If an error occurs in parsing or compilation, in most cases a valid op
12458 tree (most likely null) is returned anyway. The error is reflected in
12459 the parser state, normally resulting in a single exception at the top
12460 level of parsing which covers all the compilation errors that occurred.
12461 Some compilation errors, however, will throw an exception immediately.
12462 .Sp
12463 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12464 be zero.
12465 .RS 4
12466 .Sp
12467 .Vb 2
12468 \& OP * parse_fullstmt( U32 flags)
12469 \& OP * Perl_parse_fullstmt(pTHX_ U32 flags)
12470 .Ve
12471 .RE
12472 .RS 4
12473 .RE
12474 .ie n .IP """parse_label""" 4
12475 .el .IP \f(CWparse_label\fR 4
12476 .IX Xref "parse_label"
12477 .IX Item "parse_label"
12478 NOTE: \f(CW\*(C`parse_label\*(C'\fR is \fBexperimental\fR and may change or be
12479 removed without notice.
12480 .Sp
12481 Parse a single label, possibly optional, of the type that may prefix a
12482 Perl statement. It is up to the caller to ensure that the dynamic parser
12483 state ("PL_parser" et al) is correctly set to reflect the source of
12484 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
12485 label is optional, otherwise it is mandatory.
12486 .Sp
12487 The name of the label is returned in the form of a fresh scalar. If an
12488 optional label is absent, a null pointer is returned.
12489 .Sp
12490 If an error occurs in parsing, which can only occur if the label is
12491 mandatory, a valid label is returned anyway. The error is reflected in
12492 the parser state, normally resulting in a single exception at the top
12493 level of parsing which covers all the compilation errors that occurred.
12494 .RS 4
12495 .Sp
12496 .Vb 2
12497 \& SV * parse_label( U32 flags)
12498 \& SV * Perl_parse_label(pTHX_ U32 flags)
12499 .Ve
12500 .RE
12501 .RS 4
12502 .RE
12503 .ie n .IP """parse_listexpr""" 4
12504 .el .IP \f(CWparse_listexpr\fR 4
12505 .IX Xref "parse_listexpr"
12506 .IX Item "parse_listexpr"
12507 NOTE: \f(CW\*(C`parse_listexpr\*(C'\fR is \fBexperimental\fR and may change or be
12508 removed without notice.
12509 .Sp
12510 Parse a Perl list expression. This may contain operators of precedence
12511 down to the comma operator. The expression must be followed (and thus
12512 terminated) either by a low\-precedence logic operator such as \f(CW\*(C`or\*(C'\fR or by
12513 something that would normally terminate an expression such as semicolon.
12514 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
12515 otherwise it is mandatory. It is up to the caller to ensure that the
12516 dynamic parser state ("PL_parser" et al) is correctly set to reflect
12517 the source of the code to be parsed and the lexical context for the
12518 expression.
12519 .Sp
12520 The op tree representing the expression is returned. If an optional
12521 expression is absent, a null pointer is returned, otherwise the pointer
12522 will be non\-null.
12523 .Sp
12524 If an error occurs in parsing or compilation, in most cases a valid op
12525 tree is returned anyway. The error is reflected in the parser state,
12526 normally resulting in a single exception at the top level of parsing
12527 which covers all the compilation errors that occurred. Some compilation
12528 errors, however, will throw an exception immediately.
12529 .RS 4
12530 .Sp
12531 .Vb 2
12532 \& OP * parse_listexpr( U32 flags)
12533 \& OP * Perl_parse_listexpr(pTHX_ U32 flags)
12534 .Ve
12535 .RE
12536 .RS 4
12537 .RE
12538 .ie n .IP """parse_stmtseq""" 4
12539 .el .IP \f(CWparse_stmtseq\fR 4
12540 .IX Xref "parse_stmtseq"
12541 .IX Item "parse_stmtseq"
12542 NOTE: \f(CW\*(C`parse_stmtseq\*(C'\fR is \fBexperimental\fR and may change or be
12543 removed without notice.
12544 .Sp
12545 Parse a sequence of zero or more Perl statements. These may be normal
12546 imperative statements, including optional labels, or declarations
12547 that have compile\-time effect, or any mixture thereof. The statement
12548 sequence ends when a closing brace or end\-of\-file is encountered in a
12549 place where a new statement could have validly started. It is up to
12550 the caller to ensure that the dynamic parser state ("PL_parser" et al)
12551 is correctly set to reflect the source of the code to be parsed and the
12552 lexical context for the statements.
12553 .Sp
12554 The op tree representing the statement sequence is returned. This may
12555 be a null pointer if the statements were all null, for example if there
12556 were no statements or if there were only subroutine definitions (which
12557 have compile\-time side effects). If not null, it will be a \f(CW\*(C`lineseq\*(C'\fR
12558 list, normally including \f(CW\*(C`nextstate\*(C'\fR or equivalent ops.
12559 .Sp
12560 If an error occurs in parsing or compilation, in most cases a valid op
12561 tree is returned anyway. The error is reflected in the parser state,
12562 normally resulting in a single exception at the top level of parsing
12563 which covers all the compilation errors that occurred. Some compilation
12564 errors, however, will throw an exception immediately.
12565 .Sp
12566 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12567 be zero.
12568 .RS 4
12569 .Sp
12570 .Vb 2
12571 \& OP * parse_stmtseq( U32 flags)
12572 \& OP * Perl_parse_stmtseq(pTHX_ U32 flags)
12573 .Ve
12574 .RE
12575 .RS 4
12576 .RE
12577 .ie n .IP """parse_subsignature""" 4
12578 .el .IP \f(CWparse_subsignature\fR 4
12579 .IX Xref "parse_subsignature"
12580 .IX Item "parse_subsignature"
12581 NOTE: \f(CW\*(C`parse_subsignature\*(C'\fR is \fBexperimental\fR and may change or be
12582 removed without notice.
12583 .Sp
12584 Parse a subroutine signature declaration. This is the contents of the
12585 parentheses following a named or anonymous subroutine declaration when the
12586 \&\f(CW\*(C`signatures\*(C'\fR feature is enabled. Note that this function neither expects
12587 nor consumes the opening and closing parentheses around the signature; it
12588 is the caller\*(Aqs job to handle these.
12589 .Sp
12590 This function must only be called during parsing of a subroutine; after
12591 "start_subparse" has been called. It might allocate lexical variables on
12592 the pad for the current subroutine.
12593 .Sp
12594 The op tree to unpack the arguments from the stack at runtime is returned.
12595 This op tree should appear at the beginning of the compiled function. The
12596 caller may wish to use "op_append_list" to build their function body
12597 after it, or splice it together with the body before calling "newATTRSUB".
12598 .Sp
12599 The \f(CW\*(C`flags\*(C'\fR parameter is reserved for future use, and must always
12600 be zero.
12601 .RS 4
12602 .Sp
12603 .Vb 2
12604 \& OP * parse_subsignature( U32 flags)
12605 \& OP * Perl_parse_subsignature(pTHX_ U32 flags)
12606 .Ve
12607 .RE
12608 .RS 4
12609 .RE
12610 .ie n .IP """parse_termexpr""" 4
12611 .el .IP \f(CWparse_termexpr\fR 4
12612 .IX Xref "parse_termexpr"
12613 .IX Item "parse_termexpr"
12614 NOTE: \f(CW\*(C`parse_termexpr\*(C'\fR is \fBexperimental\fR and may change or be
12615 removed without notice.
12616 .Sp
12617 Parse a Perl term expression. This may contain operators of precedence
12618 down to the assignment operators. The expression must be followed (and thus
12619 terminated) either by a comma or lower\-precedence operator or by
12620 something that would normally terminate an expression such as semicolon.
12621 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`PARSE_OPTIONAL\*(C'\fR bit set, then the expression is optional,
12622 otherwise it is mandatory. It is up to the caller to ensure that the
12623 dynamic parser state ("PL_parser" et al) is correctly set to reflect
12624 the source of the code to be parsed and the lexical context for the
12625 expression.
12626 .Sp
12627 The op tree representing the expression is returned. If an optional
12628 expression is absent, a null pointer is returned, otherwise the pointer
12629 will be non\-null.
12630 .Sp
12631 If an error occurs in parsing or compilation, in most cases a valid op
12632 tree is returned anyway. The error is reflected in the parser state,
12633 normally resulting in a single exception at the top level of parsing
12634 which covers all the compilation errors that occurred. Some compilation
12635 errors, however, will throw an exception immediately.
12636 .RS 4
12637 .Sp
12638 .Vb 2
12639 \& OP * parse_termexpr( U32 flags)
12640 \& OP * Perl_parse_termexpr(pTHX_ U32 flags)
12641 .Ve
12642 .RE
12643 .RS 4
12644 .RE
12645 .ie n .IP """PL_parser""" 4
12646 .el .IP \f(CWPL_parser\fR 4
12647 .IX Xref "PL_parser"
12648 .IX Item "PL_parser"
12649 Pointer to a structure encapsulating the state of the parsing operation
12650 currently in progress. The pointer can be locally changed to perform
12651 a nested parse without interfering with the state of an outer parse.
12652 Individual members of \f(CW\*(C`PL_parser\*(C'\fR have their own documentation.
12653 .ie n .IP """PL_parser\->bufend""" 4
12654 .el .IP \f(CWPL_parser\->bufend\fR 4
12655 .IX Xref "PL_parser->bufend"
12656 .IX Item "PL_parser->bufend"
12657 NOTE: \f(CW\*(C`PL_parser\->bufend\*(C'\fR is \fBexperimental\fR and may change or be
12658 removed without notice.
12659 .Sp
12660 Direct pointer to the end of the chunk of text currently being lexed, the
12661 end of the lexer buffer. This is equal to \f(CW\*(C`SvPVX(PL_parser\->linestr)
12662 + SvCUR(PL_parser\->linestr)\*(C'\fR. A \f(CW\*(C`NUL\*(C'\fR character (zero octet) is
12663 always located at the end of the buffer, and does not count as part of
12664 the buffer\*(Aqs contents.
12665 .ie n .IP """PL_parser\->bufptr""" 4
12666 .el .IP \f(CWPL_parser\->bufptr\fR 4
12667 .IX Xref "PL_parser->bufptr"
12668 .IX Item "PL_parser->bufptr"
12669 NOTE: \f(CW\*(C`PL_parser\->bufptr\*(C'\fR is \fBexperimental\fR and may change or be
12670 removed without notice.
12671 .Sp
12672 Points to the current position of lexing inside the lexer buffer.
12673 Characters around this point may be freely examined, within
12674 the range delimited by \f(CWSvPVX("PL_parser\->linestr")\fR and
12675 "PL_parser\->bufend". The octets of the buffer may be intended to be
12676 interpreted as either UTF\-8 or Latin\-1, as indicated by "lex_bufutf8".
12677 .Sp
12678 Lexing code (whether in the Perl core or not) moves this pointer past
12679 the characters that it consumes. It is also expected to perform some
12680 bookkeeping whenever a newline character is consumed. This movement
12681 can be more conveniently performed by the function "lex_read_to",
12682 which handles newlines appropriately.
12683 .Sp
12684 Interpretation of the buffer\*(Aqs octets can be abstracted out by
12685 using the slightly higher\-level functions "lex_peek_unichar" and
12686 "lex_read_unichar".
12687 .ie n .IP """PL_parser\->linestart""" 4
12688 .el .IP \f(CWPL_parser\->linestart\fR 4
12689 .IX Xref "PL_parser->linestart"
12690 .IX Item "PL_parser->linestart"
12691 NOTE: \f(CW\*(C`PL_parser\->linestart\*(C'\fR is \fBexperimental\fR and may change or be
12692 removed without notice.
12693 .Sp
12694 Points to the start of the current line inside the lexer buffer.
12695 This is useful for indicating at which column an error occurred, and
12696 not much else. This must be updated by any lexing code that consumes
12697 a newline; the function "lex_read_to" handles this detail.
12698 .ie n .IP """PL_parser\->linestr""" 4
12699 .el .IP \f(CWPL_parser\->linestr\fR 4
12700 .IX Xref "PL_parser->linestr"
12701 .IX Item "PL_parser->linestr"
12702 NOTE: \f(CW\*(C`PL_parser\->linestr\*(C'\fR is \fBexperimental\fR and may change or be
12703 removed without notice.
12704 .Sp
12705 Buffer scalar containing the chunk currently under consideration of the
12706 text currently being lexed. This is always a plain string scalar (for
12707 which \f(CW\*(C`SvPOK\*(C'\fR is true). It is not intended to be used as a scalar by
12708 normal scalar means; instead refer to the buffer directly by the pointer
12709 variables described below.
12710 .Sp
12711 The lexer maintains various \f(CW\*(C`char*\*(C'\fR pointers to things in the
12712 \&\f(CW\*(C`PL_parser\->linestr\*(C'\fR buffer. If \f(CW\*(C`PL_parser\->linestr\*(C'\fR is ever
12713 reallocated, all of these pointers must be updated. Don\*(Aqt attempt to
12714 do this manually, but rather use "lex_grow_linestr" if you need to
12715 reallocate the buffer.
12716 .Sp
12717 The content of the text chunk in the buffer is commonly exactly one
12718 complete line of input, up to and including a newline terminator,
12719 but there are situations where it is otherwise. The octets of the
12720 buffer may be intended to be interpreted as either UTF\-8 or Latin\-1.
12721 The function "lex_bufutf8" tells you which. Do not use the \f(CW\*(C`SvUTF8\*(C'\fR
12722 flag on this scalar, which may disagree with it.
12723 .Sp
12724 For direct examination of the buffer, the variable
12725 "PL_parser\->bufend" points to the end of the buffer. The current
12726 lexing position is pointed to by "PL_parser\->bufptr". Direct use
12727 of these pointers is usually preferable to examination of the scalar
12728 through normal scalar means.
12729 .ie n .IP """resume_compcv_and_save""" 4
12730 .el .IP \f(CWresume_compcv_and_save\fR 4
12731 .IX Xref "resume_compcv_and_save"
12732 .IX Item "resume_compcv_and_save"
12733 Resumes a buffer previously suspended by the \f(CW\*(C`suspend_compcv\*(C'\fR function, in a
12734 way that will be re\-suspended at the end of the scope so it can be used again
12735 later. This should be used within an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR scoped pair.
12736 .RS 4
12737 .Sp
12738 .Vb 1
12739 \& void resume_compcv_and_save(struct suspended_compcv *buffer)
12740 .Ve
12741 .RE
12742 .RS 4
12743 .RE
12744 .ie n .IP """resume_compcv_final""" 4
12745 .el .IP \f(CWresume_compcv_final\fR 4
12746 .IX Xref "resume_compcv_final"
12747 .IX Item "resume_compcv_final"
12748 Resumes the parser state previously saved using the \f(CW\*(C`suspend_compcv\*(C'\fR function
12749 for a final time before being compiled into a full CV. This should be used
12750 within an \f(CW\*(C`ENTER\*(C'\fR/\f(CW\*(C`LEAVE\*(C'\fR scoped pair.
12751 .RS 4
12752 .Sp
12753 .Vb 1
12754 \& void resume_compcv_final(struct suspended_compcv *buffer)
12755 .Ve
12756 .RE
12757 .RS 4
12758 .RE
12759 .ie n .IP """suspend_compcv""" 4
12760 .el .IP \f(CWsuspend_compcv\fR 4
12761 .IX Xref "suspend_compcv"
12762 .IX Item "suspend_compcv"
12763 Implements part of the concept of a "suspended compilation CV", which can be
12764 used to pause the parser and compiler during parsing a CV in order to come
12765 back to it later on.
12766 .Sp
12767 This function saves the current state of the subroutine under compilation
12768 (\f(CW\*(C`PL_compcv\*(C'\fR) into the supplied buffer. This should be used initially to
12769 create the state in the buffer, as the final thing before a \f(CW\*(C`LEAVE\*(C'\fR within a
12770 block.
12771 .Sp
12772 .Vb 3
12773 \& ENTER;
12774 \& start_subparse(0);
12775 \& ...
12776 \&
12777 \& suspend_compcv(&buffer);
12778 \& LEAVE;
12779 .Ve
12780 .Sp
12781 Once suspended, the \f(CW\*(C`resume_compcv_final\*(C'\fR or \f(CW\*(C`resume_compcv_and_save\*(C'\fR
12782 function can later be used to continue the parsing from the point this stopped.
12783 .RS 4
12784 .Sp
12785 .Vb 2
12786 \& void suspend_compcv( struct suspended_compcv *buffer)
12787 \& void Perl_suspend_compcv(pTHX_ struct suspended_compcv *buffer)
12788 .Ve
12789 .RE
12790 .RS 4
12791 .RE
12792 .ie n .IP """valid_identifier_pve""" 4
12793 .el .IP \f(CWvalid_identifier_pve\fR 4
12794 .IX Xref "valid_identifier_pve"
12795 .IX Item "valid_identifier_pve"
12796 Returns true if the string given by \f(CW\*(C`s\*(C'\fR until \f(CW\*(C`end\*(C'\fR would be considered
12797 valid as a Perl identifier. That is, it must begin with a character matching
12798 \&\f(CW\*(C`isIDFIRST\*(C'\fR, followed by characters all matching \f(CW\*(C`isIDCONT\*(C'\fR. An empty
12799 string (i.e. when \f(CW\*(C`end\*(C'\fR is \f(CW\*(C`s\*(C'\fR) will return false.
12800 .Sp
12801 If \f(CW\*(C`flags\*(C'\fR contains the \f(CW\*(C`SVf_UTF8\*(C'\fR bit, then the string is presumed to be
12802 encoded in UTF\-8, and suitable Unicode character test functions will be used.
12803 .RS 4
12804 .Sp
12805 .Vb 4
12806 \& bool valid_identifier_pve( const char *s,
12807 \& const char *end, U32 flags)
12808 \& bool Perl_valid_identifier_pve(pTHX_ const char *s,
12809 \& const char *end, U32 flags)
12810 .Ve
12811 .RE
12812 .RS 4
12813 .RE
12814 .ie n .IP """valid_identifier_pvn""" 4
12815 .el .IP \f(CWvalid_identifier_pvn\fR 4
12816 .IX Xref "valid_identifier_pvn"
12817 .IX Item "valid_identifier_pvn"
12818 Returns true if the string given by \f(CW\*(C`s\*(C'\fR whose length is \f(CW\*(C`len\*(C'\fR would be
12819 considered valid as a Perl identifier. That is, it must begin with a
12820 character matching \f(CW\*(C`isIDFIRST\*(C'\fR, followed by characters all matching
12821 \&\f(CW\*(C`isIDCONT\*(C'\fR. An empty string (i.e. when \f(CW\*(C`len\*(C'\fR is zero) will return false.
12822 .Sp
12823 If \f(CW\*(C`flags\*(C'\fR contains the \f(CW\*(C`SVf_UTF8\*(C'\fR bit, then the string is presumed to be
12824 encoded in UTF\-8, and suitable Unicode character test functions will be used.
12825 .RS 4
12826 .Sp
12827 .Vb 4
12828 \& bool valid_identifier_pvn( const char *s, STRLEN len,
12829 \& U32 flags)
12830 \& bool Perl_valid_identifier_pvn(pTHX_ const char *s, STRLEN len,
12831 \& U32 flags)
12832 .Ve
12833 .RE
12834 .RS 4
12835 .RE
12836 .ie n .IP """valid_identifier_sv""" 4
12837 .el .IP \f(CWvalid_identifier_sv\fR 4
12838 .IX Xref "valid_identifier_sv"
12839 .IX Item "valid_identifier_sv"
12840 Returns true if the given SV contains a non\-empty string whose characters
12841 match accoding to \f(CW\*(C`valid_identifier_pvn\*(C'\fR. Returns false if given NULL, an
12842 undefined SV, or a SV that does not contain a non\-empty string.
12843 .Sp
12844 Does not invoke \f(CW\*(C`get\*(C'\fR magic on the SV beforehand.
12845 .RS 4
12846 .Sp
12847 .Vb 2
12848 \& bool valid_identifier_sv( SV *sv)
12849 \& bool Perl_valid_identifier_sv(pTHX_ SV *sv)
12850 .Ve
12851 .RE
12852 .RS 4
12853 .RE
12854 .ie n .IP """wrap_infix_plugin""" 4
12855 .el .IP \f(CWwrap_infix_plugin\fR 4
12856 .IX Xref "wrap_infix_plugin"
12857 .IX Item "wrap_infix_plugin"
12858 NOTE: \f(CW\*(C`wrap_infix_plugin\*(C'\fR is \fBexperimental\fR and may change or be
12859 removed without notice.
12860 .Sp
12861 \&\fBNOTE:\fR This API exists entirely for the purpose of making the CPAN module
12862 \&\f(CW\*(C`XS::Parse::Infix\*(C'\fR work. It is not expected that additional modules will make
12863 use of it; rather, that they should use \f(CW\*(C`XS::Parse::Infix\*(C'\fR to provide parsing
12864 of new infix operators.
12865 .Sp
12866 Puts a C function into the chain of infix plugins. This is the preferred
12867 way to manipulate the "PL_infix_plugin" variable. \f(CW\*(C`new_plugin\*(C'\fR is a
12868 pointer to the C function that is to be added to the infix plugin chain, and
12869 \&\f(CW\*(C`old_plugin_p\*(C'\fR points to a storage location where a pointer to the next
12870 function in the chain will be stored. The value of \f(CW\*(C`new_plugin\*(C'\fR is written
12871 into the "PL_infix_plugin" variable, while the value previously stored there
12872 is written to \f(CW*old_plugin_p\fR.
12873 .Sp
12874 Direct access to "PL_infix_plugin" should be avoided.
12875 .RS 4
12876 .Sp
12877 .Vb 5
12878 \& void wrap_infix_plugin( Perl_infix_plugin_t new_plugin,
12879 \& Perl_infix_plugin_t *old_plugin_p)
12880 \& void Perl_wrap_infix_plugin(pTHX_
12881 \& Perl_infix_plugin_t new_plugin,
12882 \& Perl_infix_plugin_t *old_plugin_p)
12883 .Ve
12884 .RE
12885 .RS 4
12886 .RE
12887 .ie n .IP """wrap_keyword_plugin""" 4
12888 .el .IP \f(CWwrap_keyword_plugin\fR 4
12889 .IX Xref "wrap_keyword_plugin"
12890 .IX Item "wrap_keyword_plugin"
12891 NOTE: \f(CW\*(C`wrap_keyword_plugin\*(C'\fR is \fBexperimental\fR and may change or be
12892 removed without notice.
12893 .Sp
12894 Puts a C function into the chain of keyword plugins. This is the
12895 preferred way to manipulate the "PL_keyword_plugin" variable.
12896 \&\f(CW\*(C`new_plugin\*(C'\fR is a pointer to the C function that is to be added to the
12897 keyword plugin chain, and \f(CW\*(C`old_plugin_p\*(C'\fR points to the storage location
12898 where a pointer to the next function in the chain will be stored. The
12899 value of \f(CW\*(C`new_plugin\*(C'\fR is written into the "PL_keyword_plugin" variable,
12900 while the value previously stored there is written to \f(CW*old_plugin_p\fR.
12901 .Sp
12902 "PL_keyword_plugin" is global to an entire process, and a module wishing
12903 to hook keyword parsing may find itself invoked more than once per
12904 process, typically in different threads. To handle that situation, this
12905 function is idempotent. The location \f(CW*old_plugin_p\fR must initially
12906 (once per process) contain a null pointer. A C variable of static
12907 duration (declared at file scope, typically also marked \f(CW\*(C`static\*(C'\fR to give
12908 it internal linkage) will be implicitly initialised appropriately, if it
12909 does not have an explicit initialiser. This function will only actually
12910 modify the plugin chain if it finds \f(CW*old_plugin_p\fR to be null. This
12911 function is also thread safe on the small scale. It uses appropriate
12912 locking to avoid race conditions in accessing "PL_keyword_plugin".
12913 .Sp
12914 When this function is called, the function referenced by \f(CW\*(C`new_plugin\*(C'\fR
12915 must be ready to be called, except for \f(CW*old_plugin_p\fR being unfilled.
12916 In a threading situation, \f(CW\*(C`new_plugin\*(C'\fR may be called immediately, even
12917 before this function has returned. \f(CW*old_plugin_p\fR will always be
12918 appropriately set before \f(CW\*(C`new_plugin\*(C'\fR is called. If \f(CW\*(C`new_plugin\*(C'\fR
12919 decides not to do anything special with the identifier that it is given
12920 (which is the usual case for most calls to a keyword plugin), it must
12921 chain the plugin function referenced by \f(CW*old_plugin_p\fR.
12922 .Sp
12923 Taken all together, XS code to install a keyword plugin should typically
12924 look something like this:
12925 .Sp
12926 .Vb 10
12927 \& static Perl_keyword_plugin_t next_keyword_plugin;
12928 \& static OP *my_keyword_plugin(pTHX_
12929 \& char *keyword_ptr, STRLEN keyword_len, OP **op_ptr)
12930 \& {
12931 \& if (memEQs(keyword_ptr, keyword_len,
12932 \& "my_new_keyword")) {
12933 \& ...
12934 \& } else {
12935 \& return next_keyword_plugin(aTHX_
12936 \& keyword_ptr, keyword_len, op_ptr);
12937 \& }
12938 \& }
12939 \& BOOT:
12940 \& wrap_keyword_plugin(my_keyword_plugin,
12941 \& &next_keyword_plugin);
12942 .Ve
12943 .Sp
12944 Direct access to "PL_keyword_plugin" should be avoided.
12945 .RS 4
12946 .Sp
12947 .Vb 5
12948 \& void wrap_keyword_plugin(Perl_keyword_plugin_t new_plugin,
12949 \& Perl_keyword_plugin_t *old_plugin_p)
12950 \& void Perl_wrap_keyword_plugin(pTHX_
12951 \& Perl_keyword_plugin_t new_plugin,
12952 \& Perl_keyword_plugin_t *old_plugin_p)
12953 .Ve
12954 .RE
12955 .RS 4
12956 .RE
12957 .SH Locales
12958 .IX Header "Locales"
12959 .ie n .IP """DECLARATION_FOR_LC_NUMERIC_MANIPULATION""" 4
12960 .el .IP \f(CWDECLARATION_FOR_LC_NUMERIC_MANIPULATION\fR 4
12961 .IX Xref "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
12962 .IX Item "DECLARATION_FOR_LC_NUMERIC_MANIPULATION"
12963 This macro should be used as a statement. It declares a private variable
12964 (whose name begins with an underscore) that is needed by the other macros in
12965 this section. Failing to include this correctly should lead to a syntax error.
12966 For compatibility with C89 C compilers it should be placed in a block before
12967 any executable statements.
12968 .RS 4
12969 .Sp
12970 .Vb 1
12971 \& void DECLARATION_FOR_LC_NUMERIC_MANIPULATION
12972 .Ve
12973 .RE
12974 .RS 4
12975 .RE
12976 .ie n .IP """HAS_DUPLOCALE""" 4
12977 .el .IP \f(CWHAS_DUPLOCALE\fR 4
12978 .IX Xref "HAS_DUPLOCALE"
12979 .IX Item "HAS_DUPLOCALE"
12980 This symbol, if defined, indicates that the \f(CW\*(C`duplocale\*(C'\fR routine is
12981 available to duplicate a locale object.
12982 .ie n .IP """HAS_FREELOCALE""" 4
12983 .el .IP \f(CWHAS_FREELOCALE\fR 4
12984 .IX Xref "HAS_FREELOCALE"
12985 .IX Item "HAS_FREELOCALE"
12986 This symbol, if defined, indicates that the \f(CW\*(C`freelocale\*(C'\fR routine is
12987 available to deallocates the resources associated with a locale object.
12988 .ie n .IP """HAS_LC_MONETARY_2008""" 4
12989 .el .IP \f(CWHAS_LC_MONETARY_2008\fR 4
12990 .IX Xref "HAS_LC_MONETARY_2008"
12991 .IX Item "HAS_LC_MONETARY_2008"
12992 This symbol, if defined, indicates that the localeconv routine is
12993 available and has the additional members added in \f(CW\*(C`POSIX\*(C'\fR 1003.1\-2008.
12994 .ie n .IP """HAS_LOCALECONV""" 4
12995 .el .IP \f(CWHAS_LOCALECONV\fR 4
12996 .IX Xref "HAS_LOCALECONV"
12997 .IX Item "HAS_LOCALECONV"
12998 This symbol, if defined, indicates that the \f(CW\*(C`localeconv\*(C'\fR routine is
12999 available for numeric and monetary formatting conventions.
13000 .ie n .IP """HAS_LOCALECONV_L""" 4
13001 .el .IP \f(CWHAS_LOCALECONV_L\fR 4
13002 .IX Xref "HAS_LOCALECONV_L"
13003 .IX Item "HAS_LOCALECONV_L"
13004 This symbol, if defined, indicates that the \f(CW\*(C`localeconv_l\*(C'\fR routine is
13005 available to query certain information about a locale.
13006 .ie n .IP """HAS_NEWLOCALE""" 4
13007 .el .IP \f(CWHAS_NEWLOCALE\fR 4
13008 .IX Xref "HAS_NEWLOCALE"
13009 .IX Item "HAS_NEWLOCALE"
13010 This symbol, if defined, indicates that the \f(CW\*(C`newlocale\*(C'\fR routine is
13011 available to return a new locale object or modify an existing
13012 locale object.
13013 .ie n .IP """HAS_NL_LANGINFO""" 4
13014 .el .IP \f(CWHAS_NL_LANGINFO\fR 4
13015 .IX Xref "HAS_NL_LANGINFO"
13016 .IX Item "HAS_NL_LANGINFO"
13017 This symbol, if defined, indicates that the \f(CW\*(C`nl_langinfo\*(C'\fR routine is
13018 available to return locale data. You will also need \fIlanginfo.h\fR
13019 and therefore \f(CW\*(C`I_LANGINFO\*(C'\fR.
13020 .ie n .IP """HAS_NL_LANGINFO_L""" 4
13021 .el .IP \f(CWHAS_NL_LANGINFO_L\fR 4
13022 .IX Xref "HAS_NL_LANGINFO_L"
13023 .IX Item "HAS_NL_LANGINFO_L"
13024 This symbol, if defined, indicates that the \f(CW\*(C`nl_langinfo_l\*(C'\fR routine is
13025 available to return locale data. You will also need \fIlanginfo.h\fR
13026 and therefore \f(CW\*(C`I_LANGINFO\*(C'\fR.
13027 .ie n .IP """HAS_QUERYLOCALE""" 4
13028 .el .IP \f(CWHAS_QUERYLOCALE\fR 4
13029 .IX Xref "HAS_QUERYLOCALE"
13030 .IX Item "HAS_QUERYLOCALE"
13031 This symbol, if defined, indicates that the \f(CW\*(C`querylocale\*(C'\fR routine is
13032 available to return the name of the locale for a category mask.
13033 .ie n .IP """HAS_SETLOCALE""" 4
13034 .el .IP \f(CWHAS_SETLOCALE\fR 4
13035 .IX Xref "HAS_SETLOCALE"
13036 .IX Item "HAS_SETLOCALE"
13037 This symbol, if defined, indicates that the \f(CW\*(C`setlocale\*(C'\fR routine is
13038 available to handle locale\-specific ctype implementations.
13039 .ie n .IP """HAS_SETLOCALE_R""" 4
13040 .el .IP \f(CWHAS_SETLOCALE_R\fR 4
13041 .IX Xref "HAS_SETLOCALE_R"
13042 .IX Item "HAS_SETLOCALE_R"
13043 This symbol, if defined, indicates that the \f(CW\*(C`setlocale_r\*(C'\fR routine
13044 is available to setlocale re\-entrantly.
13045 .ie n .IP """HAS_USELOCALE""" 4
13046 .el .IP \f(CWHAS_USELOCALE\fR 4
13047 .IX Xref "HAS_USELOCALE"
13048 .IX Item "HAS_USELOCALE"
13049 This symbol, if defined, indicates that the \f(CW\*(C`uselocale\*(C'\fR routine is
13050 available to set the current locale for the calling thread.
13051 .ie n .IP """I_LANGINFO""" 4
13052 .el .IP \f(CWI_LANGINFO\fR 4
13053 .IX Xref "I_LANGINFO"
13054 .IX Item "I_LANGINFO"
13055 This symbol, if defined, indicates that \fIlanginfo.h\fR exists and
13056 should be included.
13057 .RS 4
13058 .Sp
13059 .Vb 3
13060 \& #ifdef I_LANGINFO
13061 \& #include <langinfo.h>
13062 \& #endif
13063 .Ve
13064 .RE
13065 .RS 4
13066 .RE
13067 .ie n .IP """I_LOCALE""" 4
13068 .el .IP \f(CWI_LOCALE\fR 4
13069 .IX Xref "I_LOCALE"
13070 .IX Item "I_LOCALE"
13071 This symbol, if defined, indicates to the C program that it should
13072 include \fIlocale.h\fR.
13073 .RS 4
13074 .Sp
13075 .Vb 3
13076 \& #ifdef I_LOCALE
13077 \& #include <locale.h>
13078 \& #endif
13079 .Ve
13080 .RE
13081 .RS 4
13082 .RE
13083 .ie n .IP """I_XLOCALE""" 4
13084 .el .IP \f(CWI_XLOCALE\fR 4
13085 .IX Xref "I_XLOCALE"
13086 .IX Item "I_XLOCALE"
13087 This symbol, if defined, indicates to the C program that the
13088 header \fIxlocale.h\fR is available. See also \f(CW"NEED_XLOCALE_H"\fR
13089 .RS 4
13090 .Sp
13091 .Vb 3
13092 \& #ifdef I_XLOCALE
13093 \& #include <xlocale.h>
13094 \& #endif
13095 .Ve
13096 .RE
13097 .RS 4
13098 .RE
13099 .ie n .IP """IN_LOCALE""" 4
13100 .el .IP \f(CWIN_LOCALE\fR 4
13101 .IX Xref "IN_LOCALE"
13102 .IX Item "IN_LOCALE"
13103 Evaluates to TRUE if the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
13104 .RS 4
13105 .Sp
13106 .Vb 1
13107 \& bool IN_LOCALE
13108 .Ve
13109 .RE
13110 .RS 4
13111 .RE
13112 .ie n .IP """IN_LOCALE_COMPILETIME""" 4
13113 .el .IP \f(CWIN_LOCALE_COMPILETIME\fR 4
13114 .IX Xref "IN_LOCALE_COMPILETIME"
13115 .IX Item "IN_LOCALE_COMPILETIME"
13116 Evaluates to TRUE if, when compiling a perl program (including an \f(CW\*(C`eval\*(C'\fR) if
13117 the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
13118 .RS 4
13119 .Sp
13120 .Vb 1
13121 \& bool IN_LOCALE_COMPILETIME
13122 .Ve
13123 .RE
13124 .RS 4
13125 .RE
13126 .ie n .IP """IN_LOCALE_RUNTIME""" 4
13127 .el .IP \f(CWIN_LOCALE_RUNTIME\fR 4
13128 .IX Xref "IN_LOCALE_RUNTIME"
13129 .IX Item "IN_LOCALE_RUNTIME"
13130 Evaluates to TRUE if, when executing a perl program (including an \f(CW\*(C`eval\*(C'\fR) if
13131 the plain locale pragma without a parameter (\f(CW\*(C`use\ locale\*(C'\fR) is in effect.
13132 .RS 4
13133 .Sp
13134 .Vb 1
13135 \& bool IN_LOCALE_RUNTIME
13136 .Ve
13137 .RE
13138 .RS 4
13139 .RE
13140 .ie n .IP """NEED_XLOCALE_H""" 4
13141 .el .IP \f(CWNEED_XLOCALE_H\fR 4
13142 .IX Xref "NEED_XLOCALE_H"
13143 .IX Item "NEED_XLOCALE_H"
13144 This symbol, if defined, indicates that the C program should
13145 include \fIxlocale.h\fR to get \f(CWnewlocale()\fR and its friends.
13146 .ie n .IP """Perl_langinfo*""" 4
13147 .el .IP \f(CWPerl_langinfo*\fR 4
13148 .IX Item "Perl_langinfo*"
13149 .PD 0
13150 .ie n .IP """Perl_langinfo8*""" 4
13151 .el .IP \f(CWPerl_langinfo8*\fR 4
13152 .IX Item "Perl_langinfo8*"
13153 .PD
13154 Described under \f(CW"sv_langinfo"\fR
13155 .ie n .IP """PERL_LC_ALL_CATEGORY_POSITIONS_INIT""" 4
13156 .el .IP \f(CWPERL_LC_ALL_CATEGORY_POSITIONS_INIT\fR 4
13157 .IX Xref "PERL_LC_ALL_CATEGORY_POSITIONS_INIT"
13158 .IX Item "PERL_LC_ALL_CATEGORY_POSITIONS_INIT"
13159 This symbol, when defined, gives the C initializer for an array whose
13160 element [0] is the first category in the string returned by
13161 \&\f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR when not all categories are the same, on
13162 systems that use a positional notation. After element [0] is
13163 \&\f(CW\*(C`LC_ALL_SEPARATOR\*(C'\fR, then the category given by element [1] and so on.
13164 .ie n .IP """PERL_LC_ALL_SEPARATOR""" 4
13165 .el .IP \f(CWPERL_LC_ALL_SEPARATOR\fR 4
13166 .IX Xref "PERL_LC_ALL_SEPARATOR"
13167 .IX Item "PERL_LC_ALL_SEPARATOR"
13168 This symbol, if defined, gives the string returned by
13169 \&\f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR to separate categories that are in different
13170 locales on systems that use a positional notation as opposed to
13171 \&\*(Aqname=value\*(Aq pairs. An example on some platforms could be the \*(Aq/\*(Aq in
13172 "C/\f(CW\*(C`de_DE\*(C'\fR/C/\f(CW\*(C`en_UK\*(C'\fR/C/C"
13173 .ie n .IP """PERL_LC_ALL_USES_NAME_VALUE_PAIRS""" 4
13174 .el .IP \f(CWPERL_LC_ALL_USES_NAME_VALUE_PAIRS\fR 4
13175 .IX Xref "PERL_LC_ALL_USES_NAME_VALUE_PAIRS"
13176 .IX Item "PERL_LC_ALL_USES_NAME_VALUE_PAIRS"
13177 This symbol, if defined, indicates to the C program that the string
13178 returned by \f(CW\*(C`setlocale(LC_ALL, NULL)\*(C'\fR uses \*(Aqname=value;\*(Aq pairs to
13179 indicate what each category\*(Aqs locale is when they aren\*(Aqt all set to the
13180 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;..."
13181 When not defined, the system uses positional notation.
13182 .ie n .IP """Perl_localeconv""" 4
13183 .el .IP \f(CWPerl_localeconv\fR 4
13184 .IX Xref "Perl_localeconv"
13185 .IX Item "Perl_localeconv"
13186 This is a thread\-safe version of the libc \fBlocaleconv\fR\|(3). It is the same as
13187 POSIX::localeconv (returning a hash of the \f(CWlocaleconv()\fR
13188 fields), but directly callable from XS code. The hash is mortalized, so must
13189 be dealt with immediately.
13190 .RS 4
13191 .Sp
13192 .Vb 1
13193 \& HV * Perl_localeconv(pTHX)
13194 .Ve
13195 .RE
13196 .RS 4
13197 .RE
13198 .ie n .IP """Perl_setlocale""" 4
13199 .el .IP \f(CWPerl_setlocale\fR 4
13200 .IX Xref "Perl_setlocale"
13201 .IX Item "Perl_setlocale"
13202 This is an (almost) drop\-in replacement for the system \f(CW\*(C`\fR\f(CBsetlocale\fR\f(CW\|(3)\*(C'\fR,
13203 taking the same parameters, and returning the same information, except that it
13204 returns the correct underlying \f(CW\*(C`LC_NUMERIC\*(C'\fR locale. Regular \f(CW\*(C`setlocale\*(C'\fR will
13205 instead return \f(CW\*(C`C\*(C'\fR if the underlying locale has a non\-dot decimal point
13206 character, or a non\-empty thousands separator for displaying floating point
13207 numbers. This is because perl keeps that locale category such that it has a
13208 dot and empty separator, changing the locale briefly during the operations
13209 where the underlying one is required. \f(CW\*(C`Perl_setlocale\*(C'\fR knows about this, and
13210 compensates; regular \f(CW\*(C`setlocale\*(C'\fR doesn\*(Aqt.
13211 .Sp
13212 Another reason it isn\*(Aqt completely a drop\-in replacement is that it is
13213 declared to return \f(CW\*(C`const\ char\ *\*(C'\fR, whereas the system setlocale omits the
13214 \&\f(CW\*(C`const\*(C'\fR (presumably because its API was specified long ago, and can\*(Aqt be
13215 updated; it is illegal to change the information \f(CW\*(C`setlocale\*(C'\fR returns; doing
13216 so leads to segfaults.)
13217 .Sp
13218 Finally, \f(CW\*(C`Perl_setlocale\*(C'\fR works under all circumstances, whereas plain
13219 \&\f(CW\*(C`setlocale\*(C'\fR can be completely ineffective on some platforms under some
13220 configurations.
13221 .Sp
13222 Changing the locale is not a good idea when more than one thread is running,
13223 except on systems where the predefined variable \f(CW\*(C`${^SAFE_LOCALES}\*(C'\fR is
13224 non\-zero. This is because on such systems the locale is global to the whole
13225 process and not local to just the thread calling the function. So changing it
13226 in one thread instantaneously changes it in all. On some such systems, the
13227 system \f(CWsetlocale()\fR is ineffective, returning the wrong information, and
13228 failing to actually change the locale. z/OS refuses to try to change the
13229 locale once a second thread is created. \f(CW\*(C`Perl_setlocale\*(C'\fR, should give you
13230 accurate results of what actually happened on these problematic platforms,
13231 returning NULL if the system forbade the locale change.
13232 .Sp
13233 The return points to a per\-thread static buffer, which is overwritten the next
13234 time \f(CW\*(C`Perl_setlocale\*(C'\fR is called from the same thread.
13235 .RS 4
13236 .Sp
13237 .Vb 2
13238 \& const char * Perl_setlocale(const int category,
13239 \& const char *locale)
13240 .Ve
13241 .RE
13242 .RS 4
13243 .RE
13244 .ie n .IP """RESTORE_LC_NUMERIC""" 4
13245 .el .IP \f(CWRESTORE_LC_NUMERIC\fR 4
13246 .IX Xref "RESTORE_LC_NUMERIC"
13247 .IX Item "RESTORE_LC_NUMERIC"
13248 This is used in conjunction with one of the macros
13249 "STORE_LC_NUMERIC_SET_TO_NEEDED"
13250 and "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING" to properly restore the
13251 \&\f(CW\*(C`LC_NUMERIC\*(C'\fR state.
13252 .Sp
13253 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
13254 declare at compile time a private variable used by this macro and the two
13255 \&\f(CW\*(C`STORE\*(C'\fR ones. This macro should be called as a single statement, not an
13256 expression, but with an empty argument list, like this:
13257 .Sp
13258 .Vb 6
13259 \& {
13260 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
13261 \& ...
13262 \& RESTORE_LC_NUMERIC();
13263 \& ...
13264 \& }
13265 .Ve
13266 .RS 4
13267 .Sp
13268 .Vb 1
13269 \& void RESTORE_LC_NUMERIC()
13270 .Ve
13271 .RE
13272 .RS 4
13273 .RE
13274 .ie n .IP """SETLOCALE_ACCEPTS_ANY_LOCALE_NAME""" 4
13275 .el .IP \f(CWSETLOCALE_ACCEPTS_ANY_LOCALE_NAME\fR 4
13276 .IX Xref "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
13277 .IX Item "SETLOCALE_ACCEPTS_ANY_LOCALE_NAME"
13278 This symbol, if defined, indicates that the setlocale routine is
13279 available and it accepts any input locale name as valid.
13280 .ie n .IP """STORE_LC_NUMERIC_FORCE_TO_UNDERLYING""" 4
13281 .el .IP \f(CWSTORE_LC_NUMERIC_FORCE_TO_UNDERLYING\fR 4
13282 .IX Xref "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
13283 .IX Item "STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"
13284 This is used by XS code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale\-aware to force the
13285 locale for category \f(CW\*(C`LC_NUMERIC\*(C'\fR to be what perl thinks is the current
13286 underlying locale. (The perl interpreter could be wrong about what the
13287 underlying locale actually is if some C or XS code has called the C library
13288 function \fBsetlocale\fR\|(3) behind its back; calling "sync_locale" before calling
13289 this macro will update perl\*(Aqs records.)
13290 .Sp
13291 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
13292 declare at compile time a private variable used by this macro. This macro
13293 should be called as a single statement, not an expression, but with an empty
13294 argument list, like this:
13295 .Sp
13296 .Vb 8
13297 \& {
13298 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
13299 \& ...
13300 \& STORE_LC_NUMERIC_FORCE_TO_UNDERLYING();
13301 \& ...
13302 \& RESTORE_LC_NUMERIC();
13303 \& ...
13304 \& }
13305 .Ve
13306 .Sp
13307 The private variable is used to save the current locale state, so
13308 that the requisite matching call to "RESTORE_LC_NUMERIC" can restore it.
13309 .Sp
13310 On threaded perls not operating with thread\-safe functionality, this macro uses
13311 a mutex to force a critical section. Therefore the matching RESTORE should be
13312 close by, and guaranteed to be called.
13313 .RS 4
13314 .Sp
13315 .Vb 1
13316 \& void STORE_LC_NUMERIC_FORCE_TO_UNDERLYING()
13317 .Ve
13318 .RE
13319 .RS 4
13320 .RE
13321 .ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED""" 4
13322 .el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED\fR 4
13323 .IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED"
13324 .IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED"
13325 This is used to help wrap XS or C code that is \f(CW\*(C`LC_NUMERIC\*(C'\fR locale\-aware.
13326 This locale category is generally kept set to a locale where the decimal radix
13327 character is a dot, and the separator between groups of digits is empty. This
13328 is because most XS code that reads floating point numbers is expecting them to
13329 have this syntax.
13330 .Sp
13331 This macro makes sure the current \f(CW\*(C`LC_NUMERIC\*(C'\fR state is set properly, to be
13332 aware of locale if the call to the XS or C code from the Perl program is
13333 from within the scope of a \f(CW\*(C`use\ locale\*(C'\fR; or to ignore locale if the call is
13334 instead from outside such scope.
13335 .Sp
13336 This macro is the start of wrapping the C or XS code; the wrap ending is done
13337 by calling the "RESTORE_LC_NUMERIC" macro after the operation. Otherwise
13338 the state can be changed that will adversely affect other XS code.
13339 .Sp
13340 A call to "DECLARATION_FOR_LC_NUMERIC_MANIPULATION" must have been made to
13341 declare at compile time a private variable used by this macro. This macro
13342 should be called as a single statement, not an expression, but with an empty
13343 argument list, like this:
13344 .Sp
13345 .Vb 8
13346 \& {
13347 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
13348 \& ...
13349 \& STORE_LC_NUMERIC_SET_TO_NEEDED();
13350 \& ...
13351 \& RESTORE_LC_NUMERIC();
13352 \& ...
13353 \& }
13354 .Ve
13355 .Sp
13356 On threaded perls not operating with thread\-safe functionality, this macro uses
13357 a mutex to force a critical section. Therefore the matching RESTORE should be
13358 close by, and guaranteed to be called; see "WITH_LC_NUMERIC_SET_TO_NEEDED"
13359 for a more contained way to ensure that.
13360 .RS 4
13361 .Sp
13362 .Vb 1
13363 \& void STORE_LC_NUMERIC_SET_TO_NEEDED()
13364 .Ve
13365 .RE
13366 .RS 4
13367 .RE
13368 .ie n .IP """STORE_LC_NUMERIC_SET_TO_NEEDED_IN""" 4
13369 .el .IP \f(CWSTORE_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4
13370 .IX Xref "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
13371 .IX Item "STORE_LC_NUMERIC_SET_TO_NEEDED_IN"
13372 Same as "STORE_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
13373 as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller\*(Aqs
13374 responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR
13375 cannot have changed since the precalculation.
13376 .RS 4
13377 .Sp
13378 .Vb 1
13379 \& void STORE_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric)
13380 .Ve
13381 .RE
13382 .RS 4
13383 .RE
13384 .ie n .IP """sv_langinfo""" 4
13385 .el .IP \f(CWsv_langinfo\fR 4
13386 .IX Item "sv_langinfo"
13387 .PD 0
13388 .ie n .IP """Perl_langinfo""" 4
13389 .el .IP \f(CWPerl_langinfo\fR 4
13390 .IX Item "Perl_langinfo"
13391 .ie n .IP """Perl_langinfo8""" 4
13392 .el .IP \f(CWPerl_langinfo8\fR 4
13393 .IX Xref "Perl_langinfo Perl_langinfo8 sv_langinfo"
13394 .IX Item "Perl_langinfo8"
13395 .PD
13396 These perform the equivalent functionality as the system \f(CW\*(C`\fR\f(CBnl_langinfo\fR\f(CW\|(3)\*(C'\fR,
13397 taking the same \f(CW\*(C`item\*(C'\fR parameter values, but are preferred over calling that
13398 directly because they are portable to platforms lacking that function, are
13399 thread\-safe, and can automatically handle UTF\-8 strings.
13400 .Sp
13401 The simplest to use is \f(CW\*(C`sv_langinfo\*(C'\fR. It returns an SV containing the correct
13402 PV and UTF8ness, requiring no extra muss or fuss from you. New code should use
13403 this form.
13404 .Sp
13405 \&\f(CW\*(C`Perl_langinfo\*(C'\fR and \f(CW\*(C`Perl_langinfo8\*(C'\fR are retained for backwards
13406 compatibility. \f(CW\*(C`Perl_langinfo\*(C'\fR is an (almost) drop\-in replacement for the
13407 system \f(CW\*(C`\fR\f(CBnl_langinfo\fR\f(CW\|(3)\*(C'\fR, but exists on systems that lack a native
13408 \&\f(CW\*(C`nl_langinfo\*(C'\fR.
13409 .Sp
13410 \&\f(CW\*(C`Perl_langinfo8\*(C'\fR is identical to \f(CW\*(C`Perl_langinfo\*(C'\fR except for an additional
13411 parameter, a pointer to a variable declared as \f(CW"utf8ness_t"\fR, into which it
13412 returns to you how you should treat the returned string with regards to it
13413 being encoded in UTF\-8 or not.
13414 .Sp
13415 \&\f(CW\*(C`Perl_langinfo\*(C'\fR and \f(CW\*(C`Perl_langinfo8\*(C'\fR share private per\-thread memory that
13416 will be changed the next time either one of them is called with any input, but
13417 not before.
13418 .Sp
13419 Concerning the differences between these functions and plain \f(CWnl_langinfo()\fR:
13420 .RS 4
13421 .IP a. 4
13422 .IX Item "a."
13423 \&\f(CW\*(C`Perl_langinfo8\*(C'\fR has an extra parameter, described above. Besides this, the
13424 other reason they aren\*(Aqt quite a drop\-in replacement is actually an advantage.
13425 The \f(CW\*(C`const\*(C'\fRness of the return allows the compiler to catch attempts to write
13426 into the returned buffer, which is illegal and could cause run\-time crashes.
13427 .IP b. 4
13428 .IX Item "b."
13429 They deliver the correct results for the \f(CW\*(C`RADIXCHAR\*(C'\fR and \f(CW\*(C`THOUSEP\*(C'\fR items,
13430 without you having to write extra code. The reason for the extra code would be
13431 because these are from the \f(CW\*(C`LC_NUMERIC\*(C'\fR locale category, which is normally
13432 kept set by Perl so that the radix is a dot, and the separator is the empty
13433 string, no matter what the underlying locale is supposed to be, and so to get
13434 the expected results, you have to temporarily toggle into the underlying
13435 locale, and later toggle back. (You could use plain \f(CW\*(C`nl_langinfo\*(C'\fR and
13436 \&\f(CW"STORE_LC_NUMERIC_FORCE_TO_UNDERLYING"\fR for this but then you wouldn\*(Aqt get
13437 the other advantages of \f(CWPerl_langinfo()\fR; not keeping \f(CW\*(C`LC_NUMERIC\*(C'\fR in the C
13438 (or equivalent) locale would break a lot of CPAN, which is expecting the radix
13439 (decimal point) character to be a dot.)
13440 .IP c. 4
13441 .IX Item "c."
13442 The system function they replace can have its static return buffer trashed,
13443 not only by a subsequent call to that function, but by a \f(CW\*(C`freelocale\*(C'\fR,
13444 \&\f(CW\*(C`setlocale\*(C'\fR, or other locale change. \f(CW\*(C`sv_langinfo\*(C'\fR sidesteps this problem
13445 entirely; the returned buffer of the other two is not changed until the next
13446 call to one or the other, so the buffer is never in a trashed state.
13447 .IP d. 4
13448 .IX Item "d."
13449 The return buffer of \f(CW\*(C`Perl_langinfo\*(C'\fR and \f(CW\*(C`Perl_langinfo8\*(C'\fR is per\-thread so
13450 it also is never overwritten by a call to these functions from another thread;
13451 unlike the function they replace.
13452 .IP e. 4
13453 .IX Item "e."
13454 But most importantly, they work on systems that don\*(Aqt have \f(CW\*(C`nl_langinfo\*(C'\fR, such
13455 as Windows, hence making your code more portable. Of the fifty\-some possible
13456 items specified by the POSIX 2008 standard,
13457 <https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/langinfo.h.html>,
13458 only one is completely unimplemented, though on non\-Windows platforms, another
13459 significant one is not fully implemented). They use various techniques to
13460 recover the other items, including calling \f(CW\*(C`\fR\f(CBlocaleconv\fR\f(CW\|(3)\*(C'\fR, and
13461 \&\f(CW\*(C`\fR\f(CBstrftime\fR\f(CW\|(3)\*(C'\fR, both of which are specified in C89, so should be always be
13462 available. Later \f(CWstrftime()\fR versions have additional capabilities.
13463 If an item is not available on your system, this returns either the value
13464 associated with the C locale, or simply \f(CW""\fR, whichever is more appropriate.
13465 .Sp
13466 It is important to note that, when called with an item that is recovered by
13467 using \f(CW\*(C`localeconv\*(C'\fR, the buffer from any previous explicit call to
13468 \&\f(CW\*(C`\fR\f(CBlocaleconv\fR\f(CW\|(3)\*(C'\fR will be overwritten. But you shouldn\*(Aqt be using
13469 \&\f(CW\*(C`localeconv\*(C'\fR anyway because it is is very much not thread\-safe, and suffers
13470 from the same problems outlined in item \*(Aqb.\*(Aq above for the fields it returns
13471 that are controlled by the LC_NUMERIC locale category. Instead, avoid all of
13472 those problems by calling "Perl_localeconv", which is thread\-safe; or by
13473 using the methods given in perlcall to call
13474 \&\f(CWPOSIX::localeconv()\fR, which is also thread\-safe.
13475 .RE
13476 .RS 4
13477 .Sp
13478 The details for those items which may deviate from what this emulation returns
13479 and what a native \f(CWnl_langinfo()\fR would return are specified in
13480 I18N::Langinfo.
13481 .Sp
13482 .Vb 5
13483 \& SV * sv_langinfo ( const nl_item item)
13484 \& SV * Perl_sv_langinfo (pTHX_ const nl_item item)
13485 \& const char * Perl_langinfo ( const nl_item item)
13486 \& const char * Perl_langinfo8( const nl_item item,
13487 \& utf8ness_t *utf8ness)
13488 .Ve
13489 .RE
13490 .RS 4
13491 .RE
13492 .ie n .IP """switch_to_global_locale""" 4
13493 .el .IP \f(CWswitch_to_global_locale\fR 4
13494 .IX Xref "switch_to_global_locale"
13495 .IX Item "switch_to_global_locale"
13496 This function copies the locale state of the calling thread into the program\*(Aqs
13497 global locale, and converts the thread to use that global locale.
13498 .Sp
13499 It is intended so that Perl can safely be used with C libraries that access the
13500 global locale and which can\*(Aqt be converted to not access it. Effectively, this
13501 means libraries that call \f(CW\*(C`\fR\f(CBsetlocale\fR\f(CW\|(3)\*(C'\fR on non\-Windows systems. (For
13502 portability, it is a good idea to use it on Windows as well.)
13503 .Sp
13504 A downside of using it is that it disables the services that Perl provides to
13505 hide locale gotchas from your code. The service you most likely will miss
13506 regards the radix character (decimal point) in floating point numbers. Code
13507 executed after this function is called can no longer just assume that this
13508 character is correct for the current circumstances.
13509 .Sp
13510 To return to Perl control, and restart the gotcha prevention services, call
13511 \&\f(CW"sync_locale"\fR. Behavior is undefined for any pure Perl code that executes
13512 while the switch is in effect.
13513 .Sp
13514 The global locale and the per\-thread locales are independent. As long as just
13515 one thread converts to the global locale, everything works smoothly. But if
13516 more than one does, they can easily interfere with each other, and races are
13517 likely. On Windows systems prior to Visual Studio 15 (at which point Microsoft
13518 fixed a bug), races can occur (even if only one thread has been converted to
13519 the global locale), but only if you use the following operations:
13520 .RS 4
13521 .IP POSIX::localeconv 4
13522 .IX Item "POSIX::localeconv"
13523 .PD 0
13524 .ie n .IP "I18N::Langinfo, items ""CRNCYSTR"" and ""THOUSEP""" 4
13525 .el .IP "I18N::Langinfo, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4
13526 .IX Item "I18N::Langinfo, items CRNCYSTR and THOUSEP"
13527 .ie n .IP """sv_langinfo"" in perlapi, items ""CRNCYSTR"" and ""THOUSEP""" 4
13528 .el .IP """sv_langinfo"" in perlapi, items \f(CWCRNCYSTR\fR and \f(CWTHOUSEP\fR" 4
13529 .IX Item """sv_langinfo"" in perlapi, items CRNCYSTR and THOUSEP"
13530 .PD
13531 .RE
13532 .RS 4
13533 .Sp
13534 The first item is not fixable (except by upgrading to a later Visual Studio
13535 release), but it would be possible to work around the latter two items by
13536 having Perl change its algorithm for calculating these to use Windows API
13537 functions (likely \f(CW\*(C`GetNumberFormat\*(C'\fR and \f(CW\*(C`GetCurrencyFormat\*(C'\fR); patches
13538 welcome.
13539 .Sp
13540 XS code should never call plain \f(CW\*(C`setlocale\*(C'\fR, but should instead be converted
13541 to either call \f(CW\*(C`Perl_setlocale\*(C'\fR (which is a drop\-in
13542 for the system \f(CW\*(C`setlocale\*(C'\fR) or use the methods given in perlcall to call
13543 \&\f(CW\*(C`POSIX::setlocale\*(C'\fR. Either one will transparently properly
13544 handle all cases of single\- vs multi\-thread, POSIX 2008\-supported or not.
13545 .Sp
13546 .Vb 2
13547 \& void switch_to_global_locale()
13548 \& void Perl_switch_to_global_locale(pTHX)
13549 .Ve
13550 .RE
13551 .RS 4
13552 .RE
13553 .ie n .IP """sync_locale""" 4
13554 .el .IP \f(CWsync_locale\fR 4
13555 .IX Xref "sync_locale"
13556 .IX Item "sync_locale"
13557 This function copies the state of the program global locale into the calling
13558 thread, and converts that thread to using per\-thread locales, if it wasn\*(Aqt
13559 already, and the platform supports them. The LC_NUMERIC locale is toggled into
13560 the standard state (using the C locale\*(Aqs conventions), if not within the
13561 lexical scope of \f(CW\*(C`use\ locale\*(C'\fR.
13562 .Sp
13563 Perl will now consider itself to have control of the locale.
13564 .Sp
13565 Since unthreaded perls have only a global locale, this function is a no\-op
13566 without threads.
13567 .Sp
13568 This function is intended for use with C libraries that do locale manipulation.
13569 It allows Perl to accommodate the use of them. Call this function before
13570 transferring back to Perl space so that it knows what state the C code has left
13571 things in.
13572 .Sp
13573 XS code should not manipulate the locale on its own. Instead,
13574 \&\f(CW\*(C`Perl_setlocale\*(C'\fR can be used at any time to query or
13575 change the locale (though changing the locale is antisocial and dangerous on
13576 multi\-threaded systems that don\*(Aqt have multi\-thread safe locale operations.
13577 (See "Multi\-threaded operation" in perllocale).
13578 .Sp
13579 Using the libc \f(CW\*(C`\fR\f(CBsetlocale\fR\f(CW\|(3)\*(C'\fR function should be avoided. Nevertheless,
13580 certain non\-Perl libraries called from XS, do call it, and their behavior may
13581 not be able to be changed. This function, along with
13582 \&\f(CW"switch_to_global_locale"\fR, can be used to get seamless behavior in these
13583 circumstances, as long as only one thread is involved.
13584 .Sp
13585 If the library has an option to turn off its locale manipulation, doing that is
13586 preferable to using this mechanism. \f(CW\*(C`Gtk\*(C'\fR is such a library.
13587 .Sp
13588 The return value is a boolean: TRUE if the global locale at the time of call
13589 was in effect for the caller; and FALSE if a per\-thread locale was in effect.
13590 .RS 4
13591 .Sp
13592 .Vb 2
13593 \& bool sync_locale()
13594 \& bool Perl_sync_locale(pTHX)
13595 .Ve
13596 .RE
13597 .RS 4
13598 .RE
13599 .ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED""" 4
13600 .el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED\fR 4
13601 .IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED"
13602 .IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED"
13603 This macro invokes the supplied statement or block within the context
13604 of a "STORE_LC_NUMERIC_SET_TO_NEEDED" .. "RESTORE_LC_NUMERIC" pair
13605 if required, so eg:
13606 .Sp
13607 .Vb 3
13608 \& WITH_LC_NUMERIC_SET_TO_NEEDED(
13609 \& SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis)
13610 \& );
13611 .Ve
13612 .Sp
13613 is equivalent to:
13614 .Sp
13615 .Vb 10
13616 \& {
13617 \&#ifdef USE_LOCALE_NUMERIC
13618 \& DECLARATION_FOR_LC_NUMERIC_MANIPULATION;
13619 \& STORE_LC_NUMERIC_SET_TO_NEEDED();
13620 \&#endif
13621 \& SNPRINTF_G(fv, ebuf, sizeof(ebuf), precis);
13622 \&#ifdef USE_LOCALE_NUMERIC
13623 \& RESTORE_LC_NUMERIC();
13624 \&#endif
13625 \& }
13626 .Ve
13627 .RS 4
13628 .Sp
13629 .Vb 1
13630 \& void WITH_LC_NUMERIC_SET_TO_NEEDED(block)
13631 .Ve
13632 .RE
13633 .RS 4
13634 .RE
13635 .ie n .IP """WITH_LC_NUMERIC_SET_TO_NEEDED_IN""" 4
13636 .el .IP \f(CWWITH_LC_NUMERIC_SET_TO_NEEDED_IN\fR 4
13637 .IX Xref "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
13638 .IX Item "WITH_LC_NUMERIC_SET_TO_NEEDED_IN"
13639 Same as "WITH_LC_NUMERIC_SET_TO_NEEDED" with in_lc_numeric provided
13640 as the precalculated value of \f(CWIN_LC(LC_NUMERIC)\fR. It is the caller\*(Aqs
13641 responsibility to ensure that the status of \f(CW\*(C`PL_compiling\*(C'\fR and \f(CW\*(C`PL_hints\*(C'\fR
13642 cannot have changed since the precalculation.
13643 .RS 4
13644 .Sp
13645 .Vb 1
13646 \& void WITH_LC_NUMERIC_SET_TO_NEEDED_IN(bool in_lc_numeric, block)
13647 .Ve
13648 .RE
13649 .RS 4
13650 .RE
13651 .SH Magic
13652 .IX Xref "MAGIC"
13653 .IX Header "Magic"
13654 "Magic" is special data attached to SV structures in order to give them
13655 "magical" properties. When any Perl code tries to read from, or assign to,
13656 an SV marked as magical, it calls the \*(Aqget\*(Aq or \*(Aqset\*(Aq function associated
13657 with that SV\*(Aqs magic. A get is called prior to reading an SV, in order to
13658 give it a chance to update its internal value (get on $. writes the line
13659 number of the last read filehandle into the SV\*(Aqs IV slot), while
13660 set is called after an SV has been written to, in order to allow it to make
13661 use of its changed value (set on $/ copies the SV\*(Aqs new value to the
13662 PL_rs global variable).
13663 .PP
13664 Magic is implemented as a linked list of MAGIC structures attached to the
13665 SV. Each MAGIC struct holds the type of the magic, a pointer to an array
13666 of functions that implement the \fBget()\fR, \fBset()\fR, \fBlength()\fR etc functions,
13667 plus space for some flags and pointers. For example, a tied variable has
13668 a MAGIC structure that contains a pointer to the object associated with the
13669 tie.
13670 .ie n .IP """mg_clear""" 4
13671 .el .IP \f(CWmg_clear\fR 4
13672 .IX Xref "mg_clear"
13673 .IX Item "mg_clear"
13674 Clear something magical that the SV represents. See \f(CW"sv_magic"\fR.
13675 .RS 4
13676 .Sp
13677 .Vb 2
13678 \& int mg_clear( SV *sv)
13679 \& int Perl_mg_clear(pTHX_ SV *sv)
13680 .Ve
13681 .RE
13682 .RS 4
13683 .RE
13684 .ie n .IP """mg_copy""" 4
13685 .el .IP \f(CWmg_copy\fR 4
13686 .IX Xref "mg_copy"
13687 .IX Item "mg_copy"
13688 Copies the magic from one SV to another. See \f(CW"sv_magic"\fR.
13689 .RS 4
13690 .Sp
13691 .Vb 4
13692 \& int mg_copy( SV *sv, SV *nsv, const char *key,
13693 \& I32 klen)
13694 \& int Perl_mg_copy(pTHX_ SV *sv, SV *nsv, const char *key,
13695 \& I32 klen)
13696 .Ve
13697 .RE
13698 .RS 4
13699 .RE
13700 .ie n .IP """mg_find""" 4
13701 .el .IP \f(CWmg_find\fR 4
13702 .IX Xref "mg_find"
13703 .IX Item "mg_find"
13704 Finds the magic pointer for \f(CW\*(C`type\*(C'\fR matching the SV. See \f(CW"sv_magic"\fR.
13705 .RS 4
13706 .Sp
13707 .Vb 2
13708 \& MAGIC * mg_find(const SV *sv, int type)
13709 \& MAGIC * Perl_mg_find(const SV *sv, int type)
13710 .Ve
13711 .RE
13712 .RS 4
13713 .RE
13714 .ie n .IP """mg_findext""" 4
13715 .el .IP \f(CWmg_findext\fR 4
13716 .IX Xref "mg_findext"
13717 .IX Item "mg_findext"
13718 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
13719 \&\f(CW"sv_magicext"\fR.
13720 .RS 4
13721 .Sp
13722 .Vb 4
13723 \& MAGIC * mg_findext(const SV *sv, int type,
13724 \& const MGVTBL *vtbl)
13725 \& MAGIC * Perl_mg_findext(const SV *sv, int type,
13726 \& const MGVTBL *vtbl)
13727 .Ve
13728 .RE
13729 .RS 4
13730 .RE
13731 .ie n .IP """mg_free""" 4
13732 .el .IP \f(CWmg_free\fR 4
13733 .IX Xref "mg_free"
13734 .IX Item "mg_free"
13735 Free any magic storage used by the SV. See \f(CW"sv_magic"\fR.
13736 .RS 4
13737 .Sp
13738 .Vb 2
13739 \& int mg_free( SV *sv)
13740 \& int Perl_mg_free(pTHX_ SV *sv)
13741 .Ve
13742 .RE
13743 .RS 4
13744 .RE
13745 .ie n .IP """mg_free_type""" 4
13746 .el .IP \f(CWmg_free_type\fR 4
13747 .IX Xref "mg_free_type"
13748 .IX Item "mg_free_type"
13749 Remove any magic of type \f(CW\*(C`how\*(C'\fR from the SV \f(CW\*(C`sv\*(C'\fR. See "sv_magic".
13750 .RS 4
13751 .Sp
13752 .Vb 2
13753 \& void mg_free_type( SV *sv, int how)
13754 \& void Perl_mg_free_type(pTHX_ SV *sv, int how)
13755 .Ve
13756 .RE
13757 .RS 4
13758 .RE
13759 .ie n .IP """mg_freeext""" 4
13760 .el .IP \f(CWmg_freeext\fR 4
13761 .IX Xref "mg_freeext"
13762 .IX Item "mg_freeext"
13763 Remove any magic of type \f(CW\*(C`how\*(C'\fR using virtual table \f(CW\*(C`vtbl\*(C'\fR from the
13764 SV \f(CW\*(C`sv\*(C'\fR. See "sv_magic".
13765 .Sp
13766 \&\f(CW\*(C`mg_freeext(sv, how, NULL)\*(C'\fR is equivalent to \f(CW\*(C`mg_free_type(sv, how)\*(C'\fR.
13767 .RS 4
13768 .Sp
13769 .Vb 2
13770 \& void mg_freeext( SV *sv, int how, const MGVTBL *vtbl)
13771 \& void Perl_mg_freeext(pTHX_ SV *sv, int how, const MGVTBL *vtbl)
13772 .Ve
13773 .RE
13774 .RS 4
13775 .RE
13776 .ie n .IP """mg_get""" 4
13777 .el .IP \f(CWmg_get\fR 4
13778 .IX Xref "mg_get"
13779 .IX Item "mg_get"
13780 Do magic before a value is retrieved from the SV. The type of SV must
13781 be >= \f(CW\*(C`SVt_PVMG\*(C'\fR. See \f(CW"sv_magic"\fR.
13782 .RS 4
13783 .Sp
13784 .Vb 2
13785 \& int mg_get( SV *sv)
13786 \& int Perl_mg_get(pTHX_ SV *sv)
13787 .Ve
13788 .RE
13789 .RS 4
13790 .RE
13791 .ie n .IP """mg_magical""" 4
13792 .el .IP \f(CWmg_magical\fR 4
13793 .IX Xref "mg_magical"
13794 .IX Item "mg_magical"
13795 Turns on the magical status of an SV. See \f(CW"sv_magic"\fR.
13796 .RS 4
13797 .Sp
13798 .Vb 2
13799 \& void mg_magical(SV *sv)
13800 \& void Perl_mg_magical(SV *sv)
13801 .Ve
13802 .RE
13803 .RS 4
13804 .RE
13805 .ie n .IP """mg_set""" 4
13806 .el .IP \f(CWmg_set\fR 4
13807 .IX Xref "mg_set"
13808 .IX Item "mg_set"
13809 Do magic after a value is assigned to the SV. See \f(CW"sv_magic"\fR.
13810 .RS 4
13811 .Sp
13812 .Vb 2
13813 \& int mg_set( SV *sv)
13814 \& int Perl_mg_set(pTHX_ SV *sv)
13815 .Ve
13816 .RE
13817 .RS 4
13818 .RE
13819 .ie n .IP """MGf_COPY""" 4
13820 .el .IP \f(CWMGf_COPY\fR 4
13821 .IX Item "MGf_COPY"
13822 .PD 0
13823 .ie n .IP """MGf_DUP""" 4
13824 .el .IP \f(CWMGf_DUP\fR 4
13825 .IX Item "MGf_DUP"
13826 .ie n .IP """MGf_LOCAL""" 4
13827 .el .IP \f(CWMGf_LOCAL\fR 4
13828 .IX Item "MGf_LOCAL"
13829 .ie n .IP """MGVTBL""" 4
13830 .el .IP \f(CWMGVTBL\fR 4
13831 .IX Item "MGVTBL"
13832 .ie n .IP """PERL_MAGIC_arylen""" 4
13833 .el .IP \f(CWPERL_MAGIC_arylen\fR 4
13834 .IX Item "PERL_MAGIC_arylen"
13835 .ie n .IP """PERL_MAGIC_arylen_p""" 4
13836 .el .IP \f(CWPERL_MAGIC_arylen_p\fR 4
13837 .IX Item "PERL_MAGIC_arylen_p"
13838 .ie n .IP """PERL_MAGIC_backref""" 4
13839 .el .IP \f(CWPERL_MAGIC_backref\fR 4
13840 .IX Item "PERL_MAGIC_backref"
13841 .ie n .IP """PERL_MAGIC_bm""" 4
13842 .el .IP \f(CWPERL_MAGIC_bm\fR 4
13843 .IX Item "PERL_MAGIC_bm"
13844 .ie n .IP """PERL_MAGIC_checkcall""" 4
13845 .el .IP \f(CWPERL_MAGIC_checkcall\fR 4
13846 .IX Item "PERL_MAGIC_checkcall"
13847 .ie n .IP """PERL_MAGIC_collxfrm""" 4
13848 .el .IP \f(CWPERL_MAGIC_collxfrm\fR 4
13849 .IX Item "PERL_MAGIC_collxfrm"
13850 .ie n .IP """PERL_MAGIC_dbfile""" 4
13851 .el .IP \f(CWPERL_MAGIC_dbfile\fR 4
13852 .IX Item "PERL_MAGIC_dbfile"
13853 .ie n .IP """PERL_MAGIC_dbline""" 4
13854 .el .IP \f(CWPERL_MAGIC_dbline\fR 4
13855 .IX Item "PERL_MAGIC_dbline"
13856 .ie n .IP """PERL_MAGIC_debugvar""" 4
13857 .el .IP \f(CWPERL_MAGIC_debugvar\fR 4
13858 .IX Item "PERL_MAGIC_debugvar"
13859 .ie n .IP """PERL_MAGIC_defelem""" 4
13860 .el .IP \f(CWPERL_MAGIC_defelem\fR 4
13861 .IX Item "PERL_MAGIC_defelem"
13862 .ie n .IP """PERL_MAGIC_destruct""" 4
13863 .el .IP \f(CWPERL_MAGIC_destruct\fR 4
13864 .IX Item "PERL_MAGIC_destruct"
13865 .ie n .IP """PERL_MAGIC_env""" 4
13866 .el .IP \f(CWPERL_MAGIC_env\fR 4
13867 .IX Item "PERL_MAGIC_env"
13868 .ie n .IP """PERL_MAGIC_envelem""" 4
13869 .el .IP \f(CWPERL_MAGIC_envelem\fR 4
13870 .IX Item "PERL_MAGIC_envelem"
13871 .ie n .IP """PERL_MAGIC_ext""" 4
13872 .el .IP \f(CWPERL_MAGIC_ext\fR 4
13873 .IX Item "PERL_MAGIC_ext"
13874 .ie n .IP """PERL_MAGIC_extvalue""" 4
13875 .el .IP \f(CWPERL_MAGIC_extvalue\fR 4
13876 .IX Item "PERL_MAGIC_extvalue"
13877 .ie n .IP """PERL_MAGIC_fm""" 4
13878 .el .IP \f(CWPERL_MAGIC_fm\fR 4
13879 .IX Item "PERL_MAGIC_fm"
13880 .ie n .IP """PERL_MAGIC_hints""" 4
13881 .el .IP \f(CWPERL_MAGIC_hints\fR 4
13882 .IX Item "PERL_MAGIC_hints"
13883 .ie n .IP """PERL_MAGIC_hintselem""" 4
13884 .el .IP \f(CWPERL_MAGIC_hintselem\fR 4
13885 .IX Item "PERL_MAGIC_hintselem"
13886 .ie n .IP """PERL_MAGIC_hook""" 4
13887 .el .IP \f(CWPERL_MAGIC_hook\fR 4
13888 .IX Item "PERL_MAGIC_hook"
13889 .ie n .IP """PERL_MAGIC_hookelem""" 4
13890 .el .IP \f(CWPERL_MAGIC_hookelem\fR 4
13891 .IX Item "PERL_MAGIC_hookelem"
13892 .ie n .IP """PERL_MAGIC_isa""" 4
13893 .el .IP \f(CWPERL_MAGIC_isa\fR 4
13894 .IX Item "PERL_MAGIC_isa"
13895 .ie n .IP """PERL_MAGIC_isaelem""" 4
13896 .el .IP \f(CWPERL_MAGIC_isaelem\fR 4
13897 .IX Item "PERL_MAGIC_isaelem"
13898 .ie n .IP """PERL_MAGIC_lvref""" 4
13899 .el .IP \f(CWPERL_MAGIC_lvref\fR 4
13900 .IX Item "PERL_MAGIC_lvref"
13901 .ie n .IP """PERL_MAGIC_nkeys""" 4
13902 .el .IP \f(CWPERL_MAGIC_nkeys\fR 4
13903 .IX Item "PERL_MAGIC_nkeys"
13904 .ie n .IP """PERL_MAGIC_nonelem""" 4
13905 .el .IP \f(CWPERL_MAGIC_nonelem\fR 4
13906 .IX Item "PERL_MAGIC_nonelem"
13907 .ie n .IP """PERL_MAGIC_overload_table""" 4
13908 .el .IP \f(CWPERL_MAGIC_overload_table\fR 4
13909 .IX Item "PERL_MAGIC_overload_table"
13910 .ie n .IP """PERL_MAGIC_pos""" 4
13911 .el .IP \f(CWPERL_MAGIC_pos\fR 4
13912 .IX Item "PERL_MAGIC_pos"
13913 .ie n .IP """PERL_MAGIC_qr""" 4
13914 .el .IP \f(CWPERL_MAGIC_qr\fR 4
13915 .IX Item "PERL_MAGIC_qr"
13916 .ie n .IP """PERL_MAGIC_regdata""" 4
13917 .el .IP \f(CWPERL_MAGIC_regdata\fR 4
13918 .IX Item "PERL_MAGIC_regdata"
13919 .ie n .IP """PERL_MAGIC_regdatum""" 4
13920 .el .IP \f(CWPERL_MAGIC_regdatum\fR 4
13921 .IX Item "PERL_MAGIC_regdatum"
13922 .ie n .IP """PERL_MAGIC_regex_global""" 4
13923 .el .IP \f(CWPERL_MAGIC_regex_global\fR 4
13924 .IX Item "PERL_MAGIC_regex_global"
13925 .ie n .IP """PERL_MAGIC_rhash""" 4
13926 .el .IP \f(CWPERL_MAGIC_rhash\fR 4
13927 .IX Item "PERL_MAGIC_rhash"
13928 .ie n .IP """PERL_MAGIC_shared""" 4
13929 .el .IP \f(CWPERL_MAGIC_shared\fR 4
13930 .IX Item "PERL_MAGIC_shared"
13931 .ie n .IP """PERL_MAGIC_shared_scalar""" 4
13932 .el .IP \f(CWPERL_MAGIC_shared_scalar\fR 4
13933 .IX Item "PERL_MAGIC_shared_scalar"
13934 .ie n .IP """PERL_MAGIC_sig""" 4
13935 .el .IP \f(CWPERL_MAGIC_sig\fR 4
13936 .IX Item "PERL_MAGIC_sig"
13937 .ie n .IP """PERL_MAGIC_sigelem""" 4
13938 .el .IP \f(CWPERL_MAGIC_sigelem\fR 4
13939 .IX Item "PERL_MAGIC_sigelem"
13940 .ie n .IP """PERL_MAGIC_substr""" 4
13941 .el .IP \f(CWPERL_MAGIC_substr\fR 4
13942 .IX Item "PERL_MAGIC_substr"
13943 .ie n .IP """PERL_MAGIC_sv""" 4
13944 .el .IP \f(CWPERL_MAGIC_sv\fR 4
13945 .IX Item "PERL_MAGIC_sv"
13946 .ie n .IP """PERL_MAGIC_symtab""" 4
13947 .el .IP \f(CWPERL_MAGIC_symtab\fR 4
13948 .IX Item "PERL_MAGIC_symtab"
13949 .ie n .IP """PERL_MAGIC_taint""" 4
13950 .el .IP \f(CWPERL_MAGIC_taint\fR 4
13951 .IX Item "PERL_MAGIC_taint"
13952 .ie n .IP """PERL_MAGIC_tied""" 4
13953 .el .IP \f(CWPERL_MAGIC_tied\fR 4
13954 .IX Item "PERL_MAGIC_tied"
13955 .ie n .IP """PERL_MAGIC_tiedelem""" 4
13956 .el .IP \f(CWPERL_MAGIC_tiedelem\fR 4
13957 .IX Item "PERL_MAGIC_tiedelem"
13958 .ie n .IP """PERL_MAGIC_tiedscalar""" 4
13959 .el .IP \f(CWPERL_MAGIC_tiedscalar\fR 4
13960 .IX Item "PERL_MAGIC_tiedscalar"
13961 .ie n .IP """PERL_MAGIC_utf8""" 4
13962 .el .IP \f(CWPERL_MAGIC_utf8\fR 4
13963 .IX Item "PERL_MAGIC_utf8"
13964 .ie n .IP """PERL_MAGIC_uvar""" 4
13965 .el .IP \f(CWPERL_MAGIC_uvar\fR 4
13966 .IX Item "PERL_MAGIC_uvar"
13967 .ie n .IP """PERL_MAGIC_uvar_elem""" 4
13968 .el .IP \f(CWPERL_MAGIC_uvar_elem\fR 4
13969 .IX Item "PERL_MAGIC_uvar_elem"
13970 .ie n .IP """PERL_MAGIC_vec""" 4
13971 .el .IP \f(CWPERL_MAGIC_vec\fR 4
13972 .IX Item "PERL_MAGIC_vec"
13973 .ie n .IP """PERL_MAGIC_vstring""" 4
13974 .el .IP \f(CWPERL_MAGIC_vstring\fR 4
13975 .IX Item "PERL_MAGIC_vstring"
13976 .PD
13977 Described in perlguts.
13978 .ie n .IP """SvTIED_obj""" 4
13979 .el .IP \f(CWSvTIED_obj\fR 4
13980 .IX Item "SvTIED_obj"
13981 Described in perlinterp.
13982 .RS 4
13983 .Sp
13984 .Vb 1
13985 \& SvTIED_obj(SV *sv, MAGIC *mg)
13986 .Ve
13987 .RE
13988 .RS 4
13989 .RE
13990 .SH "Memory Management"
13991 .IX Header "Memory Management"
13992 .ie n .IP """dump_mstats""" 4
13993 .el .IP \f(CWdump_mstats\fR 4
13994 .IX Xref "dump_mstats"
13995 .IX Item "dump_mstats"
13996 When enabled by compiling with \f(CW\*(C`\-DDEBUGGING_MSTATS\*(C'\fR, print out statistics
13997 about malloc as two lines of numbers, one showing the length of the free list
13998 for each size category, the second showing the number of mallocs\ \-\ frees for
13999 each size category.
14000 .Sp
14001 \&\f(CW\*(C`s\*(C'\fR, if not NULL, is used as a phrase to include in the output, such as
14002 "after\ compilation".
14003 .RS 4
14004 .Sp
14005 .Vb 2
14006 \& void dump_mstats( const char *s)
14007 \& void Perl_dump_mstats(pTHX_ const char *s)
14008 .Ve
14009 .RE
14010 .RS 4
14011 .RE
14012 .ie n .IP """HAS_MALLOC_GOOD_SIZE""" 4
14013 .el .IP \f(CWHAS_MALLOC_GOOD_SIZE\fR 4
14014 .IX Xref "HAS_MALLOC_GOOD_SIZE"
14015 .IX Item "HAS_MALLOC_GOOD_SIZE"
14016 This symbol, if defined, indicates that the \f(CW\*(C`malloc_good_size\*(C'\fR
14017 routine is available for use.
14018 .ie n .IP """HAS_MALLOC_SIZE""" 4
14019 .el .IP \f(CWHAS_MALLOC_SIZE\fR 4
14020 .IX Xref "HAS_MALLOC_SIZE"
14021 .IX Item "HAS_MALLOC_SIZE"
14022 This symbol, if defined, indicates that the \f(CW\*(C`malloc_size\*(C'\fR
14023 routine is available for use.
14024 .ie n .IP """HASATTRIBUTE_MALLOC""" 4
14025 .el .IP \f(CWHASATTRIBUTE_MALLOC\fR 4
14026 .IX Xref "HASATTRIBUTE_MALLOC"
14027 .IX Item "HASATTRIBUTE_MALLOC"
14028 Can we handle \f(CW\*(C`GCC\*(C'\fR attribute for malloc\-style functions.
14029 .ie n .IP """I_MALLOCMALLOC""" 4
14030 .el .IP \f(CWI_MALLOCMALLOC\fR 4
14031 .IX Xref "I_MALLOCMALLOC"
14032 .IX Item "I_MALLOCMALLOC"
14033 This symbol, if defined, indicates to the C program that it should
14034 include \fImalloc/malloc.h\fR.
14035 .RS 4
14036 .Sp
14037 .Vb 3
14038 \& #ifdef I_MALLOCMALLOC
14039 \& #include <mallocmalloc.h>
14040 \& #endif
14041 .Ve
14042 .RE
14043 .RS 4
14044 .RE
14045 .ie n .IP """MYMALLOC""" 4
14046 .el .IP \f(CWMYMALLOC\fR 4
14047 .IX Xref "MYMALLOC"
14048 .IX Item "MYMALLOC"
14049 This symbol, if defined, indicates that we\*(Aqre using our own malloc.
14050 .ie n .IP """Newx""" 4
14051 .el .IP \f(CWNewx\fR 4
14052 .IX Item "Newx"
14053 .PD 0
14054 .ie n .IP """safemalloc""" 4
14055 .el .IP \f(CWsafemalloc\fR 4
14056 .IX Xref "Newx safemalloc"
14057 .IX Item "safemalloc"
14058 .PD
14059 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`malloc\*(C'\fR function.
14060 .Sp
14061 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
14062 .Sp
14063 In 5.9.3, \fBNewx()\fR and friends replace the older \fBNew()\fR API, and drops
14064 the first parameter, \fIx\fR, a debug aid which allowed callers to identify
14065 themselves. This aid has been superseded by a new build option,
14066 PERL_MEM_LOG (see "PERL_MEM_LOG" in perlhacktips). The older API is still
14067 there for use in XS modules supporting older perls.
14068 .RS 4
14069 .Sp
14070 .Vb 2
14071 \& void Newx (void* ptr, int nitems, type)
14072 \& void* safemalloc(size_t size)
14073 .Ve
14074 .RE
14075 .RS 4
14076 .RE
14077 .ie n .IP """Newxc""" 4
14078 .el .IP \f(CWNewxc\fR 4
14079 .IX Xref "Newxc"
14080 .IX Item "Newxc"
14081 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`malloc\*(C'\fR function, with
14082 cast. See also \f(CW"Newx"\fR.
14083 .Sp
14084 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
14085 .RS 4
14086 .Sp
14087 .Vb 1
14088 \& void Newxc(void* ptr, int nitems, type, cast)
14089 .Ve
14090 .RE
14091 .RS 4
14092 .RE
14093 .ie n .IP """Newxz""" 4
14094 .el .IP \f(CWNewxz\fR 4
14095 .IX Item "Newxz"
14096 .PD 0
14097 .ie n .IP """safecalloc""" 4
14098 .el .IP \f(CWsafecalloc\fR 4
14099 .IX Xref "Newxz safecalloc"
14100 .IX Item "safecalloc"
14101 .PD
14102 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`calloc\*(C'\fR function. The allocated
14103 memory is zeroed with \f(CW\*(C`memzero\*(C'\fR. See also \f(CW"Newx"\fR.
14104 .Sp
14105 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
14106 .RS 4
14107 .Sp
14108 .Vb 2
14109 \& void Newxz (void* ptr, int nitems, type)
14110 \& void* safecalloc(size_t nitems, size_t item_size)
14111 .Ve
14112 .RE
14113 .RS 4
14114 .RE
14115 .ie n .IP """PERL_MALLOC_WRAP""" 4
14116 .el .IP \f(CWPERL_MALLOC_WRAP\fR 4
14117 .IX Xref "PERL_MALLOC_WRAP"
14118 .IX Item "PERL_MALLOC_WRAP"
14119 This symbol, if defined, indicates that we\*(Aqd like malloc wrap checks.
14120 .ie n .IP """Renew""" 4
14121 .el .IP \f(CWRenew\fR 4
14122 .IX Item "Renew"
14123 .PD 0
14124 .ie n .IP """saferealloc""" 4
14125 .el .IP \f(CWsaferealloc\fR 4
14126 .IX Xref "Renew saferealloc"
14127 .IX Item "saferealloc"
14128 .PD
14129 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`realloc\*(C'\fR function.
14130 .Sp
14131 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
14132 .RS 4
14133 .Sp
14134 .Vb 2
14135 \& void Renew (void* ptr, int nitems, type)
14136 \& void* saferealloc(void *ptr, size_t size)
14137 .Ve
14138 .RE
14139 .RS 4
14140 .RE
14141 .ie n .IP """Renewc""" 4
14142 .el .IP \f(CWRenewc\fR 4
14143 .IX Xref "Renewc"
14144 .IX Item "Renewc"
14145 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`realloc\*(C'\fR function, with
14146 cast.
14147 .Sp
14148 Memory obtained by this should \fBONLY\fR be freed with "Safefree".
14149 .RS 4
14150 .Sp
14151 .Vb 1
14152 \& void Renewc(void* ptr, int nitems, type, cast)
14153 .Ve
14154 .RE
14155 .RS 4
14156 .RE
14157 .ie n .IP """safecalloc*""" 4
14158 .el .IP \f(CWsafecalloc*\fR 4
14159 .IX Item "safecalloc*"
14160 Described under \f(CW"Newxz"\fR
14161 .ie n .IP """Safefree""" 4
14162 .el .IP \f(CWSafefree\fR 4
14163 .IX Xref "Safefree"
14164 .IX Item "Safefree"
14165 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`free\*(C'\fR function.
14166 .Sp
14167 This should \fBONLY\fR be used on memory obtained using "Newx" and friends.
14168 .RS 4
14169 .Sp
14170 .Vb 1
14171 \& void Safefree(void* ptr)
14172 .Ve
14173 .RE
14174 .RS 4
14175 .RE
14176 .ie n .IP """safemalloc*""" 4
14177 .el .IP \f(CWsafemalloc*\fR 4
14178 .IX Item "safemalloc*"
14179 Described under \f(CW"Newx"\fR
14180 .ie n .IP """saferealloc*""" 4
14181 .el .IP \f(CWsaferealloc*\fR 4
14182 .IX Item "saferealloc*"
14183 Described under \f(CW"Renew"\fR
14184 .ie n .IP """safesyscalloc""" 4
14185 .el .IP \f(CWsafesyscalloc\fR 4
14186 .IX Xref "safesyscalloc"
14187 .IX Item "safesyscalloc"
14188 Safe version of system\*(Aqs \fBcalloc()\fR
14189 .RS 4
14190 .Sp
14191 .Vb 2
14192 \& Malloc_t safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
14193 \& Malloc_t Perl_safesyscalloc(MEM_SIZE elements, MEM_SIZE size)
14194 .Ve
14195 .RE
14196 .RS 4
14197 .RE
14198 .ie n .IP """safesysfree""" 4
14199 .el .IP \f(CWsafesysfree\fR 4
14200 .IX Xref "safesysfree"
14201 .IX Item "safesysfree"
14202 Safe version of system\*(Aqs \fBfree()\fR
14203 .RS 4
14204 .Sp
14205 .Vb 2
14206 \& Free_t safesysfree(Malloc_t where)
14207 \& Free_t Perl_safesysfree(Malloc_t where)
14208 .Ve
14209 .RE
14210 .RS 4
14211 .RE
14212 .ie n .IP """safesysmalloc""" 4
14213 .el .IP \f(CWsafesysmalloc\fR 4
14214 .IX Xref "safesysmalloc"
14215 .IX Item "safesysmalloc"
14216 Paranoid version of system\*(Aqs \fBmalloc()\fR
14217 .RS 4
14218 .Sp
14219 .Vb 2
14220 \& Malloc_t safesysmalloc(MEM_SIZE nbytes)
14221 \& Malloc_t Perl_safesysmalloc(MEM_SIZE nbytes)
14222 .Ve
14223 .RE
14224 .RS 4
14225 .RE
14226 .ie n .IP """safesysrealloc""" 4
14227 .el .IP \f(CWsafesysrealloc\fR 4
14228 .IX Xref "safesysrealloc"
14229 .IX Item "safesysrealloc"
14230 Paranoid version of system\*(Aqs \fBrealloc()\fR
14231 .RS 4
14232 .Sp
14233 .Vb 2
14234 \& Malloc_t safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
14235 \& Malloc_t Perl_safesysrealloc(Malloc_t where, MEM_SIZE nbytes)
14236 .Ve
14237 .RE
14238 .RS 4
14239 .RE
14240 .SH MRO
14241 .IX Header "MRO"
14242 These functions are related to the method resolution order of perl classes
14243 Also see perlmroapi.
14244 .ie n .IP """HvMROMETA""" 4
14245 .el .IP \f(CWHvMROMETA\fR 4
14246 .IX Item "HvMROMETA"
14247 Described in perlmroapi.
14248 .RS 4
14249 .Sp
14250 .Vb 1
14251 \& struct mro_meta * HvMROMETA(HV *hv)
14252 .Ve
14253 .RE
14254 .RS 4
14255 .RE
14256 .ie n .IP """mro_get_from_name""" 4
14257 .el .IP \f(CWmro_get_from_name\fR 4
14258 .IX Xref "mro_get_from_name"
14259 .IX Item "mro_get_from_name"
14260 Returns the previously registered mro with the given \f(CW\*(C`name\*(C'\fR, or NULL if not
14261 registered. See "\f(CW\*(C`mro_register\*(C'\fR".
14262 .RS 4
14263 .Sp
14264 .Vb 1
14265 \& const struct mro_alg * Perl_mro_get_from_name(pTHX_ SV *name)
14266 .Ve
14267 .RE
14268 .RS 4
14269 .RE
14270 .ie n .IP """mro_get_linear_isa""" 4
14271 .el .IP \f(CWmro_get_linear_isa\fR 4
14272 .IX Xref "mro_get_linear_isa"
14273 .IX Item "mro_get_linear_isa"
14274 Returns the mro linearisation for the given stash. By default, this
14275 will be whatever \f(CW\*(C`mro_get_linear_isa_dfs\*(C'\fR returns unless some
14276 other MRO is in effect for the stash. The return value is a
14277 read\-only AV* whose values are string SVs giving class names.
14278 .Sp
14279 You are responsible for \f(CWSvREFCNT_inc()\fR on the
14280 return value if you plan to store it anywhere
14281 semi\-permanently (otherwise it might be deleted
14282 out from under you the next time the cache is
14283 invalidated).
14284 .RS 4
14285 .Sp
14286 .Vb 2
14287 \& AV * mro_get_linear_isa( HV *stash)
14288 \& AV * Perl_mro_get_linear_isa(pTHX_ HV *stash)
14289 .Ve
14290 .RE
14291 .RS 4
14292 .RE
14293 .ie n .IP """MRO_GET_PRIVATE_DATA""" 4
14294 .el .IP \f(CWMRO_GET_PRIVATE_DATA\fR 4
14295 .IX Item "MRO_GET_PRIVATE_DATA"
14296 Described in perlmroapi.
14297 .RS 4
14298 .Sp
14299 .Vb 2
14300 \& SV* MRO_GET_PRIVATE_DATA(struct mro_meta *const smeta,
14301 \& const struct mro_alg *const which)
14302 .Ve
14303 .RE
14304 .RS 4
14305 .RE
14306 .ie n .IP """mro_method_changed_in""" 4
14307 .el .IP \f(CWmro_method_changed_in\fR 4
14308 .IX Xref "mro_method_changed_in"
14309 .IX Item "mro_method_changed_in"
14310 Invalidates method caching on any child classes
14311 of the given stash, so that they might notice
14312 the changes in this one.
14313 .Sp
14314 Ideally, all instances of \f(CW\*(C`PL_sub_generation++\*(C'\fR in
14315 perl source outside of \fImro.c\fR should be
14316 replaced by calls to this.
14317 .Sp
14318 Perl automatically handles most of the common
14319 ways a method might be redefined. However, there
14320 are a few ways you could change a method in a stash
14321 without the cache code noticing, in which case you
14322 need to call this method afterwards:
14323 .Sp
14324 1) Directly manipulating the stash HV entries from
14325 XS code.
14326 .Sp
14327 2) Assigning a reference to a readonly scalar
14328 constant into a stash entry in order to create
14329 a constant subroutine (like \fIconstant.pm\fR
14330 does).
14331 .Sp
14332 This same method is available from pure perl
14333 via, \f(CWmro::method_changed_in(classname)\fR.
14334 .RS 4
14335 .Sp
14336 .Vb 2
14337 \& void mro_method_changed_in( HV *stash)
14338 \& void Perl_mro_method_changed_in(pTHX_ HV *stash)
14339 .Ve
14340 .RE
14341 .RS 4
14342 .RE
14343 .ie n .IP """mro_register""" 4
14344 .el .IP \f(CWmro_register\fR 4
14345 .IX Xref "mro_register"
14346 .IX Item "mro_register"
14347 Registers a custom mro plugin. See perlmroapi for details on this and other
14348 mro functions.
14349 .RS 4
14350 .Sp
14351 .Vb 1
14352 \& void Perl_mro_register(pTHX_ const struct mro_alg *mro)
14353 .Ve
14354 .RE
14355 .RS 4
14356 .RE
14357 .ie n .IP """mro_set_mro""" 4
14358 .el .IP \f(CWmro_set_mro\fR 4
14359 .IX Xref "mro_set_mro"
14360 .IX Item "mro_set_mro"
14361 Set \f(CW\*(C`meta\*(C'\fR to the value contained in the registered mro plugin whose name is
14362 \&\f(CW\*(C`name\*(C'\fR.
14363 .Sp
14364 Croaks if \f(CW\*(C`name\*(C'\fR hasn\*(Aqt been registered
14365 .RS 4
14366 .Sp
14367 .Vb 2
14368 \& void Perl_mro_set_mro(pTHX_ struct mro_meta * const meta,
14369 \& SV * const name)
14370 .Ve
14371 .RE
14372 .RS 4
14373 .RE
14374 .ie n .IP """mro_set_private_data""" 4
14375 .el .IP \f(CWmro_set_private_data\fR 4
14376 .IX Item "mro_set_private_data"
14377 Described in perlmroapi.
14378 .RS 4
14379 .Sp
14380 .Vb 4
14381 \& SV * Perl_mro_set_private_data(pTHX_
14382 \& struct mro_meta * const smeta,
14383 \& const struct mro_alg * const which,
14384 \& SV * const data)
14385 .Ve
14386 .RE
14387 .RS 4
14388 .RE
14389 .SH "Multicall Functions"
14390 .IX Header "Multicall Functions"
14391 .ie n .IP """dMULTICALL""" 4
14392 .el .IP \f(CWdMULTICALL\fR 4
14393 .IX Xref "dMULTICALL"
14394 .IX Item "dMULTICALL"
14395 Declare local variables for a multicall. See "LIGHTWEIGHT CALLBACKS" in perlcall.
14396 .RS 4
14397 .Sp
14398 .Vb 1
14399 \& dMULTICALL;
14400 .Ve
14401 .RE
14402 .RS 4
14403 .RE
14404 .ie n .IP """MULTICALL""" 4
14405 .el .IP \f(CWMULTICALL\fR 4
14406 .IX Xref "MULTICALL"
14407 .IX Item "MULTICALL"
14408 Make a lightweight callback. See "LIGHTWEIGHT CALLBACKS" in perlcall.
14409 .RS 4
14410 .Sp
14411 .Vb 1
14412 \& MULTICALL;
14413 .Ve
14414 .RE
14415 .RS 4
14416 .RE
14417 .ie n .IP """POP_MULTICALL""" 4
14418 .el .IP \f(CWPOP_MULTICALL\fR 4
14419 .IX Xref "POP_MULTICALL"
14420 .IX Item "POP_MULTICALL"
14421 Closing bracket for a lightweight callback.
14422 See "LIGHTWEIGHT CALLBACKS" in perlcall.
14423 .RS 4
14424 .Sp
14425 .Vb 1
14426 \& POP_MULTICALL;
14427 .Ve
14428 .RE
14429 .RS 4
14430 .RE
14431 .ie n .IP """PUSH_MULTICALL""" 4
14432 .el .IP \f(CWPUSH_MULTICALL\fR 4
14433 .IX Xref "PUSH_MULTICALL"
14434 .IX Item "PUSH_MULTICALL"
14435 Opening bracket for a lightweight callback.
14436 See "LIGHTWEIGHT CALLBACKS" in perlcall.
14437 .RS 4
14438 .Sp
14439 .Vb 1
14440 \& PUSH_MULTICALL(CV* the_cv);
14441 .Ve
14442 .RE
14443 .RS 4
14444 .RE
14445 .SH "Numeric Functions"
14446 .IX Xref "IS_NUMBER_GREATER_THAN_UV_MAX IS_NUMBER_IN_UV IS_NUMBER_INFINITY IS_NUMBER_NAN IS_NUMBER_NEG IS_NUMBER_NOT_INT IS_NUMBER_TRAILING PERL_SCAN_ALLOW_UNDERSCORES PERL_SCAN_DISALLOW_PREFIX PERL_SCAN_GREATER_THAN_UV_MAX PERL_SCAN_SILENT_ILLDIGIT PERL_SCAN_TRAILING"
14447 .IX Header "Numeric Functions"
14448 .ie n .IP """Atof*""" 4
14449 .el .IP \f(CWAtof*\fR 4
14450 .IX Item "Atof*"
14451 Described under \f(CW"my_atof"\fR
14452 .ie n .IP """grok_atoUV""" 4
14453 .el .IP \f(CWgrok_atoUV\fR 4
14454 .IX Xref "grok_atoUV"
14455 .IX Item "grok_atoUV"
14456 parse a string, looking for a decimal unsigned integer.
14457 .Sp
14458 On entry, \f(CW\*(C`pv\*(C'\fR points to the beginning of the string;
14459 \&\f(CW\*(C`valptr\*(C'\fR points to a UV that will receive the converted value, if found;
14460 \&\f(CW\*(C`endptr\*(C'\fR is either NULL or points to a variable that points to one byte
14461 beyond the point in \f(CW\*(C`pv\*(C'\fR that this routine should examine.
14462 If \f(CW\*(C`endptr\*(C'\fR is NULL, \f(CW\*(C`pv\*(C'\fR is assumed to be NUL\-terminated.
14463 .Sp
14464 Returns FALSE if \f(CW\*(C`pv\*(C'\fR doesn\*(Aqt represent a valid unsigned integer value (with
14465 no leading zeros). Otherwise it returns TRUE, and sets \f(CW*valptr\fR to that
14466 value.
14467 .Sp
14468 If you constrain the portion of \f(CW\*(C`pv\*(C'\fR that is looked at by this function (by
14469 passing a non\-NULL \f(CW\*(C`endptr\*(C'\fR), and if the initial bytes of that portion form a
14470 valid value, it will return TRUE, setting \f(CW*endptr\fR to the byte following the
14471 final digit of the value. But if there is no constraint at what\*(Aqs looked at,
14472 all of \f(CW\*(C`pv\*(C'\fR must be valid in order for TRUE to be returned. \f(CW*endptr\fR is
14473 unchanged from its value on input if FALSE is returned;
14474 .Sp
14475 The only characters this accepts are the decimal digits \*(Aq0\*(Aq..\*(Aq9\*(Aq.
14476 .Sp
14477 As opposed to \fBatoi\fR\|(3) or \fBstrtol\fR\|(3), \f(CW\*(C`grok_atoUV\*(C'\fR does NOT allow optional
14478 leading whitespace, nor negative inputs. If such features are required, the
14479 calling code needs to explicitly implement those.
14480 .Sp
14481 Note that this function returns FALSE for inputs that would overflow a UV,
14482 or have leading zeros. Thus a single \f(CW0\fR is accepted, but not \f(CW00\fR nor
14483 \&\f(CW01\fR, \f(CW002\fR, \fIetc\fR.
14484 .Sp
14485 Background: \f(CW\*(C`atoi\*(C'\fR has severe problems with illegal inputs, it cannot be
14486 used for incremental parsing, and therefore should be avoided
14487 \&\f(CW\*(C`atoi\*(C'\fR and \f(CW\*(C`strtol\*(C'\fR are also affected by locale settings, which can also be
14488 seen as a bug (global state controlled by user environment).
14489 .RS 4
14490 .Sp
14491 .Vb 4
14492 \& bool grok_atoUV(const char *pv, UV *valptr,
14493 \& const char **endptr)
14494 \& bool Perl_grok_atoUV(const char *pv, UV *valptr,
14495 \& const char **endptr)
14496 .Ve
14497 .RE
14498 .RS 4
14499 .RE
14500 .ie n .IP """grok_bin""" 4
14501 .el .IP \f(CWgrok_bin\fR 4
14502 .IX Xref "grok_bin"
14503 .IX Item "grok_bin"
14504 converts a string representing a binary number to numeric form.
14505 .Sp
14506 On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
14507 conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The
14508 scan stops at the end of the string, or at just before the first invalid
14509 character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
14510 encountering an invalid character (except NUL) will also trigger a warning. On
14511 return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
14512 gives output flags.
14513 .Sp
14514 If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
14515 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
14516 returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
14517 and writes an approximation of the correct value into \f(CW*result\fR (which is an
14518 NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
14519 .Sp
14520 The binary number may optionally be prefixed with \f(CW"0b"\fR or \f(CW"b"\fR unless
14521 \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry.
14522 .Sp
14523 If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
14524 digits may be separated from each other by a single underscore; also a single
14525 leading underscore is accepted.
14526 .RS 4
14527 .Sp
14528 .Vb 4
14529 \& UV grok_bin( const char *start, STRLEN *len_p,
14530 \& I32 *flags, NV *result)
14531 \& UV Perl_grok_bin(pTHX_ const char *start, STRLEN *len_p,
14532 \& I32 *flags, NV *result)
14533 .Ve
14534 .RE
14535 .RS 4
14536 .RE
14537 .ie n .IP """grok_hex""" 4
14538 .el .IP \f(CWgrok_hex\fR 4
14539 .IX Xref "grok_hex"
14540 .IX Item "grok_hex"
14541 converts a string representing a hex number to numeric form.
14542 .Sp
14543 On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
14544 conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The
14545 scan stops at the end of the string, or at just before the first invalid
14546 character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
14547 encountering an invalid character (except NUL) will also trigger a warning. On
14548 return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
14549 gives output flags.
14550 .Sp
14551 If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
14552 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
14553 returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
14554 and writes an approximation of the correct value into \f(CW*result\fR (which is an
14555 NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
14556 .Sp
14557 The hex number may optionally be prefixed with \f(CW"0x"\fR or \f(CW"x"\fR unless
14558 \&\f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR is set in \f(CW*flags\fR on entry.
14559 .Sp
14560 If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
14561 digits may be separated from each other by a single underscore; also a single
14562 leading underscore is accepted.
14563 .RS 4
14564 .Sp
14565 .Vb 4
14566 \& UV grok_hex( const char *start, STRLEN *len_p,
14567 \& I32 *flags, NV *result)
14568 \& UV Perl_grok_hex(pTHX_ const char *start, STRLEN *len_p,
14569 \& I32 *flags, NV *result)
14570 .Ve
14571 .RE
14572 .RS 4
14573 .RE
14574 .ie n .IP """grok_infnan""" 4
14575 .el .IP \f(CWgrok_infnan\fR 4
14576 .IX Xref "grok_infnan"
14577 .IX Item "grok_infnan"
14578 Helper for \f(CWgrok_number()\fR, accepts various ways of spelling "infinity"
14579 or "not a number", and returns one of the following flag combinations:
14580 .Sp
14581 .Vb 5
14582 \& IS_NUMBER_INFINITY
14583 \& IS_NUMBER_NAN
14584 \& IS_NUMBER_INFINITY | IS_NUMBER_NEG
14585 \& IS_NUMBER_NAN | IS_NUMBER_NEG
14586 \& 0
14587 .Ve
14588 .Sp
14589 possibly |\-ed with \f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR.
14590 .Sp
14591 If an infinity or a not\-a\-number is recognized, \f(CW*sp\fR will point to
14592 one byte past the end of the recognized string. If the recognition fails,
14593 zero is returned, and \f(CW*sp\fR will not move.
14594 .RS 4
14595 .Sp
14596 .Vb 2
14597 \& int grok_infnan( const char **sp, const char *send)
14598 \& int Perl_grok_infnan(pTHX_ const char **sp, const char *send)
14599 .Ve
14600 .RE
14601 .RS 4
14602 .RE
14603 .ie n .IP """grok_number""" 4
14604 .el .IP \f(CWgrok_number\fR 4
14605 .IX Item "grok_number"
14606 .PD 0
14607 .ie n .IP """grok_number_flags""" 4
14608 .el .IP \f(CWgrok_number_flags\fR 4
14609 .IX Xref "grok_number grok_number_flags"
14610 .IX Item "grok_number_flags"
14611 .PD
14612 Look for a number in the \f(CW\*(C`len\*(C'\fR bytes starting at \f(CW\*(C`pv\*(C'\fR. If one isn\*(Aqt found,
14613 return 0; otherwise return its type (and optionally its value). In
14614 \&\f(CW\*(C`grok_number\*(C'\fR all \f(CW\*(C`len\*(C'\fR bytes must be either leading \f(CW"isSPACE"\fR
14615 characters or part of the number. The same is true in \f(CW\*(C`grok_number_flags\*(C'\fR
14616 unless \f(CW\*(C`flags\*(C'\fR contains the \f(CW\*(C`PERL_SCAN_TRAILING\*(C'\fR bit, which allows for
14617 trailing non\-numeric text. (This is the only difference between the two
14618 functions.)
14619 .Sp
14620 The returned type is the ORing of various bits (#defined in \fIperl.h\fR) as
14621 described below:
14622 .Sp
14623 If the number is negative, the returned type will include the \f(CW\*(C`IS_NUMBER_NEG\*(C'\fR
14624 bit.
14625 .Sp
14626 If the absolute value of the integral portion of the found number fits in a UV,
14627 the returned type will include the \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR bit. If it won\*(Aqt fit,
14628 instead the \f(CW\*(C`IS_NUMBER_GREATER_THAN_UV_MAX\*(C'\fR bit will be included.
14629 .Sp
14630 If the found number is not an integer, the returned type will include
14631 the \f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR bit. This happens either if the number
14632 is expressed in exponential \f(CW\*(C`e\*(C'\fR notation, or if it includes a decimal
14633 point (radix) character. If exponential notation is used, then neither
14634 IS_NUMBER_IN_UV nor IS_NUMBER_GREATER_THAN_UV_MAX bits are set.
14635 Otherwise, the integer part of the number is used to determine the
14636 \&\f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR and \f(CW\*(C`IS_NUMBER_GREATER_THAN_UV_MAX\*(C'\fR bits.
14637 .Sp
14638 If the found number is a string indicating it is infinity, the
14639 \&\f(CW\*(C`IS_NUMBER_INFINITY\*(C'\fR and \f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR bits are included in the
14640 returned type.
14641 .Sp
14642 If the found number is a string indicating it is not a number, the
14643 \&\f(CW\*(C`IS_NUMBER_NAN\*(C'\fR and \f(CW\*(C`IS_NUMBER_NOT_INT\*(C'\fR bits are included in the
14644 returned type.
14645 .Sp
14646 You can get the number\*(Aqs absolute integral value returned to you by calling
14647 these functions with a non\-NULL \f(CW\*(C`valuep\*(C'\fR argument. If the returned type
14648 includes the \f(CW\*(C`IS_NUMBER_IN_UV\*(C'\fR bit, \f(CW*valuep\fR will be set to the correct
14649 value. Otherwise, it could well have been zapped with garbage.
14650 .Sp
14651 In \f(CW\*(C`grok_number_flags\*(C'\fR when \f(CW\*(C`flags\*(C'\fR contains the \f(CW\*(C`PERL_SCAN_TRAILING\*(C'\fR
14652 bit, and trailing non\-numeric text was found, the returned type will include
14653 the \f(CW\*(C`IS_NUMBER_TRAILING\*(C'\fR bit.
14654 .RS 4
14655 .Sp
14656 .Vb 8
14657 \& int grok_number ( const char *pv, STRLEN len,
14658 \& UV *valuep)
14659 \& int Perl_grok_number (pTHX_ const char *pv, STRLEN len,
14660 \& UV *valuep)
14661 \& int grok_number_flags( const char *pv, STRLEN len,
14662 \& UV *valuep, U32 flags)
14663 \& int Perl_grok_number_flags(pTHX_ const char *pv, STRLEN len,
14664 \& UV *valuep, U32 flags)
14665 .Ve
14666 .RE
14667 .RS 4
14668 .RE
14669 .ie n .IP """grok_numeric_radix""" 4
14670 .el .IP \f(CWgrok_numeric_radix\fR 4
14671 .IX Item "grok_numeric_radix"
14672 .PD 0
14673 .ie n .IP """GROK_NUMERIC_RADIX""" 4
14674 .el .IP \f(CWGROK_NUMERIC_RADIX\fR 4
14675 .IX Xref "GROK_NUMERIC_RADIX grok_numeric_radix"
14676 .IX Item "GROK_NUMERIC_RADIX"
14677 .PD
14678 These are identical.
14679 .Sp
14680 Scan and skip for a numeric decimal separator (radix).
14681 .RS 4
14682 .Sp
14683 .Vb 6
14684 \& bool grok_numeric_radix( const char **sp,
14685 \& const char *send)
14686 \& bool Perl_grok_numeric_radix(pTHX_ const char **sp,
14687 \& const char *send)
14688 \& bool GROK_NUMERIC_RADIX( const char **sp,
14689 \& const char *send)
14690 .Ve
14691 .RE
14692 .RS 4
14693 .RE
14694 .ie n .IP """grok_oct""" 4
14695 .el .IP \f(CWgrok_oct\fR 4
14696 .IX Xref "grok_oct"
14697 .IX Item "grok_oct"
14698 converts a string representing an octal number to numeric form.
14699 .Sp
14700 On entry \f(CW\*(C`start\*(C'\fR and \f(CW*len_p\fR give the string to scan, \f(CW*flags\fR gives
14701 conversion flags, and \f(CW\*(C`result\*(C'\fR should be \f(CW\*(C`NULL\*(C'\fR or a pointer to an NV. The
14702 scan stops at the end of the string, or at just before the first invalid
14703 character. Unless \f(CW\*(C`PERL_SCAN_SILENT_ILLDIGIT\*(C'\fR is set in \f(CW*flags\fR,
14704 encountering an invalid character (except NUL) will also trigger a warning. On
14705 return \f(CW*len_p\fR is set to the length of the scanned string, and \f(CW*flags\fR
14706 gives output flags.
14707 .Sp
14708 If the value is <= \f(CW\*(C`UV_MAX\*(C'\fR it is returned as a UV, the output flags are clear,
14709 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
14710 returns \f(CW\*(C`UV_MAX\*(C'\fR, sets \f(CW\*(C`PERL_SCAN_GREATER_THAN_UV_MAX\*(C'\fR in the output flags,
14711 and writes an approximation of the correct value into \f(CW*result\fR (which is an
14712 NV; or the approximation is discarded if \f(CW\*(C`result\*(C'\fR is NULL).
14713 .Sp
14714 If \f(CW\*(C`PERL_SCAN_ALLOW_UNDERSCORES\*(C'\fR is set in \f(CW*flags\fR then any or all pairs of
14715 digits may be separated from each other by a single underscore; also a single
14716 leading underscore is accepted.
14717 .Sp
14718 The \f(CW\*(C`PERL_SCAN_DISALLOW_PREFIX\*(C'\fR flag is always treated as being set for
14719 this function.
14720 .RS 4
14721 .Sp
14722 .Vb 4
14723 \& UV grok_oct( const char *start, STRLEN *len_p,
14724 \& I32 *flags, NV *result)
14725 \& UV Perl_grok_oct(pTHX_ const char *start, STRLEN *len_p,
14726 \& I32 *flags, NV *result)
14727 .Ve
14728 .RE
14729 .RS 4
14730 .RE
14731 .ie n .IP """isinfnan""" 4
14732 .el .IP \f(CWisinfnan\fR 4
14733 .IX Xref "isinfnan"
14734 .IX Item "isinfnan"
14735 \&\f(CWPerl_isinfnan()\fR is a utility function that returns true if the NV
14736 argument is either an infinity or a \f(CW\*(C`NaN\*(C'\fR, false otherwise. To test
14737 in more detail, use \f(CWPerl_isinf()\fR and \f(CWPerl_isnan()\fR.
14738 .Sp
14739 This is also the logical inverse of \fBPerl_isfinite()\fR.
14740 .RS 4
14741 .Sp
14742 .Vb 2
14743 \& bool isinfnan(NV nv)
14744 \& bool Perl_isinfnan(NV nv)
14745 .Ve
14746 .RE
14747 .RS 4
14748 .RE
14749 .ie n .IP """my_atof""" 4
14750 .el .IP \f(CWmy_atof\fR 4
14751 .IX Item "my_atof"
14752 .PD 0
14753 .ie n .IP """Atof""" 4
14754 .el .IP \f(CWAtof\fR 4
14755 .IX Xref "Atof my_atof"
14756 .IX Item "Atof"
14757 .PD
14758 These each are \f(CW\*(C`\fR\f(CBatof\fR\f(CW\|(3)\*(C'\fR, but properly work with Perl locale handling,
14759 accepting a dot radix character always, but also the current locale\*(Aqs radix
14760 character if and only if called from within the lexical scope of a Perl \f(CW\*(C`use
14761 locale\*(C'\fR statement.
14762 .Sp
14763 N.B. \f(CW\*(C`s\*(C'\fR must be NUL terminated.
14764 .RS 4
14765 .Sp
14766 .Vb 3
14767 \& NV my_atof( const char *s)
14768 \& NV Perl_my_atof(pTHX_ const char *s)
14769 \& NV Atof ( const char * const s)
14770 .Ve
14771 .RE
14772 .RS 4
14773 .RE
14774 .ie n .IP """my_strtod""" 4
14775 .el .IP \f(CWmy_strtod\fR 4
14776 .IX Item "my_strtod"
14777 .PD 0
14778 .ie n .IP """Strtod""" 4
14779 .el .IP \f(CWStrtod\fR 4
14780 .IX Xref "my_strtod Strtod"
14781 .IX Item "Strtod"
14782 .PD
14783 These are identical.
14784 .Sp
14785 They act like the libc \f(CW\*(C`\fR\f(CBstrtod\fR\f(CW\|(3)\*(C'\fR function, with three exceptions:
14786 .RS 4
14787 .IP 1. 4
14788 Their return value is an NV. Plain \f(CW\*(C`strod\*(C'\fR returns a double precision value.
14789 .IP 2. 4
14790 Plain \f(CW\*(C`strtod\*(C'\fR always is expecting the radix character (or string) to be the
14791 one specified by the underlying locale the program is executing in. This is
14792 almost universally a dot (U+002E) or a comma (U+002C).
14793 .Sp
14794 In contrast, these expect the radix to be a dot, except when called from within
14795 the scope of \f(CW\*(C`use\ locale\*(C'\fR, in which case they act like plain \f(CW\*(C`strtod\*(C'\fR,
14796 expecting the radix to be that specified by the current locale.
14797 .IP 3. 4
14798 These are are available even on platforms that lack plain \fBstrtod()\fR.
14799 .RE
14800 .RS 4
14801 .Sp
14802 .Vb 3
14803 \& NV my_strtod(const char * const s, char **e)
14804 \& NV Perl_my_strtod(const char * const s, char **e)
14805 \& NV Strtod (const char * const s, char **e)
14806 .Ve
14807 .RE
14808 .RS 4
14809 .RE
14810 .ie n .IP """PERL_ABS""" 4
14811 .el .IP \f(CWPERL_ABS\fR 4
14812 .IX Xref "PERL_ABS"
14813 .IX Item "PERL_ABS"
14814 Typeless \f(CW\*(C`abs\*(C'\fR or \f(CW\*(C`fabs\*(C'\fR, \fIetc\fR. (The usage below indicates it is for
14815 integers, but it works for any type.) Use instead of these, since the C
14816 library ones force their argument to be what it is expecting, potentially
14817 leading to disaster. But also beware that this evaluates its argument twice,
14818 so no \f(CW\*(C`x++\*(C'\fR.
14819 .RS 4
14820 .Sp
14821 .Vb 1
14822 \& int PERL_ABS(int x)
14823 .Ve
14824 .RE
14825 .RS 4
14826 .RE
14827 .ie n .IP """Perl_acos""" 4
14828 .el .IP \f(CWPerl_acos\fR 4
14829 .IX Item "Perl_acos"
14830 .PD 0
14831 .ie n .IP """Perl_asin""" 4
14832 .el .IP \f(CWPerl_asin\fR 4
14833 .IX Item "Perl_asin"
14834 .ie n .IP """Perl_atan""" 4
14835 .el .IP \f(CWPerl_atan\fR 4
14836 .IX Item "Perl_atan"
14837 .ie n .IP """Perl_atan2""" 4
14838 .el .IP \f(CWPerl_atan2\fR 4
14839 .IX Item "Perl_atan2"
14840 .ie n .IP """Perl_ceil""" 4
14841 .el .IP \f(CWPerl_ceil\fR 4
14842 .IX Item "Perl_ceil"
14843 .ie n .IP """Perl_cos""" 4
14844 .el .IP \f(CWPerl_cos\fR 4
14845 .IX Item "Perl_cos"
14846 .ie n .IP """Perl_cosh""" 4
14847 .el .IP \f(CWPerl_cosh\fR 4
14848 .IX Item "Perl_cosh"
14849 .ie n .IP """Perl_exp""" 4
14850 .el .IP \f(CWPerl_exp\fR 4
14851 .IX Item "Perl_exp"
14852 .ie n .IP """Perl_floor""" 4
14853 .el .IP \f(CWPerl_floor\fR 4
14854 .IX Item "Perl_floor"
14855 .ie n .IP """Perl_fmod""" 4
14856 .el .IP \f(CWPerl_fmod\fR 4
14857 .IX Item "Perl_fmod"
14858 .ie n .IP """Perl_frexp""" 4
14859 .el .IP \f(CWPerl_frexp\fR 4
14860 .IX Item "Perl_frexp"
14861 .ie n .IP """Perl_isfinite""" 4
14862 .el .IP \f(CWPerl_isfinite\fR 4
14863 .IX Item "Perl_isfinite"
14864 .ie n .IP """Perl_isinf""" 4
14865 .el .IP \f(CWPerl_isinf\fR 4
14866 .IX Item "Perl_isinf"
14867 .ie n .IP """Perl_isnan""" 4
14868 .el .IP \f(CWPerl_isnan\fR 4
14869 .IX Item "Perl_isnan"
14870 .ie n .IP """Perl_ldexp""" 4
14871 .el .IP \f(CWPerl_ldexp\fR 4
14872 .IX Item "Perl_ldexp"
14873 .ie n .IP """Perl_log""" 4
14874 .el .IP \f(CWPerl_log\fR 4
14875 .IX Item "Perl_log"
14876 .ie n .IP """Perl_log10""" 4
14877 .el .IP \f(CWPerl_log10\fR 4
14878 .IX Item "Perl_log10"
14879 .ie n .IP """Perl_modf""" 4
14880 .el .IP \f(CWPerl_modf\fR 4
14881 .IX Item "Perl_modf"
14882 .ie n .IP """Perl_pow""" 4
14883 .el .IP \f(CWPerl_pow\fR 4
14884 .IX Item "Perl_pow"
14885 .ie n .IP """Perl_sin""" 4
14886 .el .IP \f(CWPerl_sin\fR 4
14887 .IX Item "Perl_sin"
14888 .ie n .IP """Perl_sinh""" 4
14889 .el .IP \f(CWPerl_sinh\fR 4
14890 .IX Item "Perl_sinh"
14891 .ie n .IP """Perl_sqrt""" 4
14892 .el .IP \f(CWPerl_sqrt\fR 4
14893 .IX Item "Perl_sqrt"
14894 .ie n .IP """Perl_tan""" 4
14895 .el .IP \f(CWPerl_tan\fR 4
14896 .IX Item "Perl_tan"
14897 .ie n .IP """Perl_tanh""" 4
14898 .el .IP \f(CWPerl_tanh\fR 4
14899 .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"
14900 .IX Item "Perl_tanh"
14901 .PD
14902 These perform the corresponding mathematical operation on the operand(s), using
14903 the libc function designed for the task that has just enough precision for an
14904 NV on this platform. If no such function with sufficient precision exists,
14905 the highest precision one available is used.
14906 .RS 4
14907 .Sp
14908 .Vb 10
14909 \& NV Perl_acos (NV x)
14910 \& NV Perl_asin (NV x)
14911 \& NV Perl_atan (NV x)
14912 \& NV Perl_atan2 (NV x, NV y)
14913 \& NV Perl_ceil (NV x)
14914 \& NV Perl_cos (NV x)
14915 \& NV Perl_cosh (NV x)
14916 \& NV Perl_exp (NV x)
14917 \& NV Perl_floor (NV x)
14918 \& NV Perl_fmod (NV x, NV y)
14919 \& NV Perl_frexp (NV x, int *exp)
14920 \& IV Perl_isfinite(NV x)
14921 \& IV Perl_isinf (NV x)
14922 \& IV Perl_isnan (NV x)
14923 \& NV Perl_ldexp (NV x, int exp)
14924 \& NV Perl_log (NV x)
14925 \& NV Perl_log10 (NV x)
14926 \& NV Perl_modf (NV x, NV *iptr)
14927 \& NV Perl_pow (NV x, NV y)
14928 \& NV Perl_sin (NV x)
14929 \& NV Perl_sinh (NV x)
14930 \& NV Perl_sqrt (NV x)
14931 \& NV Perl_tan (NV x)
14932 \& NV Perl_tanh (NV x)
14933 .Ve
14934 .RE
14935 .RS 4
14936 .RE
14937 .ie n .IP """Perl_signbit""" 4
14938 .el .IP \f(CWPerl_signbit\fR 4
14939 .IX Xref "Perl_signbit"
14940 .IX Item "Perl_signbit"
14941 NOTE: \f(CW\*(C`Perl_signbit\*(C'\fR is \fBexperimental\fR and may change or be
14942 removed without notice.
14943 .Sp
14944 Return a non\-zero integer if the sign bit on an NV is set, and 0 if
14945 it is not.
14946 .Sp
14947 If \fIConfigure\fR detects this system has a \f(CWsignbit()\fR that will work with
14948 our NVs, then we just use it via the \f(CW\*(C`#define\*(C'\fR in \fIperl.h\fR. Otherwise,
14949 fall back on this implementation. The main use of this function
14950 is catching \f(CW\-0.0\fR.
14951 .Sp
14952 \&\f(CW\*(C`Configure\*(C'\fR notes: This function is called \f(CW\*(AqPerl_signbit\*(Aq\fR instead of a
14953 plain \f(CW\*(Aqsignbit\*(Aq\fR because it is easy to imagine a system having a \f(CWsignbit()\fR
14954 function or macro that doesn\*(Aqt happen to work with our particular choice
14955 of NVs. We shouldn\*(Aqt just re\-\f(CW\*(C`#define\*(C'\fR \f(CW\*(C`signbit\*(C'\fR as \f(CW\*(C`Perl_signbit\*(C'\fR and expect
14956 the standard system headers to be happy. Also, this is a no\-context
14957 function (no \f(CW\*(C`pTHX_\*(C'\fR) because \f(CWPerl_signbit()\fR is usually re\-\f(CW\*(C`#defined\*(C'\fR in
14958 \&\fIperl.h\fR as a simple macro call to the system\*(Aqs \f(CWsignbit()\fR.
14959 Users should just always call \f(CWPerl_signbit()\fR.
14960 .RS 4
14961 .Sp
14962 .Vb 1
14963 \& int Perl_signbit(NV f)
14964 .Ve
14965 .RE
14966 .RS 4
14967 .RE
14968 .ie n .IP """Perl_sin*""" 4
14969 .el .IP \f(CWPerl_sin*\fR 4
14970 .IX Item "Perl_sin*"
14971 .PD 0
14972 .ie n .IP """Perl_sinh*""" 4
14973 .el .IP \f(CWPerl_sinh*\fR 4
14974 .IX Item "Perl_sinh*"
14975 .ie n .IP """Perl_sqrt*""" 4
14976 .el .IP \f(CWPerl_sqrt*\fR 4
14977 .IX Item "Perl_sqrt*"
14978 .ie n .IP """Perl_tan*""" 4
14979 .el .IP \f(CWPerl_tan*\fR 4
14980 .IX Item "Perl_tan*"
14981 .ie n .IP """Perl_tanh*""" 4
14982 .el .IP \f(CWPerl_tanh*\fR 4
14983 .IX Item "Perl_tanh*"
14984 .PD
14985 Described under \f(CW"Perl_acos"\fR
14986 .ie n .IP """PL_hexdigit""" 4
14987 .el .IP \f(CWPL_hexdigit\fR 4
14988 .IX Xref "PL_hexdigit"
14989 .IX Item "PL_hexdigit"
14990 This array, indexed by an integer, converts that value into the character that
14991 represents it. For example, if the input is 8, the return will be a string
14992 whose first character is \*(Aq8\*(Aq. What is actually returned is a pointer into a
14993 string. All you are interested in is the first character of that string. To
14994 get uppercase letters (for the values 10..15), add 16 to the index. Hence,
14995 \&\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
14996 to an index whose representation is \*(Aq0\*(Aq..\*(Aq9\*(Aq yields the same as not adding 16.
14997 Indices outside the range 0..31 result in (bad) undefined behavior.
14998 .ie n .IP """READ_XDIGIT""" 4
14999 .el .IP \f(CWREAD_XDIGIT\fR 4
15000 .IX Xref "READ_XDIGIT"
15001 .IX Item "READ_XDIGIT"
15002 Returns the value of an ASCII\-range hex digit and advances the string pointer.
15003 Behaviour is only well defined when isXDIGIT(*str) is true.
15004 .RS 4
15005 .Sp
15006 .Vb 1
15007 \& U8 READ_XDIGIT(char str*)
15008 .Ve
15009 .RE
15010 .RS 4
15011 .RE
15012 .ie n .IP """scan_bin""" 4
15013 .el .IP \f(CWscan_bin\fR 4
15014 .IX Xref "scan_bin"
15015 .IX Item "scan_bin"
15016 For backwards compatibility. Use \f(CW\*(C`grok_bin\*(C'\fR instead.
15017 .RS 4
15018 .Sp
15019 .Vb 4
15020 \& NV scan_bin( const char *start, STRLEN len,
15021 \& STRLEN *retlen)
15022 \& NV Perl_scan_bin(pTHX_ const char *start, STRLEN len,
15023 \& STRLEN *retlen)
15024 .Ve
15025 .RE
15026 .RS 4
15027 .RE
15028 .ie n .IP """scan_hex""" 4
15029 .el .IP \f(CWscan_hex\fR 4
15030 .IX Xref "scan_hex"
15031 .IX Item "scan_hex"
15032 For backwards compatibility. Use \f(CW\*(C`grok_hex\*(C'\fR instead.
15033 .RS 4
15034 .Sp
15035 .Vb 4
15036 \& NV scan_hex( const char *start, STRLEN len,
15037 \& STRLEN *retlen)
15038 \& NV Perl_scan_hex(pTHX_ const char *start, STRLEN len,
15039 \& STRLEN *retlen)
15040 .Ve
15041 .RE
15042 .RS 4
15043 .RE
15044 .ie n .IP """scan_oct""" 4
15045 .el .IP \f(CWscan_oct\fR 4
15046 .IX Xref "scan_oct"
15047 .IX Item "scan_oct"
15048 For backwards compatibility. Use \f(CW\*(C`grok_oct\*(C'\fR instead.
15049 .RS 4
15050 .Sp
15051 .Vb 4
15052 \& NV scan_oct( const char *start, STRLEN len,
15053 \& STRLEN *retlen)
15054 \& NV Perl_scan_oct(pTHX_ const char *start, STRLEN len,
15055 \& STRLEN *retlen)
15056 .Ve
15057 .RE
15058 .RS 4
15059 .RE
15060 .ie n .IP """Strtod*""" 4
15061 .el .IP \f(CWStrtod*\fR 4
15062 .IX Item "Strtod*"
15063 Described under \f(CW"my_strtod"\fR
15064 .ie n .IP """Strtol""" 4
15065 .el .IP \f(CWStrtol\fR 4
15066 .IX Xref "Strtol"
15067 .IX Item "Strtol"
15068 Platform and configuration independent \f(CW\*(C`strtol\*(C'\fR. This expands to the
15069 appropriate \f(CW\*(C`strotol\*(C'\fR\-like function based on the platform and \fIConfigure\fR
15070 options>. For example it could expand to \f(CW\*(C`strtoll\*(C'\fR or \f(CW\*(C`strtoq\*(C'\fR instead of
15071 \&\f(CW\*(C`strtol\*(C'\fR.
15072 .RS 4
15073 .Sp
15074 .Vb 1
15075 \& NV Strtol(const char * const s, char ** e, int base)
15076 .Ve
15077 .RE
15078 .RS 4
15079 .RE
15080 .ie n .IP """Strtoul""" 4
15081 .el .IP \f(CWStrtoul\fR 4
15082 .IX Xref "Strtoul"
15083 .IX Item "Strtoul"
15084 Platform and configuration independent \f(CW\*(C`strtoul\*(C'\fR. This expands to the
15085 appropriate \f(CW\*(C`strotoul\*(C'\fR\-like function based on the platform and \fIConfigure\fR
15086 options>. For example it could expand to \f(CW\*(C`strtoull\*(C'\fR or \f(CW\*(C`strtouq\*(C'\fR instead of
15087 \&\f(CW\*(C`strtoul\*(C'\fR.
15088 .RS 4
15089 .Sp
15090 .Vb 1
15091 \& NV Strtoul(const char * const s, char ** e, int base)
15092 .Ve
15093 .RE
15094 .RS 4
15095 .RE
15096 .SH Optrees
15097 .IX Xref "CALL_CHECKER_REQUIRE_GV OPf_KIDS OPpEARLY_CV OPpENTERSUB_AMPER RV2CVOPCV_MARK_EARLY RV2CVOPCV_RETURN_NAME_GV"
15098 .IX Header "Optrees"
15099 .ie n .IP """alloccopstash""" 4
15100 .el .IP \f(CWalloccopstash\fR 4
15101 .IX Xref "alloccopstash"
15102 .IX Item "alloccopstash"
15103 NOTE: \f(CW\*(C`alloccopstash\*(C'\fR is \fBexperimental\fR and may change or be
15104 removed without notice.
15105 .Sp
15106 Available only under threaded builds, this function allocates an entry in
15107 \&\f(CW\*(C`PL_stashpad\*(C'\fR for the stash passed to it.
15108 .RS 4
15109 .Sp
15110 .Vb 2
15111 \& PADOFFSET alloccopstash( HV *hv)
15112 \& PADOFFSET Perl_alloccopstash(pTHX_ HV *hv)
15113 .Ve
15114 .RE
15115 .RS 4
15116 .RE
15117 .ie n .IP """BINOP""" 4
15118 .el .IP \f(CWBINOP\fR 4
15119 .IX Item "BINOP"
15120 Described in perlguts.
15121 .ie n .IP """block_end""" 4
15122 .el .IP \f(CWblock_end\fR 4
15123 .IX Xref "block_end"
15124 .IX Item "block_end"
15125 Handles compile\-time scope exit. \f(CW\*(C`floor\*(C'\fR
15126 is the savestack index returned by
15127 \&\f(CW\*(C`block_start\*(C'\fR, and \f(CW\*(C`seq\*(C'\fR is the body of the block. Returns the block,
15128 possibly modified.
15129 .RS 4
15130 .Sp
15131 .Vb 2
15132 \& OP * block_end( I32 floor, OP *seq)
15133 \& OP * Perl_block_end(pTHX_ I32 floor, OP *seq)
15134 .Ve
15135 .RE
15136 .RS 4
15137 .RE
15138 .ie n .IP """block_start""" 4
15139 .el .IP \f(CWblock_start\fR 4
15140 .IX Xref "block_start"
15141 .IX Item "block_start"
15142 Handles compile\-time scope entry.
15143 Arranges for hints to be restored on block
15144 exit and also handles pad sequence numbers to make lexical variables scope
15145 right. Returns a savestack index for use with \f(CW\*(C`block_end\*(C'\fR.
15146 .RS 4
15147 .Sp
15148 .Vb 2
15149 \& int block_start( int full)
15150 \& int Perl_block_start(pTHX_ int full)
15151 .Ve
15152 .RE
15153 .RS 4
15154 .RE
15155 .ie n .IP """ck_entersub_args_list""" 4
15156 .el .IP \f(CWck_entersub_args_list\fR 4
15157 .IX Xref "ck_entersub_args_list"
15158 .IX Item "ck_entersub_args_list"
15159 Performs the default fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR
15160 op tree. This consists of applying list context to each of the
15161 argument ops. This is the standard treatment used on a call marked
15162 with \f(CW\*(C`&\*(C'\fR, or a method call, or a call through a subroutine reference,
15163 or any other call where the callee can\*(Aqt be identified at compile time,
15164 or a call where the callee has no prototype.
15165 .RS 4
15166 .Sp
15167 .Vb 2
15168 \& OP * ck_entersub_args_list( OP *entersubop)
15169 \& OP * Perl_ck_entersub_args_list(pTHX_ OP *entersubop)
15170 .Ve
15171 .RE
15172 .RS 4
15173 .RE
15174 .ie n .IP """ck_entersub_args_proto""" 4
15175 .el .IP \f(CWck_entersub_args_proto\fR 4
15176 .IX Xref "ck_entersub_args_proto"
15177 .IX Item "ck_entersub_args_proto"
15178 Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree
15179 based on a subroutine prototype. This makes various modifications to
15180 the argument ops, from applying context up to inserting \f(CW\*(C`refgen\*(C'\fR ops,
15181 and checking the number and syntactic types of arguments, as directed by
15182 the prototype. This is the standard treatment used on a subroutine call,
15183 not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time
15184 and has a prototype.
15185 .Sp
15186 \&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call.
15187 It may be a normal defined scalar, of which the string value will be used.
15188 Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
15189 that has been cast to \f(CW\*(C`SV*\*(C'\fR) which has a prototype. The prototype
15190 supplied, in whichever form, does not need to match the actual callee
15191 referenced by the op tree.
15192 .Sp
15193 If the argument ops disagree with the prototype, for example by having
15194 an unacceptable number of arguments, a valid op tree is returned anyway.
15195 The error is reflected in the parser state, normally resulting in a single
15196 exception at the top level of parsing which covers all the compilation
15197 errors that occurred. In the error message, the callee is referred to
15198 by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter.
15199 .RS 4
15200 .Sp
15201 .Vb 4
15202 \& OP * ck_entersub_args_proto( OP *entersubop,
15203 \& GV *namegv, SV *protosv)
15204 \& OP * Perl_ck_entersub_args_proto(pTHX_ OP *entersubop,
15205 \& GV *namegv, SV *protosv)
15206 .Ve
15207 .RE
15208 .RS 4
15209 .RE
15210 .ie n .IP """ck_entersub_args_proto_or_list""" 4
15211 .el .IP \f(CWck_entersub_args_proto_or_list\fR 4
15212 .IX Xref "ck_entersub_args_proto_or_list"
15213 .IX Item "ck_entersub_args_proto_or_list"
15214 Performs the fixup of the arguments part of an \f(CW\*(C`entersub\*(C'\fR op tree either
15215 based on a subroutine prototype or using default list\-context processing.
15216 This is the standard treatment used on a subroutine call, not marked
15217 with \f(CW\*(C`&\*(C'\fR, where the callee can be identified at compile time.
15218 .Sp
15219 \&\f(CW\*(C`protosv\*(C'\fR supplies the subroutine prototype to be applied to the call,
15220 or indicates that there is no prototype. It may be a normal scalar,
15221 in which case if it is defined then the string value will be used
15222 as a prototype, and if it is undefined then there is no prototype.
15223 Alternatively, for convenience, it may be a subroutine object (a \f(CW\*(C`CV*\*(C'\fR
15224 that has been cast to \f(CW\*(C`SV*\*(C'\fR), of which the prototype will be used if it
15225 has one. The prototype (or lack thereof) supplied, in whichever form,
15226 does not need to match the actual callee referenced by the op tree.
15227 .Sp
15228 If the argument ops disagree with the prototype, for example by having
15229 an unacceptable number of arguments, a valid op tree is returned anyway.
15230 The error is reflected in the parser state, normally resulting in a single
15231 exception at the top level of parsing which covers all the compilation
15232 errors that occurred. In the error message, the callee is referred to
15233 by the name defined by the \f(CW\*(C`namegv\*(C'\fR parameter.
15234 .RS 4
15235 .Sp
15236 .Vb 6
15237 \& OP * ck_entersub_args_proto_or_list( OP *entersubop,
15238 \& GV *namegv,
15239 \& SV *protosv)
15240 \& OP * Perl_ck_entersub_args_proto_or_list(pTHX_ OP *entersubop,
15241 \& GV *namegv,
15242 \& SV *protosv)
15243 .Ve
15244 .RE
15245 .RS 4
15246 .RE
15247 .ie n .IP """cv_const_sv""" 4
15248 .el .IP \f(CWcv_const_sv\fR 4
15249 .IX Xref "cv_const_sv"
15250 .IX Item "cv_const_sv"
15251 If \f(CW\*(C`cv\*(C'\fR is a constant sub eligible for inlining, returns the constant
15252 value returned by the sub. Otherwise, returns \f(CW\*(C`NULL\*(C'\fR.
15253 .Sp
15254 Constant subs can be created with \f(CW\*(C`newCONSTSUB\*(C'\fR or as described in
15255 "Constant Functions" in perlsub.
15256 .RS 4
15257 .Sp
15258 .Vb 2
15259 \& SV * cv_const_sv(const CV * const cv)
15260 \& SV * Perl_cv_const_sv(const CV * const cv)
15261 .Ve
15262 .RE
15263 .RS 4
15264 .RE
15265 .ie n .IP """cv_get_call_checker""" 4
15266 .el .IP \f(CWcv_get_call_checker\fR 4
15267 .IX Xref "cv_get_call_checker"
15268 .IX Item "cv_get_call_checker"
15269 The original form of "cv_get_call_checker_flags", which does not return
15270 checker flags. When using a checker function returned by this function,
15271 it is only safe to call it with a genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument.
15272 .RS 4
15273 .Sp
15274 .Vb 6
15275 \& void cv_get_call_checker( CV *cv,
15276 \& Perl_call_checker *ckfun_p,
15277 \& SV **ckobj_p)
15278 \& void Perl_cv_get_call_checker(pTHX_ CV *cv,
15279 \& Perl_call_checker *ckfun_p,
15280 \& SV **ckobj_p)
15281 .Ve
15282 .RE
15283 .RS 4
15284 .RE
15285 .ie n .IP """cv_get_call_checker_flags""" 4
15286 .el .IP \f(CWcv_get_call_checker_flags\fR 4
15287 .IX Xref "cv_get_call_checker_flags"
15288 .IX Item "cv_get_call_checker_flags"
15289 Retrieves the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR.
15290 Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
15291 subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
15292 at compile time as \f(CW\*(C`cv\*(C'\fR.
15293 .Sp
15294 The C\-level function pointer is returned in \f(CW*ckfun_p\fR, an SV argument
15295 for it is returned in \f(CW*ckobj_p\fR, and control flags are returned in
15296 \&\f(CW*ckflags_p\fR. The function is intended to be called in this manner:
15297 .Sp
15298 .Vb 1
15299 \& entersubop = (*ckfun_p)(aTHX_ entersubop, namegv, (*ckobj_p));
15300 .Ve
15301 .Sp
15302 In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
15303 which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies
15304 the name that should be used by the check function to refer
15305 to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
15306 It is permitted to apply the check function in non\-standard situations,
15307 such as to a call to a different subroutine or to a method call.
15308 .Sp
15309 \&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV. If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
15310 bit is clear in \f(CW*ckflags_p\fR, it is permitted to pass a CV or other SV
15311 instead, anything that can be used as the first argument to "cv_name".
15312 If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW*ckflags_p\fR then the
15313 check function requires \f(CW\*(C`namegv\*(C'\fR to be a genuine GV.
15314 .Sp
15315 By default, the check function is
15316 Perl_ck_entersub_args_proto_or_list,
15317 the SV parameter is \f(CW\*(C`cv\*(C'\fR itself, and the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
15318 flag is clear. This implements standard prototype processing. It can
15319 be changed, for a particular subroutine, by "cv_set_call_checker_flags".
15320 .Sp
15321 If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is set in \f(CW\*(C`gflags\*(C'\fR then it
15322 indicates that the caller only knows about the genuine GV version of
15323 \&\f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit will always be set in
15324 \&\f(CW*ckflags_p\fR, regardless of the check function\*(Aqs recorded requirements.
15325 If the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit is clear in \f(CW\*(C`gflags\*(C'\fR then it
15326 indicates the caller knows about the possibility of passing something
15327 other than a GV as \f(CW\*(C`namegv\*(C'\fR, and accordingly the corresponding bit may
15328 be either set or clear in \f(CW*ckflags_p\fR, indicating the check function\*(Aqs
15329 recorded requirements.
15330 .Sp
15331 \&\f(CW\*(C`gflags\*(C'\fR is a bitset passed into \f(CW\*(C`cv_get_call_checker_flags\*(C'\fR, in which
15332 only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR bit currently has a defined meaning
15333 (for which see above). All other bits should be clear.
15334 .RS 4
15335 .Sp
15336 .Vb 8
15337 \& void cv_get_call_checker_flags(CV *cv, U32 gflags,
15338 \& Perl_call_checker *ckfun_p,
15339 \& SV **ckobj_p,
15340 \& U32 *ckflags_p)
15341 \& void Perl_cv_get_call_checker_flags(pTHX_ CV *cv, U32 gflags,
15342 \& Perl_call_checker *ckfun_p,
15343 \& SV **ckobj_p,
15344 \& U32 *ckflags_p)
15345 .Ve
15346 .RE
15347 .RS 4
15348 .RE
15349 .ie n .IP """cv_set_call_checker""" 4
15350 .el .IP \f(CWcv_set_call_checker\fR 4
15351 .IX Xref "cv_set_call_checker"
15352 .IX Item "cv_set_call_checker"
15353 The original form of "cv_set_call_checker_flags", which passes it the
15354 \&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR flag for backward\-compatibility. The effect
15355 of that flag setting is that the check function is guaranteed to get a
15356 genuine GV as its \f(CW\*(C`namegv\*(C'\fR argument.
15357 .RS 4
15358 .Sp
15359 .Vb 6
15360 \& void cv_set_call_checker( CV *cv,
15361 \& Perl_call_checker ckfun,
15362 \& SV *ckobj)
15363 \& void Perl_cv_set_call_checker(pTHX_ CV *cv,
15364 \& Perl_call_checker ckfun,
15365 \& SV *ckobj)
15366 .Ve
15367 .RE
15368 .RS 4
15369 .RE
15370 .ie n .IP """cv_set_call_checker_flags""" 4
15371 .el .IP \f(CWcv_set_call_checker_flags\fR 4
15372 .IX Xref "cv_set_call_checker_flags"
15373 .IX Item "cv_set_call_checker_flags"
15374 Sets the function that will be used to fix up a call to \f(CW\*(C`cv\*(C'\fR.
15375 Specifically, the function is applied to an \f(CW\*(C`entersub\*(C'\fR op tree for a
15376 subroutine call, not marked with \f(CW\*(C`&\*(C'\fR, where the callee can be identified
15377 at compile time as \f(CW\*(C`cv\*(C'\fR.
15378 .Sp
15379 The C\-level function pointer is supplied in \f(CW\*(C`ckfun\*(C'\fR, an SV argument for
15380 it is supplied in \f(CW\*(C`ckobj\*(C'\fR, and control flags are supplied in \f(CW\*(C`ckflags\*(C'\fR.
15381 The function should be defined like this:
15382 .Sp
15383 .Vb 1
15384 \& STATIC OP * ckfun(pTHX_ OP *op, GV *namegv, SV *ckobj)
15385 .Ve
15386 .Sp
15387 It is intended to be called in this manner:
15388 .Sp
15389 .Vb 1
15390 \& entersubop = ckfun(aTHX_ entersubop, namegv, ckobj);
15391 .Ve
15392 .Sp
15393 In this call, \f(CW\*(C`entersubop\*(C'\fR is a pointer to the \f(CW\*(C`entersub\*(C'\fR op,
15394 which may be replaced by the check function, and \f(CW\*(C`namegv\*(C'\fR supplies
15395 the name that should be used by the check function to refer
15396 to the callee of the \f(CW\*(C`entersub\*(C'\fR op if it needs to emit any diagnostics.
15397 It is permitted to apply the check function in non\-standard situations,
15398 such as to a call to a different subroutine or to a method call.
15399 .Sp
15400 \&\f(CW\*(C`namegv\*(C'\fR may not actually be a GV. For efficiency, perl may pass a
15401 CV or other SV instead. Whatever is passed can be used as the first
15402 argument to "cv_name". You can force perl to pass a GV by including
15403 \&\f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR in the \f(CW\*(C`ckflags\*(C'\fR.
15404 .Sp
15405 \&\f(CW\*(C`ckflags\*(C'\fR is a bitset, in which only the \f(CW\*(C`CALL_CHECKER_REQUIRE_GV\*(C'\fR
15406 bit currently has a defined meaning (for which see above). All other
15407 bits should be clear.
15408 .Sp
15409 The current setting for a particular CV can be retrieved by
15410 "cv_get_call_checker_flags".
15411 .RS 4
15412 .Sp
15413 .Vb 6
15414 \& void cv_set_call_checker_flags( CV *cv,
15415 \& Perl_call_checker ckfun,
15416 \& SV *ckobj, U32 ckflags)
15417 \& void Perl_cv_set_call_checker_flags(pTHX_ CV *cv,
15418 \& Perl_call_checker ckfun,
15419 \& SV *ckobj, U32 ckflags)
15420 .Ve
15421 .RE
15422 .RS 4
15423 .RE
15424 .ie n .IP """finalize_optree""" 4
15425 .el .IP \f(CWfinalize_optree\fR 4
15426 .IX Xref "finalize_optree"
15427 .IX Item "finalize_optree"
15428 This function finalizes the optree. Should be called directly after
15429 the complete optree is built. It does some additional
15430 checking which can\*(Aqt be done in the normal \f(CW\*(C`ck_\*(C'\fRxxx functions and makes
15431 the tree thread\-safe.
15432 .RS 4
15433 .Sp
15434 .Vb 2
15435 \& void finalize_optree( OP *o)
15436 \& void Perl_finalize_optree(pTHX_ OP *o)
15437 .Ve
15438 .RE
15439 .RS 4
15440 .RE
15441 .ie n .IP """forbid_outofblock_ops""" 4
15442 .el .IP \f(CWforbid_outofblock_ops\fR 4
15443 .IX Xref "forbid_outofblock_ops"
15444 .IX Item "forbid_outofblock_ops"
15445 NOTE: \f(CW\*(C`forbid_outofblock_ops\*(C'\fR is \fBexperimental\fR and may change or be
15446 removed without notice.
15447 .Sp
15448 Checks an optree that implements a block, to ensure there are no control\-flow
15449 ops that attempt to leave the block. Any \f(CW\*(C`OP_RETURN\*(C'\fR is forbidden, as is any
15450 \&\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
15451 \&\f(CW\*(C`OP_REDO\*(C'\fR) that affects a loop that contains it within the block are
15452 permitted, but those that do not are forbidden.
15453 .Sp
15454 If any of these forbidden constructions are detected, an exception is thrown
15455 by using the op name and the blockname argument to construct a suitable
15456 message.
15457 .Sp
15458 This function alone is not sufficient to ensure the optree does not perform
15459 any of these forbidden activities during runtime, as it might call a different
15460 function that performs a non\-local LOOPEX, or a string\-\fBeval()\fR that performs a
15461 \&\f(CW\*(C`goto\*(C'\fR, or various other things. It is intended purely as a compile\-time
15462 check for those that could be detected statically. Additional runtime checks
15463 may be required depending on the circumstance it is used for.
15464 .Sp
15465 Note currently that \fIall\fR \f(CW\*(C`OP_GOTO\*(C'\fR ops are forbidden, even in cases where
15466 they might otherwise be safe to execute. This may be permitted in a later
15467 version.
15468 .RS 4
15469 .Sp
15470 .Vb 4
15471 \& void forbid_outofblock_ops( OP *o,
15472 \& const char *blockname)
15473 \& void Perl_forbid_outofblock_ops(pTHX_ OP *o,
15474 \& const char *blockname)
15475 .Ve
15476 .RE
15477 .RS 4
15478 .RE
15479 .ie n .IP """LINKLIST""" 4
15480 .el .IP \f(CWLINKLIST\fR 4
15481 .IX Xref "LINKLIST"
15482 .IX Item "LINKLIST"
15483 Given the root of an optree, link the tree in execution order using the
15484 \&\f(CW\*(C`op_next\*(C'\fR pointers and return the first op executed. If this has
15485 already been done, it will not be redone, and \f(CW\*(C`o\->op_next\*(C'\fR will be
15486 returned. If \f(CW\*(C`o\->op_next\*(C'\fR is not already set, \f(CW\*(C`o\*(C'\fR should be at
15487 least an \f(CW\*(C`UNOP\*(C'\fR.
15488 .RS 4
15489 .Sp
15490 .Vb 1
15491 \& OP* LINKLIST(OP *o)
15492 .Ve
15493 .RE
15494 .RS 4
15495 .RE
15496 .ie n .IP """LISTOP""" 4
15497 .el .IP \f(CWLISTOP\fR 4
15498 .IX Item "LISTOP"
15499 .PD 0
15500 .ie n .IP """LOGOP""" 4
15501 .el .IP \f(CWLOGOP\fR 4
15502 .IX Item "LOGOP"
15503 .ie n .IP """LOOP""" 4
15504 .el .IP \f(CWLOOP\fR 4
15505 .IX Item "LOOP"
15506 .PD
15507 Described in perlguts.
15508 .ie n .IP """newANONATTRSUB""" 4
15509 .el .IP \f(CWnewANONATTRSUB\fR 4
15510 .IX Xref "newANONATTRSUB"
15511 .IX Item "newANONATTRSUB"
15512 Construct a nameless (anonymous) Perl subroutine, also performing some
15513 surrounding jobs.
15514 .Sp
15515 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
15516 set to FALSE, and its \f(CW\*(C`o\*(C'\fR parameter to NULL.
15517 For more details, see "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
15518 .RS 4
15519 .Sp
15520 .Vb 4
15521 \& OP * newANONATTRSUB( I32 floor, OP *proto, OP *attrs,
15522 \& OP *block)
15523 \& OP * Perl_newANONATTRSUB(pTHX_ I32 floor, OP *proto, OP *attrs,
15524 \& OP *block)
15525 .Ve
15526 .RE
15527 .RS 4
15528 .RE
15529 .ie n .IP """newANONHASH""" 4
15530 .el .IP \f(CWnewANONHASH\fR 4
15531 .IX Xref "newANONHASH"
15532 .IX Item "newANONHASH"
15533 Constructs, checks, and returns an anonymous hash op.
15534 .RS 4
15535 .Sp
15536 .Vb 2
15537 \& OP * newANONHASH( OP *o)
15538 \& OP * Perl_newANONHASH(pTHX_ OP *o)
15539 .Ve
15540 .RE
15541 .RS 4
15542 .RE
15543 .ie n .IP """newANONLIST""" 4
15544 .el .IP \f(CWnewANONLIST\fR 4
15545 .IX Xref "newANONLIST"
15546 .IX Item "newANONLIST"
15547 Constructs, checks, and returns an anonymous list op.
15548 .RS 4
15549 .Sp
15550 .Vb 2
15551 \& OP * newANONLIST( OP *o)
15552 \& OP * Perl_newANONLIST(pTHX_ OP *o)
15553 .Ve
15554 .RE
15555 .RS 4
15556 .RE
15557 .ie n .IP """newANONSUB""" 4
15558 .el .IP \f(CWnewANONSUB\fR 4
15559 .IX Xref "newANONSUB"
15560 .IX Item "newANONSUB"
15561 Construct a nameless (anonymous) Perl subroutine without attributes, also
15562 performing some surrounding jobs.
15563 .Sp
15564 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
15565 set to FALSE, and its \f(CW\*(C`o\*(C'\fR and \f(CW\*(C`attrs\*(C'\fR parameters to NULL.
15566 For more details, see "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
15567 .RS 4
15568 .Sp
15569 .Vb 2
15570 \& OP * newANONSUB( I32 floor, OP *proto, OP *block)
15571 \& OP * Perl_newANONSUB(pTHX_ I32 floor, OP *proto, OP *block)
15572 .Ve
15573 .RE
15574 .RS 4
15575 .RE
15576 .ie n .IP """newARGDEFELEMOP""" 4
15577 .el .IP \f(CWnewARGDEFELEMOP\fR 4
15578 .IX Xref "newARGDEFELEMOP"
15579 .IX Item "newARGDEFELEMOP"
15580 Constructs and returns a new \f(CW\*(C`OP_ARGDEFELEM\*(C'\fR op which provides a defaulting
15581 expression given by \f(CW\*(C`expr\*(C'\fR for the signature parameter at the index given
15582 by \f(CW\*(C`argindex\*(C'\fR. The expression optree is consumed by this function and
15583 becomes part of the returned optree.
15584 .RS 4
15585 .Sp
15586 .Vb 4
15587 \& OP * newARGDEFELEMOP( I32 flags, OP *expr,
15588 \& I32 argindex)
15589 \& OP * Perl_newARGDEFELEMOP(pTHX_ I32 flags, OP *expr,
15590 \& I32 argindex)
15591 .Ve
15592 .RE
15593 .RS 4
15594 .RE
15595 .ie n .IP """newASSIGNOP""" 4
15596 .el .IP \f(CWnewASSIGNOP\fR 4
15597 .IX Xref "newASSIGNOP"
15598 .IX Item "newASSIGNOP"
15599 Constructs, checks, and returns an assignment op. \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR
15600 supply the parameters of the assignment; they are consumed by this
15601 function and become part of the constructed op tree.
15602 .Sp
15603 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
15604 a suitable conditional optree is constructed. If \f(CW\*(C`optype\*(C'\fR is the opcode
15605 of a binary operator, such as \f(CW\*(C`OP_BIT_OR\*(C'\fR, then an op is constructed that
15606 performs the binary operation and assigns the result to the left argument.
15607 Either way, if \f(CW\*(C`optype\*(C'\fR is non\-zero then \f(CW\*(C`flags\*(C'\fR has no effect.
15608 .Sp
15609 If \f(CW\*(C`optype\*(C'\fR is zero, then a plain scalar or list assignment is
15610 constructed. Which type of assignment it is is automatically determined.
15611 \&\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
15612 will be set automatically, and, shifted up eight bits, the eight bits
15613 of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically
15614 set as required.
15615 .RS 4
15616 .Sp
15617 .Vb 4
15618 \& OP * newASSIGNOP( I32 flags, OP *left, I32 optype,
15619 \& OP *right)
15620 \& OP * Perl_newASSIGNOP(pTHX_ I32 flags, OP *left, I32 optype,
15621 \& OP *right)
15622 .Ve
15623 .RE
15624 .RS 4
15625 .RE
15626 .ie n .IP """newATTRSUB""" 4
15627 .el .IP \f(CWnewATTRSUB\fR 4
15628 .IX Xref "newATTRSUB"
15629 .IX Item "newATTRSUB"
15630 Construct a Perl subroutine, also performing some surrounding jobs,
15631 returning a pointer to the constructed subroutine.
15632 .Sp
15633 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
15634 set to FALSE. This means that if \f(CW\*(C`o\*(C'\fR is null, the new sub will be anonymous;
15635 otherwise the name will be derived from \f(CW\*(C`o\*(C'\fR in the way described (as with all
15636 other details) in "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
15637 .RS 4
15638 .Sp
15639 .Vb 2
15640 \& CV * newATTRSUB(I32 floor, OP *o, OP *proto, OP *attrs,
15641 \& OP *block)
15642 .Ve
15643 .RE
15644 .RS 4
15645 .RE
15646 .ie n .IP """newAVREF""" 4
15647 .el .IP \f(CWnewAVREF\fR 4
15648 .IX Xref "newAVREF"
15649 .IX Item "newAVREF"
15650 Constructs, checks, and returns an arrary reference op.
15651 .RS 4
15652 .Sp
15653 .Vb 2
15654 \& OP * newAVREF( OP *o)
15655 \& OP * Perl_newAVREF(pTHX_ OP *o)
15656 .Ve
15657 .RE
15658 .RS 4
15659 .RE
15660 .ie n .IP """newBINOP""" 4
15661 .el .IP \f(CWnewBINOP\fR 4
15662 .IX Xref "newBINOP"
15663 .IX Item "newBINOP"
15664 Constructs, checks, and returns an op of any binary type. \f(CW\*(C`type\*(C'\fR
15665 is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except
15666 that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits,
15667 the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or
15668 2 is automatically set as required. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR supply up to
15669 two ops to be the direct children of the binary op; they are consumed
15670 by this function and become part of the constructed op tree.
15671 .RS 4
15672 .Sp
15673 .Vb 4
15674 \& OP * newBINOP( I32 type, I32 flags, OP *first,
15675 \& OP *last)
15676 \& OP * Perl_newBINOP(pTHX_ I32 type, I32 flags, OP *first,
15677 \& OP *last)
15678 .Ve
15679 .RE
15680 .RS 4
15681 .RE
15682 .ie n .IP """newCONDOP""" 4
15683 .el .IP \f(CWnewCONDOP\fR 4
15684 .IX Xref "newCONDOP"
15685 .IX Item "newCONDOP"
15686 Constructs, checks, and returns a conditional\-expression (\f(CW\*(C`cond_expr\*(C'\fR)
15687 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
15688 will be set automatically, and, shifted up eight bits, the eight bits of
15689 \&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is automatically set.
15690 \&\f(CW\*(C`first\*(C'\fR supplies the expression selecting between the two branches,
15691 and \f(CW\*(C`trueop\*(C'\fR and \f(CW\*(C`falseop\*(C'\fR supply the branches; they are consumed by
15692 this function and become part of the constructed op tree.
15693 .RS 4
15694 .Sp
15695 .Vb 4
15696 \& OP * newCONDOP( I32 flags, OP *first, OP *trueop,
15697 \& OP *falseop)
15698 \& OP * Perl_newCONDOP(pTHX_ I32 flags, OP *first, OP *trueop,
15699 \& OP *falseop)
15700 .Ve
15701 .RE
15702 .RS 4
15703 .RE
15704 .ie n .IP """newCONSTSUB""" 4
15705 .el .IP \f(CWnewCONSTSUB\fR 4
15706 .IX Item "newCONSTSUB"
15707 .PD 0
15708 .ie n .IP """newCONSTSUB_flags""" 4
15709 .el .IP \f(CWnewCONSTSUB_flags\fR 4
15710 .IX Xref "newCONSTSUB newCONSTSUB_flags"
15711 .IX Item "newCONSTSUB_flags"
15712 .PD
15713 Construct a constant subroutine, also performing some surrounding
15714 jobs. A scalar constant\-valued subroutine is eligible for inlining
15715 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.
15716 .Sp
15717 The subroutine will have an empty prototype and will ignore any arguments
15718 when called. Its constant behaviour is determined by \f(CW\*(C`sv\*(C'\fR. If \f(CW\*(C`sv\*(C'\fR
15719 is null, the subroutine will yield an empty list. If \f(CW\*(C`sv\*(C'\fR points to a
15720 scalar, the subroutine will always yield that scalar. If \f(CW\*(C`sv\*(C'\fR points
15721 to an array, the subroutine will always yield a list of the elements of
15722 that array in list context, or the number of elements in the array in
15723 scalar context. This function takes ownership of one counted reference
15724 to the scalar or array, and will arrange for the object to live as long
15725 as the subroutine does. If \f(CW\*(C`sv\*(C'\fR points to a scalar then the inlining
15726 assumes that the value of the scalar will never change, so the caller
15727 must ensure that the scalar is not subsequently written to. If \f(CW\*(C`sv\*(C'\fR
15728 points to an array then no such assumption is made, so it is ostensibly
15729 safe to mutate the array or its elements, but whether this is really
15730 supported has not been determined.
15731 .Sp
15732 The subroutine will have \f(CW\*(C`CvFILE\*(C'\fR set according to \f(CW\*(C`PL_curcop\*(C'\fR.
15733 Other aspects of the subroutine will be left in their default state.
15734 The caller is free to mutate the subroutine beyond its initial state
15735 after this function has returned.
15736 .Sp
15737 If \f(CW\*(C`name\*(C'\fR is null then the subroutine will be anonymous, with its
15738 \&\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
15739 subroutine will be named accordingly, referenced by the appropriate glob.
15740 .Sp
15741 \&\f(CW\*(C`name\*(C'\fR is a string, giving a sigilless symbol name.
15742 For \f(CW\*(C`/newCONSTSUB\*(C'\fR, \f(CW\*(C`name\*(C'\fR is NUL\-terminated, interpreted as Latin\-1.
15743 .Sp
15744 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
15745 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
15746 set, and Latin\-1 otherwise. \f(CW\*(C`flags\*(C'\fR should not have bits set other than
15747 \&\f(CW\*(C`SVf_UTF8\*(C'\fR.
15748 .Sp
15749 The name may be either qualified or unqualified. If the
15750 name is unqualified then it defaults to being in the stash specified by
15751 \&\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.
15752 The symbol is always added to the stash if necessary, with \f(CW\*(C`GV_ADDMULTI\*(C'\fR
15753 semantics.
15754 .Sp
15755 If there is already a subroutine of the specified name, then the new sub
15756 will replace the existing one in the glob. A warning may be generated
15757 about the redefinition.
15758 .Sp
15759 If the subroutine has one of a few special names, such as \f(CW\*(C`BEGIN\*(C'\fR or
15760 \&\f(CW\*(C`END\*(C'\fR, then it will be claimed by the appropriate queue for automatic
15761 running of phase\-related subroutines. In this case the relevant glob will
15762 be left not containing any subroutine, even if it did contain one before.
15763 Execution of the subroutine will likely be a no\-op, unless \f(CW\*(C`sv\*(C'\fR was
15764 a tied array or the caller modified the subroutine in some interesting
15765 way before it was executed. In the case of \f(CW\*(C`BEGIN\*(C'\fR, the treatment is
15766 buggy: the sub will be executed when only half built, and may be deleted
15767 prematurely, possibly causing a crash.
15768 .Sp
15769 The function returns a pointer to the constructed subroutine. If the sub
15770 is anonymous then ownership of one counted reference to the subroutine
15771 is transferred to the caller. If the sub is named then the caller does
15772 not get ownership of a reference. In most such cases, where the sub
15773 has a non\-phase name, the sub will be alive at the point it is returned
15774 by virtue of being contained in the glob that names it. A phase\-named
15775 subroutine will usually be alive by virtue of the reference owned by
15776 the phase\*(Aqs automatic run queue. A \f(CW\*(C`BEGIN\*(C'\fR subroutine may have been
15777 destroyed already by the time this function returns, but currently bugs
15778 occur in that case before the caller gets control. It is the caller\*(Aqs
15779 responsibility to ensure that it knows which of these situations applies.
15780 .RS 4
15781 .Sp
15782 .Vb 8
15783 \& CV * newCONSTSUB ( HV *stash, const char *name,
15784 \& SV *sv)
15785 \& CV * Perl_newCONSTSUB (pTHX_ HV *stash, const char *name,
15786 \& SV *sv)
15787 \& CV * newCONSTSUB_flags( HV *stash, const char *name,
15788 \& STRLEN len, U32 flags, SV *sv)
15789 \& CV * Perl_newCONSTSUB_flags(pTHX_ HV *stash, const char *name,
15790 \& STRLEN len, U32 flags, SV *sv)
15791 .Ve
15792 .RE
15793 .RS 4
15794 .RE
15795 .ie n .IP """newCVREF""" 4
15796 .el .IP \f(CWnewCVREF\fR 4
15797 .IX Xref "newCVREF"
15798 .IX Item "newCVREF"
15799 Constructs, checks, and returns a code reference op.
15800 .RS 4
15801 .Sp
15802 .Vb 2
15803 \& OP * newCVREF( I32 flags, OP *o)
15804 \& OP * Perl_newCVREF(pTHX_ I32 flags, OP *o)
15805 .Ve
15806 .RE
15807 .RS 4
15808 .RE
15809 .ie n .IP """newDEFEROP""" 4
15810 .el .IP \f(CWnewDEFEROP\fR 4
15811 .IX Xref "newDEFEROP"
15812 .IX Item "newDEFEROP"
15813 NOTE: \f(CW\*(C`newDEFEROP\*(C'\fR is \fBexperimental\fR and may change or be
15814 removed without notice.
15815 .Sp
15816 Constructs and returns a deferred\-block statement that implements the
15817 \&\f(CW\*(C`defer\*(C'\fR semantics. The \f(CW\*(C`block\*(C'\fR optree is consumed by this function and
15818 becomes part of the returned optree.
15819 .Sp
15820 The \f(CW\*(C`flags\*(C'\fR argument carries additional flags to set on the returned op,
15821 including the \f(CW\*(C`op_private\*(C'\fR field.
15822 .RS 4
15823 .Sp
15824 .Vb 2
15825 \& OP * newDEFEROP( I32 flags, OP *block)
15826 \& OP * Perl_newDEFEROP(pTHX_ I32 flags, OP *block)
15827 .Ve
15828 .RE
15829 .RS 4
15830 .RE
15831 .ie n .IP """newDEFSVOP""" 4
15832 .el .IP \f(CWnewDEFSVOP\fR 4
15833 .IX Xref "newDEFSVOP"
15834 .IX Item "newDEFSVOP"
15835 Constructs and returns an op to access \f(CW$_\fR.
15836 .RS 4
15837 .Sp
15838 .Vb 2
15839 \& OP * newDEFSVOP()
15840 \& OP * Perl_newDEFSVOP(pTHX)
15841 .Ve
15842 .RE
15843 .RS 4
15844 .RE
15845 .ie n .IP """newFOROP""" 4
15846 .el .IP \f(CWnewFOROP\fR 4
15847 .IX Xref "newFOROP"
15848 .IX Item "newFOROP"
15849 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`foreach\*(C'\fR
15850 loop (iteration through a list of values). This is a heavyweight loop,
15851 with structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR and suchlike.
15852 .Sp
15853 \&\f(CW\*(C`sv\*(C'\fR optionally supplies the variable(s) that will be aliased to each
15854 item in turn; if null, it defaults to \f(CW$_\fR.
15855 \&\f(CW\*(C`expr\*(C'\fR supplies the list of values to iterate over. \f(CW\*(C`block\*(C'\fR supplies
15856 the main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR
15857 block that operates as a second half of the body. All of these optree
15858 inputs are consumed by this function and become part of the constructed
15859 op tree.
15860 .Sp
15861 \&\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
15862 op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for
15863 the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set
15864 automatically.
15865 .RS 4
15866 .Sp
15867 .Vb 4
15868 \& OP * newFOROP( I32 flags, OP *sv, OP *expr, OP *block,
15869 \& OP *cont)
15870 \& OP * Perl_newFOROP(pTHX_ I32 flags, OP *sv, OP *expr, OP *block,
15871 \& OP *cont)
15872 .Ve
15873 .RE
15874 .RS 4
15875 .RE
15876 .ie n .IP """newGIVENOP""" 4
15877 .el .IP \f(CWnewGIVENOP\fR 4
15878 .IX Xref "newGIVENOP"
15879 .IX Item "newGIVENOP"
15880 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`given\*(C'\fR block.
15881 \&\f(CW\*(C`cond\*(C'\fR supplies the expression to whose value \f(CW$_\fR will be locally
15882 aliased, and \f(CW\*(C`block\*(C'\fR supplies the body of the \f(CW\*(C`given\*(C'\fR construct; they
15883 are consumed by this function and become part of the constructed op tree.
15884 \&\f(CW\*(C`defsv_off\*(C'\fR must be zero (it used to identity the pad slot of lexical \f(CW$_\fR).
15885 .RS 4
15886 .Sp
15887 .Vb 4
15888 \& OP * newGIVENOP( OP *cond, OP *block,
15889 \& PADOFFSET defsv_off)
15890 \& OP * Perl_newGIVENOP(pTHX_ OP *cond, OP *block,
15891 \& PADOFFSET defsv_off)
15892 .Ve
15893 .RE
15894 .RS 4
15895 .RE
15896 .ie n .IP """newGVOP""" 4
15897 .el .IP \f(CWnewGVOP\fR 4
15898 .IX Xref "newGVOP"
15899 .IX Item "newGVOP"
15900 Constructs, checks, and returns an op of any type that involves an
15901 embedded reference to a GV. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the
15902 eight bits of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`gv\*(C'\fR identifies the GV that the op should
15903 reference; calling this function does not transfer ownership of any
15904 reference to it.
15905 .RS 4
15906 .Sp
15907 .Vb 2
15908 \& OP * newGVOP( I32 type, I32 flags, GV *gv)
15909 \& OP * Perl_newGVOP(pTHX_ I32 type, I32 flags, GV *gv)
15910 .Ve
15911 .RE
15912 .RS 4
15913 .RE
15914 .ie n .IP """newGVREF""" 4
15915 .el .IP \f(CWnewGVREF\fR 4
15916 .IX Xref "newGVREF"
15917 .IX Item "newGVREF"
15918 Constructs, checks, and returns a glob reference op.
15919 .RS 4
15920 .Sp
15921 .Vb 2
15922 \& OP * newGVREF( I32 type, OP *o)
15923 \& OP * Perl_newGVREF(pTHX_ I32 type, OP *o)
15924 .Ve
15925 .RE
15926 .RS 4
15927 .RE
15928 .ie n .IP """newHVREF""" 4
15929 .el .IP \f(CWnewHVREF\fR 4
15930 .IX Xref "newHVREF"
15931 .IX Item "newHVREF"
15932 Constructs, checks, and returns a hash reference op.
15933 .RS 4
15934 .Sp
15935 .Vb 2
15936 \& OP * newHVREF( OP *o)
15937 \& OP * Perl_newHVREF(pTHX_ OP *o)
15938 .Ve
15939 .RE
15940 .RS 4
15941 .RE
15942 .ie n .IP """newLISTOP""" 4
15943 .el .IP \f(CWnewLISTOP\fR 4
15944 .IX Xref "newLISTOP"
15945 .IX Item "newLISTOP"
15946 Constructs, checks, and returns an op of any list type. \f(CW\*(C`type\*(C'\fR is
15947 the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
15948 \&\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
15949 supply up to two ops to be direct children of the list op; they are
15950 consumed by this function and become part of the constructed op tree.
15951 .Sp
15952 For most list operators, the check function expects all the kid ops to be
15953 present already, so calling \f(CW\*(C`newLISTOP(OP_JOIN, ...)\*(C'\fR (e.g.) is not
15954 appropriate. What you want to do in that case is create an op of type
15955 \&\f(CW\*(C`OP_LIST\*(C'\fR, append more children to it, and then call "op_convert_list".
15956 See "op_convert_list" for more information.
15957 .Sp
15958 If a compiletime\-known fixed list of child ops is required, the
15959 "newLISTOPn" function can be used as a convenient shortcut, avoiding the
15960 need to create a temporary plain \f(CW\*(C`OP_LIST\*(C'\fR in a new variable.
15961 .RS 4
15962 .Sp
15963 .Vb 4
15964 \& OP * newLISTOP( I32 type, I32 flags, OP *first,
15965 \& OP *last)
15966 \& OP * Perl_newLISTOP(pTHX_ I32 type, I32 flags, OP *first,
15967 \& OP *last)
15968 .Ve
15969 .RE
15970 .RS 4
15971 .RE
15972 .ie n .IP """newLISTOPn""" 4
15973 .el .IP \f(CWnewLISTOPn\fR 4
15974 .IX Xref "newLISTOPn"
15975 .IX Item "newLISTOPn"
15976 Constructs, checks, and returns an op of any list type. \f(CW\*(C`type\*(C'\fR is
15977 the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
15978 \&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required. The variable number of
15979 arguments after \f(CW\*(C`flags\*(C'\fR must all be OP pointers, terminated by a final
15980 \&\f(CW\*(C`NULL\*(C'\fR pointer. These will all be consumed as direct children of the list
15981 op and become part of the constructed op tree.
15982 .Sp
15983 Do not forget to end the arguments list with a \f(CW\*(C`NULL\*(C'\fR pointer.
15984 .Sp
15985 This function is useful as a shortcut to performing the sequence of
15986 \&\f(CWnewLISTOP()\fR, \f(CWop_append_elem()\fR on each element and final
15987 \&\f(CWop_convert_list()\fR in the case where a compiletime\-known fixed sequence of
15988 child ops is required. If a variable number of elements are required, or for
15989 splicing in an entire sub\-list of child ops, see instead "newLISTOP" and
15990 "op_convert_list".
15991 .RS 4
15992 .Sp
15993 .Vb 2
15994 \& OP * newLISTOPn( I32 type, I32 flags, ...)
15995 \& OP * Perl_newLISTOPn(pTHX_ I32 type, I32 flags, ...)
15996 .Ve
15997 .RE
15998 .RS 4
15999 .RE
16000 .ie n .IP """newLOGOP""" 4
16001 .el .IP \f(CWnewLOGOP\fR 4
16002 .IX Xref "newLOGOP"
16003 .IX Item "newLOGOP"
16004 Constructs, checks, and returns a logical (flow control) op. \f(CW\*(C`type\*(C'\fR
16005 is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except
16006 that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically, and, shifted up eight bits,
16007 the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 is
16008 automatically set. \f(CW\*(C`first\*(C'\fR supplies the expression controlling the
16009 flow, and \f(CW\*(C`other\*(C'\fR supplies the side (alternate) chain of ops; they are
16010 consumed by this function and become part of the constructed op tree.
16011 .RS 4
16012 .Sp
16013 .Vb 4
16014 \& OP * newLOGOP( I32 optype, I32 flags, OP *first,
16015 \& OP *other)
16016 \& OP * Perl_newLOGOP(pTHX_ I32 optype, I32 flags, OP *first,
16017 \& OP *other)
16018 .Ve
16019 .RE
16020 .RS 4
16021 .RE
16022 .ie n .IP """newLOOPEX""" 4
16023 .el .IP \f(CWnewLOOPEX\fR 4
16024 .IX Xref "newLOOPEX"
16025 .IX Item "newLOOPEX"
16026 Constructs, checks, and returns a loop\-exiting op (such as \f(CW\*(C`goto\*(C'\fR
16027 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
16028 determining the target of the op; it is consumed by this function and
16029 becomes part of the constructed op tree.
16030 .RS 4
16031 .Sp
16032 .Vb 2
16033 \& OP * newLOOPEX( I32 type, OP *label)
16034 \& OP * Perl_newLOOPEX(pTHX_ I32 type, OP *label)
16035 .Ve
16036 .RE
16037 .RS 4
16038 .RE
16039 .ie n .IP """newLOOPOP""" 4
16040 .el .IP \f(CWnewLOOPOP\fR 4
16041 .IX Xref "newLOOPOP"
16042 .IX Item "newLOOPOP"
16043 Constructs, checks, and returns an op tree expressing a loop. This is
16044 only a loop in the control flow through the op tree; it does not have
16045 the heavyweight loop structure that allows exiting the loop by \f(CW\*(C`last\*(C'\fR
16046 and suchlike. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR for the
16047 top\-level op, except that some bits will be set automatically as required.
16048 \&\f(CW\*(C`expr\*(C'\fR supplies the expression controlling loop iteration, and \f(CW\*(C`block\*(C'\fR
16049 supplies the body of the loop; they are consumed by this function and
16050 become part of the constructed op tree. \f(CW\*(C`debuggable\*(C'\fR is currently
16051 unused and should always be 1.
16052 .RS 4
16053 .Sp
16054 .Vb 4
16055 \& OP * newLOOPOP( I32 flags, I32 debuggable, OP *expr,
16056 \& OP *block)
16057 \& OP * Perl_newLOOPOP(pTHX_ I32 flags, I32 debuggable, OP *expr,
16058 \& OP *block)
16059 .Ve
16060 .RE
16061 .RS 4
16062 .RE
16063 .ie n .IP """newMETHOP""" 4
16064 .el .IP \f(CWnewMETHOP\fR 4
16065 .IX Xref "newMETHOP"
16066 .IX Item "newMETHOP"
16067 Constructs, checks, and returns an op of method type with a method name
16068 evaluated at runtime. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight
16069 bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically,
16070 and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that
16071 the bit with value 1 is automatically set. \f(CW\*(C`dynamic_meth\*(C'\fR supplies an
16072 op which evaluates method name; it is consumed by this function and
16073 become part of the constructed op tree.
16074 Supported optypes: \f(CW\*(C`OP_METHOD\*(C'\fR.
16075 .RS 4
16076 .Sp
16077 .Vb 2
16078 \& OP * newMETHOP( I32 type, I32 flags, OP *dynamic_meth)
16079 \& OP * Perl_newMETHOP(pTHX_ I32 type, I32 flags, OP *dynamic_meth)
16080 .Ve
16081 .RE
16082 .RS 4
16083 .RE
16084 .ie n .IP """newMETHOP_named""" 4
16085 .el .IP \f(CWnewMETHOP_named\fR 4
16086 .IX Xref "newMETHOP_named"
16087 .IX Item "newMETHOP_named"
16088 Constructs, checks, and returns an op of method type with a constant
16089 method name. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of
16090 \&\f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits of
16091 \&\f(CW\*(C`op_private\*(C'\fR. \f(CW\*(C`const_meth\*(C'\fR supplies a constant method name;
16092 it must be a shared COW string.
16093 Supported optypes: \f(CW\*(C`OP_METHOD_NAMED\*(C'\fR.
16094 .RS 4
16095 .Sp
16096 .Vb 4
16097 \& OP * newMETHOP_named( I32 type, I32 flags,
16098 \& SV * const_meth)
16099 \& OP * Perl_newMETHOP_named(pTHX_ I32 type, I32 flags,
16100 \& SV * const_meth)
16101 .Ve
16102 .RE
16103 .RS 4
16104 .RE
16105 .ie n .IP """newNULLLIST""" 4
16106 .el .IP \f(CWnewNULLLIST\fR 4
16107 .IX Xref "newNULLLIST"
16108 .IX Item "newNULLLIST"
16109 Constructs, checks, and returns a new \f(CW\*(C`stub\*(C'\fR op, which represents an
16110 empty list expression.
16111 .RS 4
16112 .Sp
16113 .Vb 2
16114 \& OP * newNULLLIST()
16115 \& OP * Perl_newNULLLIST(pTHX)
16116 .Ve
16117 .RE
16118 .RS 4
16119 .RE
16120 .ie n .IP """newOP""" 4
16121 .el .IP \f(CWnewOP\fR 4
16122 .IX Xref "newOP"
16123 .IX Item "newOP"
16124 Constructs, checks, and returns an op of any base type (any type that
16125 has no extra fields). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the
16126 eight bits of \f(CW\*(C`op_flags\*(C'\fR, and, shifted up eight bits, the eight bits
16127 of \f(CW\*(C`op_private\*(C'\fR.
16128 .RS 4
16129 .Sp
16130 .Vb 2
16131 \& OP * newOP( I32 optype, I32 flags)
16132 \& OP * Perl_newOP(pTHX_ I32 optype, I32 flags)
16133 .Ve
16134 .RE
16135 .RS 4
16136 .RE
16137 .ie n .IP """newPADOP""" 4
16138 .el .IP \f(CWnewPADOP\fR 4
16139 .IX Xref "newPADOP"
16140 .IX Item "newPADOP"
16141 Constructs, checks, and returns an op of any type that involves a
16142 reference to a pad element. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the
16143 eight bits of \f(CW\*(C`op_flags\*(C'\fR. A pad slot is automatically allocated, and
16144 is populated with \f(CW\*(C`sv\*(C'\fR; this function takes ownership of one reference
16145 to it.
16146 .Sp
16147 This function only exists if Perl has been compiled to use ithreads.
16148 .RS 4
16149 .Sp
16150 .Vb 2
16151 \& OP * newPADOP( I32 type, I32 flags, SV *sv)
16152 \& OP * Perl_newPADOP(pTHX_ I32 type, I32 flags, SV *sv)
16153 .Ve
16154 .RE
16155 .RS 4
16156 .RE
16157 .ie n .IP """newPMOP""" 4
16158 .el .IP \f(CWnewPMOP\fR 4
16159 .IX Xref "newPMOP"
16160 .IX Item "newPMOP"
16161 Constructs, checks, and returns an op of any pattern matching type.
16162 \&\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
16163 and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR.
16164 .RS 4
16165 .Sp
16166 .Vb 2
16167 \& OP * newPMOP( I32 type, I32 flags)
16168 \& OP * Perl_newPMOP(pTHX_ I32 type, I32 flags)
16169 .Ve
16170 .RE
16171 .RS 4
16172 .RE
16173 .ie n .IP """newPVOP""" 4
16174 .el .IP \f(CWnewPVOP\fR 4
16175 .IX Xref "newPVOP"
16176 .IX Item "newPVOP"
16177 Constructs, checks, and returns an op of any type that involves an
16178 embedded C\-level pointer (PV). \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives
16179 the eight bits of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`pv\*(C'\fR supplies the C\-level pointer.
16180 Depending on the op type, the memory referenced by \f(CW\*(C`pv\*(C'\fR may be freed
16181 when the op is destroyed. If the op is of a freeing type, \f(CW\*(C`pv\*(C'\fR must
16182 have been allocated using \f(CW\*(C`PerlMemShared_malloc\*(C'\fR.
16183 .RS 4
16184 .Sp
16185 .Vb 2
16186 \& OP * newPVOP( I32 type, I32 flags, char *pv)
16187 \& OP * Perl_newPVOP(pTHX_ I32 type, I32 flags, char *pv)
16188 .Ve
16189 .RE
16190 .RS 4
16191 .RE
16192 .ie n .IP """newRANGE""" 4
16193 .el .IP \f(CWnewRANGE\fR 4
16194 .IX Xref "newRANGE"
16195 .IX Item "newRANGE"
16196 Constructs and returns a \f(CW\*(C`range\*(C'\fR op, with subordinate \f(CW\*(C`flip\*(C'\fR and
16197 \&\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
16198 \&\f(CW\*(C`flip\*(C'\fR op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR
16199 for both the \f(CW\*(C`flip\*(C'\fR and \f(CW\*(C`range\*(C'\fR ops, except that the bit with value
16200 1 is automatically set. \f(CW\*(C`left\*(C'\fR and \f(CW\*(C`right\*(C'\fR supply the expressions
16201 controlling the endpoints of the range; they are consumed by this function
16202 and become part of the constructed op tree.
16203 .RS 4
16204 .Sp
16205 .Vb 2
16206 \& OP * newRANGE( I32 flags, OP *left, OP *right)
16207 \& OP * Perl_newRANGE(pTHX_ I32 flags, OP *left, OP *right)
16208 .Ve
16209 .RE
16210 .RS 4
16211 .RE
16212 .ie n .IP """newSLICEOP""" 4
16213 .el .IP \f(CWnewSLICEOP\fR 4
16214 .IX Xref "newSLICEOP"
16215 .IX Item "newSLICEOP"
16216 Constructs, checks, and returns an \f(CW\*(C`lslice\*(C'\fR (list slice) op. \f(CW\*(C`flags\*(C'\fR
16217 gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that \f(CW\*(C`OPf_KIDS\*(C'\fR will
16218 be set automatically, and, shifted up eight bits, the eight bits of
16219 \&\f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1 or 2 is automatically
16220 set as required. \f(CW\*(C`listval\*(C'\fR and \f(CW\*(C`subscript\*(C'\fR supply the parameters of
16221 the slice; they are consumed by this function and become part of the
16222 constructed op tree.
16223 .RS 4
16224 .Sp
16225 .Vb 2
16226 \& OP * newSLICEOP( I32 flags, OP *subscript, OP *listop)
16227 \& OP * Perl_newSLICEOP(pTHX_ I32 flags, OP *subscript, OP *listop)
16228 .Ve
16229 .RE
16230 .RS 4
16231 .RE
16232 .ie n .IP """newSTATEOP""" 4
16233 .el .IP \f(CWnewSTATEOP\fR 4
16234 .IX Xref "newSTATEOP"
16235 .IX Item "newSTATEOP"
16236 Constructs a state op (COP). The state op is normally a \f(CW\*(C`nextstate\*(C'\fR op,
16237 but will be a \f(CW\*(C`dbstate\*(C'\fR op if debugging is enabled for currently\-compiled
16238 code. The state op is populated from \f(CW\*(C`PL_curcop\*(C'\fR (or \f(CW\*(C`PL_compiling\*(C'\fR).
16239 If \f(CW\*(C`label\*(C'\fR is non\-null, it supplies the name of a label to attach to
16240 the state op; this function takes ownership of the memory pointed at by
16241 \&\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
16242 for the state op.
16243 .Sp
16244 If \f(CW\*(C`o\*(C'\fR is null, the state op is returned. Otherwise the state op is
16245 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
16246 is consumed by this function and becomes part of the returned op tree.
16247 .RS 4
16248 .Sp
16249 .Vb 2
16250 \& OP * newSTATEOP( I32 flags, char *label, OP *o)
16251 \& OP * Perl_newSTATEOP(pTHX_ I32 flags, char *label, OP *o)
16252 .Ve
16253 .RE
16254 .RS 4
16255 .RE
16256 .ie n .IP """newSUB""" 4
16257 .el .IP \f(CWnewSUB\fR 4
16258 .IX Xref "newSUB"
16259 .IX Item "newSUB"
16260 Construct a Perl subroutine without attributes, and also performing some
16261 surrounding jobs, returning a pointer to the constructed subroutine.
16262 .Sp
16263 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
16264 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
16265 null, the new sub will be anonymous; otherwise the name will be derived from
16266 \&\f(CW\*(C`o\*(C'\fR in the way described (as with all other details) in
16267 "\f(CW\*(C`newATTRSUB_x\*(C'\fR" in perlintern.
16268 .RS 4
16269 .Sp
16270 .Vb 2
16271 \& CV * newSUB( I32 floor, OP *o, OP *proto, OP *block)
16272 \& CV * Perl_newSUB(pTHX_ I32 floor, OP *o, OP *proto, OP *block)
16273 .Ve
16274 .RE
16275 .RS 4
16276 .RE
16277 .ie n .IP """newSVOP""" 4
16278 .el .IP \f(CWnewSVOP\fR 4
16279 .IX Xref "newSVOP"
16280 .IX Item "newSVOP"
16281 Constructs, checks, and returns an op of any type that involves an
16282 embedded SV. \f(CW\*(C`type\*(C'\fR is the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits
16283 of \f(CW\*(C`op_flags\*(C'\fR. \f(CW\*(C`sv\*(C'\fR gives the SV to embed in the op; this function
16284 takes ownership of one reference to it.
16285 .RS 4
16286 .Sp
16287 .Vb 2
16288 \& OP * newSVOP( I32 type, I32 flags, SV *sv)
16289 \& OP * Perl_newSVOP(pTHX_ I32 type, I32 flags, SV *sv)
16290 .Ve
16291 .RE
16292 .RS 4
16293 .RE
16294 .ie n .IP """newSVREF""" 4
16295 .el .IP \f(CWnewSVREF\fR 4
16296 .IX Xref "newSVREF"
16297 .IX Item "newSVREF"
16298 Constructs, checks, and returns a scalar reference op.
16299 .RS 4
16300 .Sp
16301 .Vb 2
16302 \& OP * newSVREF( OP *o)
16303 \& OP * Perl_newSVREF(pTHX_ OP *o)
16304 .Ve
16305 .RE
16306 .RS 4
16307 .RE
16308 .ie n .IP """newTRYCATCHOP""" 4
16309 .el .IP \f(CWnewTRYCATCHOP\fR 4
16310 .IX Xref "newTRYCATCHOP"
16311 .IX Item "newTRYCATCHOP"
16312 NOTE: \f(CW\*(C`newTRYCATCHOP\*(C'\fR is \fBexperimental\fR and may change or be
16313 removed without notice.
16314 .Sp
16315 Constructs and returns a conditional execution statement that implements
16316 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,
16317 inside a context that traps exceptions. If an exception occurs then the
16318 optree in \f(CW\*(C`catchblock\*(C'\fR is executed, with the trapped exception set into the
16319 lexical variable given by \f(CW\*(C`catchvar\*(C'\fR (which must be an op of type
16320 \&\f(CW\*(C`OP_PADSV\*(C'\fR). All the optrees are consumed by this function and become part
16321 of the returned op tree.
16322 .Sp
16323 The \f(CW\*(C`flags\*(C'\fR argument is currently ignored.
16324 .RS 4
16325 .Sp
16326 .Vb 4
16327 \& OP * newTRYCATCHOP( I32 flags, OP *tryblock,
16328 \& OP *catchvar, OP *catchblock)
16329 \& OP * Perl_newTRYCATCHOP(pTHX_ I32 flags, OP *tryblock,
16330 \& OP *catchvar, OP *catchblock)
16331 .Ve
16332 .RE
16333 .RS 4
16334 .RE
16335 .ie n .IP """newUNOP""" 4
16336 .el .IP \f(CWnewUNOP\fR 4
16337 .IX Xref "newUNOP"
16338 .IX Item "newUNOP"
16339 Constructs, checks, and returns an op of any unary type. \f(CW\*(C`type\*(C'\fR is
16340 the opcode. \f(CW\*(C`flags\*(C'\fR gives the eight bits of \f(CW\*(C`op_flags\*(C'\fR, except that
16341 \&\f(CW\*(C`OPf_KIDS\*(C'\fR will be set automatically if required, and, shifted up eight
16342 bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR, except that the bit with value 1
16343 is automatically set. \f(CW\*(C`first\*(C'\fR supplies an optional op to be the direct
16344 child of the unary op; it is consumed by this function and become part
16345 of the constructed op tree.
16346 .RS 4
16347 .Sp
16348 .Vb 2
16349 \& OP * newUNOP( I32 type, I32 flags, OP *first)
16350 \& OP * Perl_newUNOP(pTHX_ I32 type, I32 flags, OP *first)
16351 .Ve
16352 .RE
16353 .RS 4
16354 .RE
16355 .ie n .IP """newUNOP_AUX""" 4
16356 .el .IP \f(CWnewUNOP_AUX\fR 4
16357 .IX Xref "newUNOP_AUX"
16358 .IX Item "newUNOP_AUX"
16359 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
16360 initialised to \f(CW\*(C`aux\*(C'\fR
16361 .RS 4
16362 .Sp
16363 .Vb 4
16364 \& OP * newUNOP_AUX( I32 type, I32 flags, OP *first,
16365 \& UNOP_AUX_item *aux)
16366 \& OP * Perl_newUNOP_AUX(pTHX_ I32 type, I32 flags, OP *first,
16367 \& UNOP_AUX_item *aux)
16368 .Ve
16369 .RE
16370 .RS 4
16371 .RE
16372 .ie n .IP """newWHENOP""" 4
16373 .el .IP \f(CWnewWHENOP\fR 4
16374 .IX Xref "newWHENOP"
16375 .IX Item "newWHENOP"
16376 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`when\*(C'\fR block.
16377 \&\f(CW\*(C`cond\*(C'\fR supplies the test expression, and \f(CW\*(C`block\*(C'\fR supplies the block
16378 that will be executed if the test evaluates to true; they are consumed
16379 by this function and become part of the constructed op tree. \f(CW\*(C`cond\*(C'\fR
16380 will be interpreted DWIMically, often as a comparison against \f(CW$_\fR,
16381 and may be null to generate a \f(CW\*(C`default\*(C'\fR block.
16382 .RS 4
16383 .Sp
16384 .Vb 2
16385 \& OP * newWHENOP( OP *cond, OP *block)
16386 \& OP * Perl_newWHENOP(pTHX_ OP *cond, OP *block)
16387 .Ve
16388 .RE
16389 .RS 4
16390 .RE
16391 .ie n .IP """newWHILEOP""" 4
16392 .el .IP \f(CWnewWHILEOP\fR 4
16393 .IX Xref "newWHILEOP"
16394 .IX Item "newWHILEOP"
16395 Constructs, checks, and returns an op tree expressing a \f(CW\*(C`while\*(C'\fR loop.
16396 This is a heavyweight loop, with structure that allows exiting the loop
16397 by \f(CW\*(C`last\*(C'\fR and suchlike.
16398 .Sp
16399 \&\f(CW\*(C`loop\*(C'\fR is an optional preconstructed \f(CW\*(C`enterloop\*(C'\fR op to use in the
16400 loop; if it is null then a suitable op will be constructed automatically.
16401 \&\f(CW\*(C`expr\*(C'\fR supplies the loop\*(Aqs controlling expression. \f(CW\*(C`block\*(C'\fR supplies the
16402 main body of the loop, and \f(CW\*(C`cont\*(C'\fR optionally supplies a \f(CW\*(C`continue\*(C'\fR block
16403 that operates as a second half of the body. All of these optree inputs
16404 are consumed by this function and become part of the constructed op tree.
16405 .Sp
16406 \&\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
16407 op and, shifted up eight bits, the eight bits of \f(CW\*(C`op_private\*(C'\fR for
16408 the \f(CW\*(C`leaveloop\*(C'\fR op, except that (in both cases) some bits will be set
16409 automatically. \f(CW\*(C`debuggable\*(C'\fR is currently unused and should always be 1.
16410 \&\f(CW\*(C`has_my\*(C'\fR can be supplied as true to force the
16411 loop body to be enclosed in its own scope.
16412 .RS 4
16413 .Sp
16414 .Vb 6
16415 \& OP * newWHILEOP( I32 flags, I32 debuggable,
16416 \& LOOP *loop, OP *expr, OP *block,
16417 \& OP *cont, I32 has_my)
16418 \& OP * Perl_newWHILEOP(pTHX_ I32 flags, I32 debuggable,
16419 \& LOOP *loop, OP *expr, OP *block,
16420 \& OP *cont, I32 has_my)
16421 .Ve
16422 .RE
16423 .RS 4
16424 .RE
16425 .ie n .IP """newXS""" 4
16426 .el .IP \f(CWnewXS\fR 4
16427 .IX Xref "newXS"
16428 .IX Item "newXS"
16429 Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. \f(CW\*(C`filename\*(C'\fR needs to be
16430 static storage, as it is used directly as \fBCvFILE()\fR, without a copy being made.
16431 .ie n .IP """OA_BASEOP""" 4
16432 .el .IP \f(CWOA_BASEOP\fR 4
16433 .IX Item "OA_BASEOP"
16434 .PD 0
16435 .ie n .IP """OA_BINOP""" 4
16436 .el .IP \f(CWOA_BINOP\fR 4
16437 .IX Item "OA_BINOP"
16438 .ie n .IP """OA_COP""" 4
16439 .el .IP \f(CWOA_COP\fR 4
16440 .IX Item "OA_COP"
16441 .ie n .IP """OA_LISTOP""" 4
16442 .el .IP \f(CWOA_LISTOP\fR 4
16443 .IX Item "OA_LISTOP"
16444 .ie n .IP """OA_LOGOP""" 4
16445 .el .IP \f(CWOA_LOGOP\fR 4
16446 .IX Item "OA_LOGOP"
16447 .ie n .IP """OA_LOOP""" 4
16448 .el .IP \f(CWOA_LOOP\fR 4
16449 .IX Item "OA_LOOP"
16450 .ie n .IP """OA_PADOP""" 4
16451 .el .IP \f(CWOA_PADOP\fR 4
16452 .IX Item "OA_PADOP"
16453 .ie n .IP """OA_PMOP""" 4
16454 .el .IP \f(CWOA_PMOP\fR 4
16455 .IX Item "OA_PMOP"
16456 .ie n .IP """OA_PVOP_OR_SVOP""" 4
16457 .el .IP \f(CWOA_PVOP_OR_SVOP\fR 4
16458 .IX Item "OA_PVOP_OR_SVOP"
16459 .ie n .IP """OA_SVOP""" 4
16460 .el .IP \f(CWOA_SVOP\fR 4
16461 .IX Item "OA_SVOP"
16462 .ie n .IP """OA_UNOP""" 4
16463 .el .IP \f(CWOA_UNOP\fR 4
16464 .IX Item "OA_UNOP"
16465 .ie n .IP """OP""" 4
16466 .el .IP \f(CWOP\fR 4
16467 .IX Item "OP"
16468 .PD
16469 Described in perlguts.
16470 .ie n .IP """op_append_elem""" 4
16471 .el .IP \f(CWop_append_elem\fR 4
16472 .IX Xref "op_append_elem"
16473 .IX Item "op_append_elem"
16474 Append an item to the list of ops contained directly within a list\-type
16475 op, returning the lengthened list. \f(CW\*(C`first\*(C'\fR is the list\-type op,
16476 and \f(CW\*(C`last\*(C'\fR is the op to append to the list. \f(CW\*(C`optype\*(C'\fR specifies the
16477 intended opcode for the list. If \f(CW\*(C`first\*(C'\fR is not already a list of the
16478 right type, it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR
16479 is null, the other is returned unchanged.
16480 .RS 4
16481 .Sp
16482 .Vb 2
16483 \& OP * op_append_elem( I32 optype, OP *first, OP *last)
16484 \& OP * Perl_op_append_elem(pTHX_ I32 optype, OP *first, OP *last)
16485 .Ve
16486 .RE
16487 .RS 4
16488 .RE
16489 .ie n .IP """op_append_list""" 4
16490 .el .IP \f(CWop_append_list\fR 4
16491 .IX Xref "op_append_list"
16492 .IX Item "op_append_list"
16493 Concatenate the lists of ops contained directly within two list\-type ops,
16494 returning the combined list. \f(CW\*(C`first\*(C'\fR and \f(CW\*(C`last\*(C'\fR are the list\-type ops
16495 to concatenate. \f(CW\*(C`optype\*(C'\fR specifies the intended opcode for the list.
16496 If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is not already a list of the right type,
16497 it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null,
16498 the other is returned unchanged.
16499 .RS 4
16500 .Sp
16501 .Vb 2
16502 \& OP * op_append_list( I32 optype, OP *first, OP *last)
16503 \& OP * Perl_op_append_list(pTHX_ I32 optype, OP *first, OP *last)
16504 .Ve
16505 .RE
16506 .RS 4
16507 .RE
16508 .ie n .IP """OP_CLASS""" 4
16509 .el .IP \f(CWOP_CLASS\fR 4
16510 .IX Xref "OP_CLASS"
16511 .IX Item "OP_CLASS"
16512 Return the class of the provided OP: that is, which of the *OP
16513 structures it uses. For core ops this currently gets the information out
16514 of \f(CW\*(C`PL_opargs\*(C'\fR, which does not always accurately reflect the type used;
16515 in v5.26 onwards, see also the function \f(CW"op_class"\fR which can do a better
16516 job of determining the used type.
16517 .Sp
16518 For custom ops the type is returned from the registration, and it is up
16519 to the registree to ensure it is accurate. The value returned will be
16520 one of the \f(CW\*(C`OA_\*(C'\fR* constants from \fIop.h\fR.
16521 .RS 4
16522 .Sp
16523 .Vb 1
16524 \& U32 OP_CLASS(OP *o)
16525 .Ve
16526 .RE
16527 .RS 4
16528 .RE
16529 .ie n .IP """op_contextualize""" 4
16530 .el .IP \f(CWop_contextualize\fR 4
16531 .IX Xref "op_contextualize"
16532 .IX Item "op_contextualize"
16533 Applies a syntactic context to an op tree representing an expression.
16534 \&\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,
16535 or \f(CW\*(C`G_VOID\*(C'\fR to specify the context to apply. The modified op tree
16536 is returned.
16537 .RS 4
16538 .Sp
16539 .Vb 2
16540 \& OP * op_contextualize( OP *o, I32 context)
16541 \& OP * Perl_op_contextualize(pTHX_ OP *o, I32 context)
16542 .Ve
16543 .RE
16544 .RS 4
16545 .RE
16546 .ie n .IP """op_convert_list""" 4
16547 .el .IP \f(CWop_convert_list\fR 4
16548 .IX Xref "op_convert_list"
16549 .IX Item "op_convert_list"
16550 Converts \f(CW\*(C`o\*(C'\fR into a list op if it is not one already, and then converts it
16551 into the specified \f(CW\*(C`type\*(C'\fR, calling its check function, allocating a target if
16552 it needs one, and folding constants.
16553 .Sp
16554 A list\-type op is usually constructed one kid at a time via \f(CW\*(C`newLISTOP\*(C'\fR,
16555 \&\f(CW\*(C`op_prepend_elem\*(C'\fR and \f(CW\*(C`op_append_elem\*(C'\fR. Then finally it is passed to
16556 \&\f(CW\*(C`op_convert_list\*(C'\fR to make it the right type.
16557 .RS 4
16558 .Sp
16559 .Vb 2
16560 \& OP * op_convert_list( I32 optype, I32 flags, OP *o)
16561 \& OP * Perl_op_convert_list(pTHX_ I32 optype, I32 flags, OP *o)
16562 .Ve
16563 .RE
16564 .RS 4
16565 .RE
16566 .ie n .IP """OP_DESC""" 4
16567 .el .IP \f(CWOP_DESC\fR 4
16568 .IX Xref "OP_DESC"
16569 .IX Item "OP_DESC"
16570 Return a short description of the provided OP.
16571 .RS 4
16572 .Sp
16573 .Vb 1
16574 \& const char * OP_DESC(OP *o)
16575 .Ve
16576 .RE
16577 .RS 4
16578 .RE
16579 .ie n .IP """op_force_list""" 4
16580 .el .IP \f(CWop_force_list\fR 4
16581 .IX Xref "op_force_list"
16582 .IX Item "op_force_list"
16583 Promotes o and any siblings to be an \f(CW\*(C`OP_LIST\*(C'\fR if it is not already. If
16584 a new \f(CW\*(C`OP_LIST\*(C'\fR op was created, its first child will be \f(CW\*(C`OP_PUSHMARK\*(C'\fR.
16585 The returned node itself will be nulled, leaving only its children.
16586 .Sp
16587 This is often what you want to do before putting the optree into list
16588 context; as
16589 .Sp
16590 .Vb 1
16591 \& o = op_contextualize(op_force_list(o), G_LIST);
16592 .Ve
16593 .RS 4
16594 .Sp
16595 .Vb 2
16596 \& OP * op_force_list( OP *o)
16597 \& OP * Perl_op_force_list(pTHX_ OP *o)
16598 .Ve
16599 .RE
16600 .RS 4
16601 .RE
16602 .ie n .IP """op_free""" 4
16603 .el .IP \f(CWop_free\fR 4
16604 .IX Xref "op_free"
16605 .IX Item "op_free"
16606 Free an op and its children. Only use this when an op is no longer linked
16607 to from any optree.
16608 .Sp
16609 Remember that any op with \f(CW\*(C`OPf_KIDS\*(C'\fR set is expected to have a valid
16610 \&\f(CW\*(C`op_first\*(C'\fR pointer. If you are attempting to free an op but preserve its
16611 child op, make sure to clear that flag before calling \f(CWop_free()\fR. For
16612 example:
16613 .Sp
16614 .Vb 3
16615 \& OP *kid = o\->op_first; o\->op_first = NULL;
16616 \& o\->op_flags &= ~OPf_KIDS;
16617 \& op_free(o);
16618 .Ve
16619 .RS 4
16620 .Sp
16621 .Vb 2
16622 \& void op_free( OP *arg)
16623 \& void Perl_op_free(pTHX_ OP *arg)
16624 .Ve
16625 .RE
16626 .RS 4
16627 .RE
16628 .ie n .IP """op_linklist""" 4
16629 .el .IP \f(CWop_linklist\fR 4
16630 .IX Xref "op_linklist"
16631 .IX Item "op_linklist"
16632 This function is the implementation of the "LINKLIST" macro. It should
16633 not be called directly.
16634 .RS 4
16635 .Sp
16636 .Vb 2
16637 \& OP * op_linklist( OP *o)
16638 \& OP * Perl_op_linklist(pTHX_ OP *o)
16639 .Ve
16640 .RE
16641 .RS 4
16642 .RE
16643 .ie n .IP """op_lvalue""" 4
16644 .el .IP \f(CWop_lvalue\fR 4
16645 .IX Xref "op_lvalue"
16646 .IX Item "op_lvalue"
16647 NOTE: \f(CW\*(C`op_lvalue\*(C'\fR is \fBexperimental\fR and may change or be
16648 removed without notice.
16649 .Sp
16650 Propagate lvalue ("modifiable") context to an op and its children.
16651 \&\f(CW\*(C`type\*(C'\fR represents the context type, roughly based on the type of op that
16652 would do the modifying, although \f(CWlocal()\fR is represented by \f(CW\*(C`OP_NULL\*(C'\fR,
16653 because it has no op type of its own (it is signalled by a flag on
16654 the lvalue op).
16655 .Sp
16656 This function detects things that can\*(Aqt be modified, such as \f(CW\*(C`$x+1\*(C'\fR, and
16657 generates errors for them. For example, \f(CW\*(C`$x+1 = 2\*(C'\fR would cause it to be
16658 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.
16659 .Sp
16660 It also flags things that need to behave specially in an lvalue context,
16661 such as \f(CW\*(C`$$x = 5\*(C'\fR which might have to vivify a reference in \f(CW$x\fR.
16662 .RS 4
16663 .Sp
16664 .Vb 1
16665 \& OP * op_lvalue(OP *o, I32 type)
16666 .Ve
16667 .RE
16668 .RS 4
16669 .RE
16670 .ie n .IP """OP_NAME""" 4
16671 .el .IP \f(CWOP_NAME\fR 4
16672 .IX Xref "OP_NAME"
16673 .IX Item "OP_NAME"
16674 Return the name of the provided OP. For core ops this looks up the name
16675 from the op_type; for custom ops from the op_ppaddr.
16676 .RS 4
16677 .Sp
16678 .Vb 1
16679 \& const char * OP_NAME(OP *o)
16680 .Ve
16681 .RE
16682 .RS 4
16683 .RE
16684 .ie n .IP """op_null""" 4
16685 .el .IP \f(CWop_null\fR 4
16686 .IX Xref "op_null"
16687 .IX Item "op_null"
16688 Neutralizes an op when it is no longer needed, but is still linked to from
16689 other ops.
16690 .RS 4
16691 .Sp
16692 .Vb 2
16693 \& void op_null( OP *o)
16694 \& void Perl_op_null(pTHX_ OP *o)
16695 .Ve
16696 .RE
16697 .RS 4
16698 .RE
16699 .ie n .IP """op_parent""" 4
16700 .el .IP \f(CWop_parent\fR 4
16701 .IX Xref "op_parent"
16702 .IX Item "op_parent"
16703 Returns the parent OP of \f(CW\*(C`o\*(C'\fR, if it has a parent. Returns \f(CW\*(C`NULL\*(C'\fR otherwise.
16704 .RS 4
16705 .Sp
16706 .Vb 2
16707 \& OP * op_parent(OP *o)
16708 \& OP * Perl_op_parent(OP *o)
16709 .Ve
16710 .RE
16711 .RS 4
16712 .RE
16713 .ie n .IP """op_prepend_elem""" 4
16714 .el .IP \f(CWop_prepend_elem\fR 4
16715 .IX Xref "op_prepend_elem"
16716 .IX Item "op_prepend_elem"
16717 Prepend an item to the list of ops contained directly within a list\-type
16718 op, returning the lengthened list. \f(CW\*(C`first\*(C'\fR is the op to prepend to the
16719 list, and \f(CW\*(C`last\*(C'\fR is the list\-type op. \f(CW\*(C`optype\*(C'\fR specifies the intended
16720 opcode for the list. If \f(CW\*(C`last\*(C'\fR is not already a list of the right type,
16721 it will be upgraded into one. If either \f(CW\*(C`first\*(C'\fR or \f(CW\*(C`last\*(C'\fR is null,
16722 the other is returned unchanged.
16723 .RS 4
16724 .Sp
16725 .Vb 2
16726 \& OP * op_prepend_elem( I32 optype, OP *first, OP *last)
16727 \& OP * Perl_op_prepend_elem(pTHX_ I32 optype, OP *first, OP *last)
16728 .Ve
16729 .RE
16730 .RS 4
16731 .RE
16732 .ie n .IP """op_scope""" 4
16733 .el .IP \f(CWop_scope\fR 4
16734 .IX Xref "op_scope"
16735 .IX Item "op_scope"
16736 NOTE: \f(CW\*(C`op_scope\*(C'\fR is \fBexperimental\fR and may change or be
16737 removed without notice.
16738 .Sp
16739 Wraps up an op tree with some additional ops so that at runtime a dynamic
16740 scope will be created. The original ops run in the new dynamic scope,
16741 and then, provided that they exit normally, the scope will be unwound.
16742 The additional ops used to create and unwind the dynamic scope will
16743 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
16744 instead if the ops are simple enough to not need the full dynamic scope
16745 structure.
16746 .RS 4
16747 .Sp
16748 .Vb 2
16749 \& OP * op_scope( OP *o)
16750 \& OP * Perl_op_scope(pTHX_ OP *o)
16751 .Ve
16752 .RE
16753 .RS 4
16754 .RE
16755 .ie n .IP """op_sibling_splice""" 4
16756 .el .IP \f(CWop_sibling_splice\fR 4
16757 .IX Xref "op_sibling_splice"
16758 .IX Item "op_sibling_splice"
16759 A general function for editing the structure of an existing chain of
16760 op_sibling nodes. By analogy with the perl\-level \f(CWsplice()\fR function, allows
16761 you to delete zero or more sequential nodes, replacing them with zero or
16762 more different nodes. Performs the necessary op_first/op_last
16763 housekeeping on the parent node and op_sibling manipulation on the
16764 children. The last deleted node will be marked as the last node by
16765 updating the op_sibling/op_sibparent or op_moresib field as appropriate.
16766 .Sp
16767 Note that op_next is not manipulated, and nodes are not freed; that is the
16768 responsibility of the caller. It also won\*(Aqt create a new list op for an
16769 empty list etc; use higher\-level functions like \fBop_append_elem()\fR for that.
16770 .Sp
16771 \&\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
16772 the splicing doesn\*(Aqt affect the first or last op in the chain.
16773 .Sp
16774 \&\f(CW\*(C`start\*(C'\fR is the node preceding the first node to be spliced. Node(s)
16775 following it will be deleted, and ops will be inserted after it. If it is
16776 \&\f(CW\*(C`NULL\*(C'\fR, the first node onwards is deleted, and nodes are inserted at the
16777 beginning.
16778 .Sp
16779 \&\f(CW\*(C`del_count\*(C'\fR is the number of nodes to delete. If zero, no nodes are deleted.
16780 If \-1 or greater than or equal to the number of remaining kids, all
16781 remaining kids are deleted.
16782 .Sp
16783 \&\f(CW\*(C`insert\*(C'\fR is the first of a chain of nodes to be inserted in place of the nodes.
16784 If \f(CW\*(C`NULL\*(C'\fR, no nodes are inserted.
16785 .Sp
16786 The head of the chain of deleted ops is returned, or \f(CW\*(C`NULL\*(C'\fR if no ops were
16787 deleted.
16788 .Sp
16789 For example:
16790 .Sp
16791 .Vb 2
16792 \& action before after returns
16793 \& \-\-\-\-\-\- \-\-\-\-\- \-\-\-\-\- \-\-\-\-\-\-\-
16794 \&
16795 \& P P
16796 \& splice(P, A, 2, X\-Y\-Z) | | B\-C
16797 \& A\-B\-C\-D A\-X\-Y\-Z\-D
16798 \&
16799 \& P P
16800 \& splice(P, NULL, 1, X\-Y) | | A
16801 \& A\-B\-C\-D X\-Y\-B\-C\-D
16802 \&
16803 \& P P
16804 \& splice(P, NULL, 3, NULL) | | A\-B\-C
16805 \& A\-B\-C\-D D
16806 \&
16807 \& P P
16808 \& splice(P, B, 0, X\-Y) | | NULL
16809 \& A\-B\-C\-D A\-B\-X\-Y\-C\-D
16810 .Ve
16811 .Sp
16812 For lower\-level direct manipulation of \f(CW\*(C`op_sibparent\*(C'\fR and \f(CW\*(C`op_moresib\*(C'\fR,
16813 see \f(CW"OpMORESIB_set"\fR, \f(CW"OpLASTSIB_set"\fR, \f(CW"OpMAYBESIB_set"\fR.
16814 .RS 4
16815 .Sp
16816 .Vb 4
16817 \& OP * op_sibling_splice( OP *parent, OP *start,
16818 \& int del_count, OP *insert)
16819 \& OP * Perl_op_sibling_splice(pTHX_ OP *parent, OP *start,
16820 \& int del_count, OP *insert)
16821 .Ve
16822 .RE
16823 .RS 4
16824 .RE
16825 .ie n .IP """OP_TYPE_IS""" 4
16826 .el .IP \f(CWOP_TYPE_IS\fR 4
16827 .IX Xref "OP_TYPE_IS"
16828 .IX Item "OP_TYPE_IS"
16829 Returns true if the given OP is not a \f(CW\*(C`NULL\*(C'\fR pointer
16830 and if it is of the given type.
16831 .Sp
16832 The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT\*(C'\fR is also available
16833 as well as \f(CW\*(C`OP_TYPE_IS_NN\*(C'\fR and \f(CW\*(C`OP_TYPE_ISNT_NN\*(C'\fR which elide
16834 the NULL pointer check.
16835 .RS 4
16836 .Sp
16837 .Vb 1
16838 \& bool OP_TYPE_IS(OP *o, Optype type)
16839 .Ve
16840 .RE
16841 .RS 4
16842 .RE
16843 .ie n .IP """OP_TYPE_IS_OR_WAS""" 4
16844 .el .IP \f(CWOP_TYPE_IS_OR_WAS\fR 4
16845 .IX Xref "OP_TYPE_IS_OR_WAS"
16846 .IX Item "OP_TYPE_IS_OR_WAS"
16847 Returns true if the given OP is not a NULL pointer and
16848 if it is of the given type or used to be before being
16849 replaced by an OP of type OP_NULL.
16850 .Sp
16851 The negation of this macro, \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT\*(C'\fR
16852 is also available as well as \f(CW\*(C`OP_TYPE_IS_OR_WAS_NN\*(C'\fR
16853 and \f(CW\*(C`OP_TYPE_ISNT_AND_WASNT_NN\*(C'\fR which elide
16854 the \f(CW\*(C`NULL\*(C'\fR pointer check.
16855 .RS 4
16856 .Sp
16857 .Vb 1
16858 \& bool OP_TYPE_IS_OR_WAS(OP *o, Optype type)
16859 .Ve
16860 .RE
16861 .RS 4
16862 .RE
16863 .ie n .IP """op_wrap_finally""" 4
16864 .el .IP \f(CWop_wrap_finally\fR 4
16865 .IX Xref "op_wrap_finally"
16866 .IX Item "op_wrap_finally"
16867 NOTE: \f(CW\*(C`op_wrap_finally\*(C'\fR is \fBexperimental\fR and may change or be
16868 removed without notice.
16869 .Sp
16870 Wraps the given \f(CW\*(C`block\*(C'\fR optree fragment in its own scoped block, arranging
16871 for the \f(CW\*(C`finally\*(C'\fR optree fragment to be invoked when leaving that block for
16872 any reason. Both optree fragments are consumed and the combined result is
16873 returned.
16874 .RS 4
16875 .Sp
16876 .Vb 2
16877 \& OP * op_wrap_finally( OP *block, OP *finally)
16878 \& OP * Perl_op_wrap_finally(pTHX_ OP *block, OP *finally)
16879 .Ve
16880 .RE
16881 .RS 4
16882 .RE
16883 .ie n .IP """opcode""" 4
16884 .el .IP \f(CWopcode\fR 4
16885 .IX Xref "opcode"
16886 .IX Item "opcode"
16887 An enum of all the legal Perl opcodes, defined in \fIopnames.h\fR
16888 .ie n .IP """OpHAS_SIBLING""" 4
16889 .el .IP \f(CWOpHAS_SIBLING\fR 4
16890 .IX Xref "OpHAS_SIBLING"
16891 .IX Item "OpHAS_SIBLING"
16892 Returns true if \f(CW\*(C`o\*(C'\fR has a sibling
16893 .RS 4
16894 .Sp
16895 .Vb 1
16896 \& bool OpHAS_SIBLING(OP *o)
16897 .Ve
16898 .RE
16899 .RS 4
16900 .RE
16901 .ie n .IP """OpLASTSIB_set""" 4
16902 .el .IP \f(CWOpLASTSIB_set\fR 4
16903 .IX Xref "OpLASTSIB_set"
16904 .IX Item "OpLASTSIB_set"
16905 Marks \f(CW\*(C`o\*(C'\fR as having no further siblings and marks
16906 o as having the specified parent. See also \f(CW"OpMORESIB_set"\fR and
16907 \&\f(CW\*(C`OpMAYBESIB_set\*(C'\fR. For a higher\-level interface, see
16908 \&\f(CW"op_sibling_splice"\fR.
16909 .RS 4
16910 .Sp
16911 .Vb 1
16912 \& void OpLASTSIB_set(OP *o, OP *parent)
16913 .Ve
16914 .RE
16915 .RS 4
16916 .RE
16917 .ie n .IP """OpMAYBESIB_set""" 4
16918 .el .IP \f(CWOpMAYBESIB_set\fR 4
16919 .IX Xref "OpMAYBESIB_set"
16920 .IX Item "OpMAYBESIB_set"
16921 Conditionally does \f(CW\*(C`OpMORESIB_set\*(C'\fR or \f(CW\*(C`OpLASTSIB_set\*(C'\fR depending on whether
16922 \&\f(CW\*(C`sib\*(C'\fR is non\-null. For a higher\-level interface, see \f(CW"op_sibling_splice"\fR.
16923 .RS 4
16924 .Sp
16925 .Vb 1
16926 \& void OpMAYBESIB_set(OP *o, OP *sib, OP *parent)
16927 .Ve
16928 .RE
16929 .RS 4
16930 .RE
16931 .ie n .IP """OpMORESIB_set""" 4
16932 .el .IP \f(CWOpMORESIB_set\fR 4
16933 .IX Xref "OpMORESIB_set"
16934 .IX Item "OpMORESIB_set"
16935 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
16936 and \f(CW"OpMAYBESIB_set"\fR. For a higher\-level interface, see
16937 \&\f(CW"op_sibling_splice"\fR.
16938 .RS 4
16939 .Sp
16940 .Vb 1
16941 \& void OpMORESIB_set(OP *o, OP *sib)
16942 .Ve
16943 .RE
16944 .RS 4
16945 .RE
16946 .ie n .IP """OpSIBLING""" 4
16947 .el .IP \f(CWOpSIBLING\fR 4
16948 .IX Xref "OpSIBLING"
16949 .IX Item "OpSIBLING"
16950 Returns the sibling of \f(CW\*(C`o\*(C'\fR, or \f(CW\*(C`NULL\*(C'\fR if there is no sibling
16951 .RS 4
16952 .Sp
16953 .Vb 1
16954 \& OP* OpSIBLING(OP *o)
16955 .Ve
16956 .RE
16957 .RS 4
16958 .RE
16959 .ie n .IP """optimize_optree""" 4
16960 .el .IP \f(CWoptimize_optree\fR 4
16961 .IX Xref "optimize_optree"
16962 .IX Item "optimize_optree"
16963 This function applies some optimisations to the optree in top\-down order.
16964 It is called before the peephole optimizer, which processes ops in
16965 execution order. Note that \fBfinalize_optree()\fR also does a top\-down scan,
16966 but is called *after* the peephole optimizer.
16967 .RS 4
16968 .Sp
16969 .Vb 2
16970 \& void optimize_optree( OP *o)
16971 \& void Perl_optimize_optree(pTHX_ OP *o)
16972 .Ve
16973 .RE
16974 .RS 4
16975 .RE
16976 .ie n .IP """peep_t""" 4
16977 .el .IP \f(CWpeep_t\fR 4
16978 .IX Item "peep_t"
16979 .PD 0
16980 .ie n .IP """Perl_cpeep_t""" 4
16981 .el .IP \f(CWPerl_cpeep_t\fR 4
16982 .IX Item "Perl_cpeep_t"
16983 .PD
16984 Described in perlguts.
16985 .ie n .IP """PL_opfreehook""" 4
16986 .el .IP \f(CWPL_opfreehook\fR 4
16987 .IX Xref "PL_opfreehook"
16988 .IX Item "PL_opfreehook"
16989 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.
16990 This allows extensions to free any extra attribute they have locally attached to an OP.
16991 It is also assured to first fire for the parent OP and then for its kids.
16992 .Sp
16993 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.
16994 .Sp
16995 On threaded perls, each thread has an independent copy of this variable;
16996 each initialized at creation time with the current value of the creating
16997 thread\*(Aqs copy.
16998 .RS 4
16999 .Sp
17000 .Vb 1
17001 \& Perl_ophook_t PL_opfreehook
17002 .Ve
17003 .RE
17004 .RS 4
17005 .RE
17006 .ie n .IP """PL_peepp""" 4
17007 .el .IP \f(CWPL_peepp\fR 4
17008 .IX Xref "PL_peepp"
17009 .IX Item "PL_peepp"
17010 Pointer to the per\-subroutine peephole optimiser. This is a function
17011 that gets called at the end of compilation of a Perl subroutine (or
17012 equivalently independent piece of Perl code) to perform fixups of
17013 some ops and to perform small\-scale optimisations. The function is
17014 called once for each subroutine that is compiled, and is passed, as sole
17015 parameter, a pointer to the op that is the entry point to the subroutine.
17016 It modifies the op tree in place.
17017 .Sp
17018 The peephole optimiser should never be completely replaced. Rather,
17019 add code to it by wrapping the existing optimiser. The basic way to do
17020 this can be seen in "Compile pass 3: peephole optimization" in perlguts.
17021 If the new code wishes to operate on ops throughout the subroutine\*(Aqs
17022 structure, rather than just at the top level, it is likely to be more
17023 convenient to wrap the "PL_rpeepp" hook.
17024 .Sp
17025 On threaded perls, each thread has an independent copy of this variable;
17026 each initialized at creation time with the current value of the creating
17027 thread\*(Aqs copy.
17028 .RS 4
17029 .Sp
17030 .Vb 1
17031 \& peep_t PL_peepp
17032 .Ve
17033 .RE
17034 .RS 4
17035 .RE
17036 .ie n .IP """PL_rpeepp""" 4
17037 .el .IP \f(CWPL_rpeepp\fR 4
17038 .IX Xref "PL_rpeepp"
17039 .IX Item "PL_rpeepp"
17040 Pointer to the recursive peephole optimiser. This is a function
17041 that gets called at the end of compilation of a Perl subroutine (or
17042 equivalently independent piece of Perl code) to perform fixups of some
17043 ops and to perform small\-scale optimisations. The function is called
17044 once for each chain of ops linked through their \f(CW\*(C`op_next\*(C'\fR fields;
17045 it is recursively called to handle each side chain. It is passed, as
17046 sole parameter, a pointer to the op that is at the head of the chain.
17047 It modifies the op tree in place.
17048 .Sp
17049 The peephole optimiser should never be completely replaced. Rather,
17050 add code to it by wrapping the existing optimiser. The basic way to do
17051 this can be seen in "Compile pass 3: peephole optimization" in perlguts.
17052 If the new code wishes to operate only on ops at a subroutine\*(Aqs top level,
17053 rather than throughout the structure, it is likely to be more convenient
17054 to wrap the "PL_peepp" hook.
17055 .Sp
17056 On threaded perls, each thread has an independent copy of this variable;
17057 each initialized at creation time with the current value of the creating
17058 thread\*(Aqs copy.
17059 .RS 4
17060 .Sp
17061 .Vb 1
17062 \& peep_t PL_rpeepp
17063 .Ve
17064 .RE
17065 .RS 4
17066 .RE
17067 .ie n .IP """PMOP""" 4
17068 .el .IP \f(CWPMOP\fR 4
17069 .IX Item "PMOP"
17070 Described in perlguts.
17071 .ie n .IP """rv2cv_op_cv""" 4
17072 .el .IP \f(CWrv2cv_op_cv\fR 4
17073 .IX Xref "rv2cv_op_cv"
17074 .IX Item "rv2cv_op_cv"
17075 Examines an op, which is expected to identify a subroutine at runtime,
17076 and attempts to determine at compile time which subroutine it identifies.
17077 This is normally used during Perl compilation to determine whether
17078 a prototype can be applied to a function call. \f(CW\*(C`cvop\*(C'\fR is the op
17079 being considered, normally an \f(CW\*(C`rv2cv\*(C'\fR op. A pointer to the identified
17080 subroutine is returned, if it could be determined statically, and a null
17081 pointer is returned if it was not possible to determine statically.
17082 .Sp
17083 Currently, the subroutine can be identified statically if the RV that the
17084 \&\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.
17085 A \f(CW\*(C`gv\*(C'\fR op is suitable if the GV\*(Aqs CV slot is populated. A \f(CW\*(C`const\*(C'\fR op is
17086 suitable if the constant value must be an RV pointing to a CV. Details of
17087 this process may change in future versions of Perl. If the \f(CW\*(C`rv2cv\*(C'\fR op
17088 has the \f(CW\*(C`OPpENTERSUB_AMPER\*(C'\fR flag set then no attempt is made to identify
17089 the subroutine statically: this flag is used to suppress compile\-time
17090 magic on a subroutine call, forcing it to use default runtime behaviour.
17091 .Sp
17092 If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_MARK_EARLY\*(C'\fR set, then the handling
17093 of a GV reference is modified. If a GV was examined and its CV slot was
17094 found to be empty, then the \f(CW\*(C`gv\*(C'\fR op has the \f(CW\*(C`OPpEARLY_CV\*(C'\fR flag set.
17095 If the op is not optimised away, and the CV slot is later populated with
17096 a subroutine having a prototype, that flag eventually triggers the warning
17097 "called too early to check prototype".
17098 .Sp
17099 If \f(CW\*(C`flags\*(C'\fR has the bit \f(CW\*(C`RV2CVOPCV_RETURN_NAME_GV\*(C'\fR set, then instead
17100 of returning a pointer to the subroutine it returns a pointer to the
17101 GV giving the most appropriate name for the subroutine in this context.
17102 Normally this is just the \f(CW\*(C`CvGV\*(C'\fR of the subroutine, but for an anonymous
17103 (\f(CW\*(C`CvANON\*(C'\fR) subroutine that is referenced through a GV it will be the
17104 referencing GV. The resulting \f(CW\*(C`GV*\*(C'\fR is cast to \f(CW\*(C`CV*\*(C'\fR to be returned.
17105 A null pointer is returned as usual if there is no statically\-determinable
17106 subroutine.
17107 .RS 4
17108 .Sp
17109 .Vb 2
17110 \& CV * rv2cv_op_cv( OP *cvop, U32 flags)
17111 \& CV * Perl_rv2cv_op_cv(pTHX_ OP *cvop, U32 flags)
17112 .Ve
17113 .RE
17114 .RS 4
17115 .RE
17116 .ie n .IP """UNOP""" 4
17117 .el .IP \f(CWUNOP\fR 4
17118 .IX Item "UNOP"
17119 .PD 0
17120 .ie n .IP """XOP""" 4
17121 .el .IP \f(CWXOP\fR 4
17122 .IX Item "XOP"
17123 .PD
17124 Described in perlguts.
17125 .SH "Pack and Unpack"
17126 .IX Header "Pack and Unpack"
17127 .ie n .IP """packlist""" 4
17128 .el .IP \f(CWpacklist\fR 4
17129 .IX Xref "packlist"
17130 .IX Item "packlist"
17131 The engine implementing \f(CWpack()\fR Perl function.
17132 .RS 4
17133 .Sp
17134 .Vb 6
17135 \& void packlist( SV *cat, const char *pat,
17136 \& const char *patend, SV **beglist,
17137 \& SV **endlist)
17138 \& void Perl_packlist(pTHX_ SV *cat, const char *pat,
17139 \& const char *patend, SV **beglist,
17140 \& SV **endlist)
17141 .Ve
17142 .RE
17143 .RS 4
17144 .RE
17145 .ie n .IP """unpackstring""" 4
17146 .el .IP \f(CWunpackstring\fR 4
17147 .IX Xref "unpackstring"
17148 .IX Item "unpackstring"
17149 The engine implementing the \f(CWunpack()\fR Perl function.
17150 .Sp
17151 Using the template \f(CW\*(C`pat..patend\*(C'\fR, this function unpacks the string
17152 \&\f(CW\*(C`s..strend\*(C'\fR into a number of mortal SVs, which it pushes onto the perl
17153 argument (\f(CW@_\fR) stack (so you will need to issue a \f(CW\*(C`PUTBACK\*(C'\fR before and
17154 \&\f(CW\*(C`SPAGAIN\*(C'\fR after the call to this function). It returns the number of
17155 pushed elements.
17156 .Sp
17157 The \f(CW\*(C`strend\*(C'\fR and \f(CW\*(C`patend\*(C'\fR pointers should point to the byte following the
17158 last character of each string.
17159 .Sp
17160 Although this function returns its values on the perl argument stack, it
17161 doesn\*(Aqt take any parameters from that stack (and thus in particular
17162 there\*(Aqs no need to do a \f(CW\*(C`PUSHMARK\*(C'\fR before calling it, unlike "call_pv" for
17163 example).
17164 .RS 4
17165 .Sp
17166 .Vb 8
17167 \& SSize_t unpackstring( const char *pat,
17168 \& const char *patend,
17169 \& const char *s,
17170 \& const char *strend, U32 flags)
17171 \& SSize_t Perl_unpackstring(pTHX_ const char *pat,
17172 \& const char *patend,
17173 \& const char *s,
17174 \& const char *strend, U32 flags)
17175 .Ve
17176 .RE
17177 .RS 4
17178 .RE
17179 .SH "Pad Data Structures"
17180 .IX Xref "SVs_PADSTALE"
17181 .IX Header "Pad Data Structures"
17182 .ie n .IP """CvPADLIST""" 4
17183 .el .IP \f(CWCvPADLIST\fR 4
17184 .IX Xref "CvPADLIST"
17185 .IX Item "CvPADLIST"
17186 NOTE: \f(CW\*(C`CvPADLIST\*(C'\fR is \fBexperimental\fR and may change or be
17187 removed without notice.
17188 .Sp
17189 CV\*(Aqs can have CvPADLIST(cv) set to point to a PADLIST. This is the CV\*(Aqs
17190 scratchpad, which stores lexical variables and opcode temporary and
17191 per\-thread values.
17192 .Sp
17193 For these purposes "formats" are a kind\-of CV; eval""s are too (except they\*(Aqre
17194 not callable at will and are always thrown away after the eval"" is done
17195 executing). Require\*(Aqd files are simply evals without any outer lexical
17196 scope.
17197 .Sp
17198 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,
17199 but that is really the callers pad (a slot of which is allocated by
17200 every entersub). Do not get or set \f(CW\*(C`CvPADLIST\*(C'\fR if a CV is an XSUB (as
17201 determined by \f(CWCvISXSUB()\fR), \f(CW\*(C`CvPADLIST\*(C'\fR slot is reused for a different
17202 internal purpose in XSUBs.
17203 .Sp
17204 The PADLIST has a C array where pads are stored.
17205 .Sp
17206 The 0th entry of the PADLIST is a PADNAMELIST
17207 which represents the "names" or rather
17208 the "static type information" for lexicals. The individual elements of a
17209 PADNAMELIST are PADNAMEs. Future
17210 refactorings might stop the PADNAMELIST from being stored in the PADLIST\*(Aqs
17211 array, so don\*(Aqt rely on it. See "PadlistNAMES".
17212 .Sp
17213 The CvDEPTH\*(Aqth entry of a PADLIST is a PAD (an AV) which is the stack frame
17214 at that depth of recursion into the CV. The 0th slot of a frame AV is an
17215 AV which is \f(CW@_\fR. Other entries are storage for variables and op targets.
17216 .Sp
17217 Iterating over the PADNAMELIST iterates over all possible pad
17218 items. Pad slots for targets (\f(CW\*(C`SVs_PADTMP\*(C'\fR)
17219 and GVs end up having &PL_padname_undef "names", while slots for constants
17220 have \f(CW&PL_padname_const\fR "names" (see \f(CW"pad_alloc"\fR). That
17221 \&\f(CW&PL_padname_undef\fR
17222 and \f(CW&PL_padname_const\fR are used is an implementation detail subject to
17223 change. To test for them, use \f(CW\*(C`!PadnamePV(name)\*(C'\fR and
17224 \&\f(CW\*(C`PadnamePV(name)\ &&\ !PadnameLEN(name)\*(C'\fR, respectively.
17225 .Sp
17226 Only \f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variable slots get valid names.
17227 The rest are op targets/GVs/constants which are statically allocated
17228 or resolved at compile time. These don\*(Aqt have names by which they
17229 can be looked up from Perl code at run time through eval"" the way
17230 \&\f(CW\*(C`my\*(C'\fR/\f(CW\*(C`our\*(C'\fR variables can be. Since they can\*(Aqt be looked up by "name"
17231 but only by their index allocated at compile time (which is usually
17232 in \f(CW\*(C`PL_op\->op_targ\*(C'\fR), wasting a name SV for them doesn\*(Aqt make sense.
17233 .Sp
17234 The pad names in the PADNAMELIST have their PV holding the name of
17235 the variable. The \f(CW\*(C`COP_SEQ_RANGE_LOW\*(C'\fR and \f(CW\*(C`_HIGH\*(C'\fR fields form a range
17236 (low+1..high inclusive) of cop_seq numbers for which the name is
17237 valid. During compilation, these fields may hold the special value
17238 PERL_PADSEQ_INTRO to indicate various stages:
17239 .Sp
17240 .Vb 8
17241 \& COP_SEQ_RANGE_LOW _HIGH
17242 \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-
17243 \& PERL_PADSEQ_INTRO 0 variable not yet introduced:
17244 \& { my ($x
17245 \& valid\-seq# PERL_PADSEQ_INTRO variable in scope:
17246 \& { my ($x);
17247 \& valid\-seq# valid\-seq# compilation of scope complete:
17248 \& { my ($x); .... }
17249 .Ve
17250 .Sp
17251 When a lexical var hasn\*(Aqt yet been introduced, it already exists from the
17252 perspective of duplicate declarations, but not for variable lookups, e.g.
17253 .Sp
17254 .Vb 2
17255 \& my ($x, $x); # \*(Aq"my" variable $x masks earlier declaration\*(Aq
17256 \& my $x = $x; # equal to my $x = $::x;
17257 .Ve
17258 .Sp
17259 For typed lexicals \f(CW\*(C`PadnameTYPE\*(C'\fR points at the type stash. For \f(CW\*(C`our\*(C'\fR
17260 lexicals, \f(CW\*(C`PadnameOURSTASH\*(C'\fR points at the stash of the associated global (so
17261 that duplicate \f(CW\*(C`our\*(C'\fR declarations in the same package can be detected).
17262 \&\f(CW\*(C`PadnameGEN\*(C'\fR is sometimes used to store the generation number during
17263 compilation.
17264 .Sp
17265 If \f(CW\*(C`PadnameOUTER\*(C'\fR is set on the pad name, then that slot in the frame AV
17266 is a REFCNT\*(Aqed reference to a lexical from "outside". Such entries
17267 are sometimes referred to as \*(Aqfake\*(Aq. In this case, the name does not
17268 use \*(Aqlow\*(Aq and \*(Aqhigh\*(Aq to store a cop_seq range, since it is in scope
17269 throughout. Instead \*(Aqhigh\*(Aq stores some flags containing info about
17270 the real lexical (is it declared in an anon, and is it capable of being
17271 instantiated multiple times?), and for fake ANONs, \*(Aqlow\*(Aq contains the index
17272 within the parent\*(Aqs pad where the lexical\*(Aqs value is stored, to make
17273 cloning quicker.
17274 .Sp
17275 If the \*(Aqname\*(Aq is \f(CW\*(C`&\*(C'\fR the corresponding entry in the PAD
17276 is a CV representing a possible closure.
17277 .Sp
17278 Note that formats are treated as anon subs, and are cloned each time
17279 write is called (if necessary).
17280 .Sp
17281 The flag \f(CW\*(C`SVs_PADSTALE\*(C'\fR is cleared on lexicals each time the \f(CWmy()\fR is executed,
17282 and set on scope exit. This allows the
17283 \&\f(CW"Variable $x is not available"\fR warning
17284 to be generated in evals, such as
17285 .Sp
17286 .Vb 1
17287 \& { my $x = 1; sub f { eval \*(Aq$x\*(Aq} } f();
17288 .Ve
17289 .Sp
17290 For state vars, \f(CW\*(C`SVs_PADSTALE\*(C'\fR is overloaded to mean \*(Aqnot yet initialised\*(Aq,
17291 but this internal state is stored in a separate pad entry.
17292 .RS 4
17293 .Sp
17294 .Vb 1
17295 \& PADLIST * CvPADLIST(CV *cv)
17296 .Ve
17297 .RE
17298 .RS 4
17299 .RE
17300 .ie n .IP """pad_add_name_pvs""" 4
17301 .el .IP \f(CWpad_add_name_pvs\fR 4
17302 .IX Xref "pad_add_name_pvs"
17303 .IX Item "pad_add_name_pvs"
17304 Exactly like "pad_add_name_pvn", but takes a literal string
17305 instead of a string/length pair.
17306 .RS 4
17307 .Sp
17308 .Vb 2
17309 \& PADOFFSET pad_add_name_pvs("name", U32 flags, HV *typestash,
17310 \& HV *ourstash)
17311 .Ve
17312 .RE
17313 .RS 4
17314 .RE
17315 .ie n .IP """pad_new""" 4
17316 .el .IP \f(CWpad_new\fR 4
17317 .IX Xref "pad_new"
17318 .IX Item "pad_new"
17319 Create a new padlist, updating the global variables for the
17320 currently\-compiling padlist to point to the new padlist. The following
17321 flags can be OR\*(Aqed together:
17322 .Sp
17323 .Vb 3
17324 \& padnew_CLONE this pad is for a cloned CV
17325 \& padnew_SAVE save old globals on the save stack
17326 \& padnew_SAVESUB also save extra stuff for start of sub
17327 .Ve
17328 .RS 4
17329 .Sp
17330 .Vb 2
17331 \& PADLIST * pad_new( int flags)
17332 \& PADLIST * Perl_pad_new(pTHX_ int flags)
17333 .Ve
17334 .RE
17335 .RS 4
17336 .RE
17337 .ie n .IP """PadARRAY""" 4
17338 .el .IP \f(CWPadARRAY\fR 4
17339 .IX Xref "PadARRAY"
17340 .IX Item "PadARRAY"
17341 NOTE: \f(CW\*(C`PadARRAY\*(C'\fR is \fBexperimental\fR and may change or be
17342 removed without notice.
17343 .Sp
17344 The C array of pad entries.
17345 .RS 4
17346 .Sp
17347 .Vb 1
17348 \& SV ** PadARRAY(PAD * pad)
17349 .Ve
17350 .RE
17351 .RS 4
17352 .RE
17353 .ie n .IP """PadlistARRAY""" 4
17354 .el .IP \f(CWPadlistARRAY\fR 4
17355 .IX Xref "PadlistARRAY"
17356 .IX Item "PadlistARRAY"
17357 NOTE: \f(CW\*(C`PadlistARRAY\*(C'\fR is \fBexperimental\fR and may change or be
17358 removed without notice.
17359 .Sp
17360 The C array of a padlist, containing the pads. Only subscript it with
17361 numbers >= 1, as the 0th entry is not guaranteed to remain usable.
17362 .RS 4
17363 .Sp
17364 .Vb 1
17365 \& PAD ** PadlistARRAY(PADLIST * padlist)
17366 .Ve
17367 .RE
17368 .RS 4
17369 .RE
17370 .ie n .IP """PadlistMAX""" 4
17371 .el .IP \f(CWPadlistMAX\fR 4
17372 .IX Xref "PadlistMAX"
17373 .IX Item "PadlistMAX"
17374 NOTE: \f(CW\*(C`PadlistMAX\*(C'\fR is \fBexperimental\fR and may change or be
17375 removed without notice.
17376 .Sp
17377 The index of the last allocated space in the padlist. Note that the last
17378 pad may be in an earlier slot. Any entries following it will be \f(CW\*(C`NULL\*(C'\fR in
17379 that case.
17380 .RS 4
17381 .Sp
17382 .Vb 1
17383 \& SSize_t PadlistMAX(PADLIST * padlist)
17384 .Ve
17385 .RE
17386 .RS 4
17387 .RE
17388 .ie n .IP """PadlistNAMES""" 4
17389 .el .IP \f(CWPadlistNAMES\fR 4
17390 .IX Xref "PadlistNAMES"
17391 .IX Item "PadlistNAMES"
17392 NOTE: \f(CW\*(C`PadlistNAMES\*(C'\fR is \fBexperimental\fR and may change or be
17393 removed without notice.
17394 .Sp
17395 The names associated with pad entries.
17396 .RS 4
17397 .Sp
17398 .Vb 1
17399 \& PADNAMELIST * PadlistNAMES(PADLIST * padlist)
17400 .Ve
17401 .RE
17402 .RS 4
17403 .RE
17404 .ie n .IP """PadlistNAMESARRAY""" 4
17405 .el .IP \f(CWPadlistNAMESARRAY\fR 4
17406 .IX Xref "PadlistNAMESARRAY"
17407 .IX Item "PadlistNAMESARRAY"
17408 NOTE: \f(CW\*(C`PadlistNAMESARRAY\*(C'\fR is \fBexperimental\fR and may change or be
17409 removed without notice.
17410 .Sp
17411 The C array of pad names.
17412 .RS 4
17413 .Sp
17414 .Vb 1
17415 \& PADNAME ** PadlistNAMESARRAY(PADLIST * padlist)
17416 .Ve
17417 .RE
17418 .RS 4
17419 .RE
17420 .ie n .IP """PadlistNAMESMAX""" 4
17421 .el .IP \f(CWPadlistNAMESMAX\fR 4
17422 .IX Xref "PadlistNAMESMAX"
17423 .IX Item "PadlistNAMESMAX"
17424 NOTE: \f(CW\*(C`PadlistNAMESMAX\*(C'\fR is \fBexperimental\fR and may change or be
17425 removed without notice.
17426 .Sp
17427 The index of the last pad name.
17428 .RS 4
17429 .Sp
17430 .Vb 1
17431 \& SSize_t PadlistNAMESMAX(PADLIST * padlist)
17432 .Ve
17433 .RE
17434 .RS 4
17435 .RE
17436 .ie n .IP """PadlistREFCNT""" 4
17437 .el .IP \f(CWPadlistREFCNT\fR 4
17438 .IX Xref "PadlistREFCNT"
17439 .IX Item "PadlistREFCNT"
17440 NOTE: \f(CW\*(C`PadlistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
17441 removed without notice.
17442 .Sp
17443 The reference count of the padlist. Currently this is always 1.
17444 .RS 4
17445 .Sp
17446 .Vb 1
17447 \& U32 PadlistREFCNT(PADLIST * padlist)
17448 .Ve
17449 .RE
17450 .RS 4
17451 .RE
17452 .ie n .IP """PadMAX""" 4
17453 .el .IP \f(CWPadMAX\fR 4
17454 .IX Xref "PadMAX"
17455 .IX Item "PadMAX"
17456 NOTE: \f(CW\*(C`PadMAX\*(C'\fR is \fBexperimental\fR and may change or be
17457 removed without notice.
17458 .Sp
17459 The index of the last pad entry.
17460 .RS 4
17461 .Sp
17462 .Vb 1
17463 \& SSize_t PadMAX(PAD * pad)
17464 .Ve
17465 .RE
17466 .RS 4
17467 .RE
17468 .ie n .IP """PadnameLEN""" 4
17469 .el .IP \f(CWPadnameLEN\fR 4
17470 .IX Xref "PadnameLEN"
17471 .IX Item "PadnameLEN"
17472 NOTE: \f(CW\*(C`PadnameLEN\*(C'\fR is \fBexperimental\fR and may change or be
17473 removed without notice.
17474 .Sp
17475 The length of the name.
17476 .RS 4
17477 .Sp
17478 .Vb 1
17479 \& STRLEN PadnameLEN(PADNAME * pn)
17480 .Ve
17481 .RE
17482 .RS 4
17483 .RE
17484 .ie n .IP """PadnamelistARRAY""" 4
17485 .el .IP \f(CWPadnamelistARRAY\fR 4
17486 .IX Xref "PadnamelistARRAY"
17487 .IX Item "PadnamelistARRAY"
17488 NOTE: \f(CW\*(C`PadnamelistARRAY\*(C'\fR is \fBexperimental\fR and may change or be
17489 removed without notice.
17490 .Sp
17491 The C array of pad names.
17492 .RS 4
17493 .Sp
17494 .Vb 1
17495 \& PADNAME ** PadnamelistARRAY(PADNAMELIST * pnl)
17496 .Ve
17497 .RE
17498 .RS 4
17499 .RE
17500 .ie n .IP """PadnamelistMAX""" 4
17501 .el .IP \f(CWPadnamelistMAX\fR 4
17502 .IX Xref "PadnamelistMAX"
17503 .IX Item "PadnamelistMAX"
17504 NOTE: \f(CW\*(C`PadnamelistMAX\*(C'\fR is \fBexperimental\fR and may change or be
17505 removed without notice.
17506 .Sp
17507 The index of the last pad name.
17508 .RS 4
17509 .Sp
17510 .Vb 1
17511 \& SSize_t PadnamelistMAX(PADNAMELIST * pnl)
17512 .Ve
17513 .RE
17514 .RS 4
17515 .RE
17516 .ie n .IP """PadnamelistREFCNT""" 4
17517 .el .IP \f(CWPadnamelistREFCNT\fR 4
17518 .IX Xref "PadnamelistREFCNT"
17519 .IX Item "PadnamelistREFCNT"
17520 NOTE: \f(CW\*(C`PadnamelistREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
17521 removed without notice.
17522 .Sp
17523 The reference count of the pad name list.
17524 .RS 4
17525 .Sp
17526 .Vb 1
17527 \& SSize_t PadnamelistREFCNT(PADNAMELIST * pnl)
17528 .Ve
17529 .RE
17530 .RS 4
17531 .RE
17532 .ie n .IP """PadnamelistREFCNT_dec""" 4
17533 .el .IP \f(CWPadnamelistREFCNT_dec\fR 4
17534 .IX Xref "PadnamelistREFCNT_dec"
17535 .IX Item "PadnamelistREFCNT_dec"
17536 NOTE: \f(CW\*(C`PadnamelistREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be
17537 removed without notice.
17538 .Sp
17539 Lowers the reference count of the pad name list.
17540 .RS 4
17541 .Sp
17542 .Vb 1
17543 \& void PadnamelistREFCNT_dec(PADNAMELIST * pnl)
17544 .Ve
17545 .RE
17546 .RS 4
17547 .RE
17548 .ie n .IP """PadnamePV""" 4
17549 .el .IP \f(CWPadnamePV\fR 4
17550 .IX Xref "PadnamePV"
17551 .IX Item "PadnamePV"
17552 NOTE: \f(CW\*(C`PadnamePV\*(C'\fR is \fBexperimental\fR and may change or be
17553 removed without notice.
17554 .Sp
17555 The name stored in the pad name struct. This returns \f(CW\*(C`NULL\*(C'\fR for a target
17556 slot.
17557 .RS 4
17558 .Sp
17559 .Vb 1
17560 \& char * PadnamePV(PADNAME * pn)
17561 .Ve
17562 .RE
17563 .RS 4
17564 .RE
17565 .ie n .IP """PadnameREFCNT""" 4
17566 .el .IP \f(CWPadnameREFCNT\fR 4
17567 .IX Xref "PadnameREFCNT"
17568 .IX Item "PadnameREFCNT"
17569 NOTE: \f(CW\*(C`PadnameREFCNT\*(C'\fR is \fBexperimental\fR and may change or be
17570 removed without notice.
17571 .Sp
17572 The reference count of the pad name.
17573 .RS 4
17574 .Sp
17575 .Vb 1
17576 \& SSize_t PadnameREFCNT(PADNAME * pn)
17577 .Ve
17578 .RE
17579 .RS 4
17580 .RE
17581 .ie n .IP """PadnameREFCNT_dec""" 4
17582 .el .IP \f(CWPadnameREFCNT_dec\fR 4
17583 .IX Xref "PadnameREFCNT_dec"
17584 .IX Item "PadnameREFCNT_dec"
17585 NOTE: \f(CW\*(C`PadnameREFCNT_dec\*(C'\fR is \fBexperimental\fR and may change or be
17586 removed without notice.
17587 .Sp
17588 Lowers the reference count of the pad name.
17589 .RS 4
17590 .Sp
17591 .Vb 1
17592 \& void PadnameREFCNT_dec(PADNAME * pn)
17593 .Ve
17594 .RE
17595 .RS 4
17596 .RE
17597 .ie n .IP """PadnameREFCNT_inc""" 4
17598 .el .IP \f(CWPadnameREFCNT_inc\fR 4
17599 .IX Xref "PadnameREFCNT_inc"
17600 .IX Item "PadnameREFCNT_inc"
17601 NOTE: \f(CW\*(C`PadnameREFCNT_inc\*(C'\fR is \fBexperimental\fR and may change or be
17602 removed without notice.
17603 .Sp
17604 Increases the reference count of the pad name. Returns the pad name itself.
17605 .RS 4
17606 .Sp
17607 .Vb 1
17608 \& PADNAME * PadnameREFCNT_inc(PADNAME * pn)
17609 .Ve
17610 .RE
17611 .RS 4
17612 .RE
17613 .ie n .IP """PadnameSV""" 4
17614 .el .IP \f(CWPadnameSV\fR 4
17615 .IX Xref "PadnameSV"
17616 .IX Item "PadnameSV"
17617 NOTE: \f(CW\*(C`PadnameSV\*(C'\fR is \fBexperimental\fR and may change or be
17618 removed without notice.
17619 .Sp
17620 Returns the pad name as a mortal SV.
17621 .RS 4
17622 .Sp
17623 .Vb 1
17624 \& SV * PadnameSV(PADNAME * pn)
17625 .Ve
17626 .RE
17627 .RS 4
17628 .RE
17629 .ie n .IP """PadnameUTF8""" 4
17630 .el .IP \f(CWPadnameUTF8\fR 4
17631 .IX Xref "PadnameUTF8"
17632 .IX Item "PadnameUTF8"
17633 NOTE: \f(CW\*(C`PadnameUTF8\*(C'\fR is \fBexperimental\fR and may change or be
17634 removed without notice.
17635 .Sp
17636 Whether PadnamePV is in UTF\-8. Currently, this is always true.
17637 .RS 4
17638 .Sp
17639 .Vb 1
17640 \& bool PadnameUTF8(PADNAME * pn)
17641 .Ve
17642 .RE
17643 .RS 4
17644 .RE
17645 .ie n .IP """PL_comppad""" 4
17646 .el .IP \f(CWPL_comppad\fR 4
17647 .IX Xref "PL_comppad"
17648 .IX Item "PL_comppad"
17649 NOTE: \f(CW\*(C`PL_comppad\*(C'\fR is \fBexperimental\fR and may change or be
17650 removed without notice.
17651 .Sp
17652 During compilation, this points to the array containing the values
17653 part of the pad for the currently\-compiling code. (At runtime a CV may
17654 have many such value arrays; at compile time just one is constructed.)
17655 At runtime, this points to the array containing the currently\-relevant
17656 values for the pad for the currently\-executing code.
17657 .ie n .IP """PL_comppad_name""" 4
17658 .el .IP \f(CWPL_comppad_name\fR 4
17659 .IX Xref "PL_comppad_name"
17660 .IX Item "PL_comppad_name"
17661 NOTE: \f(CW\*(C`PL_comppad_name\*(C'\fR is \fBexperimental\fR and may change or be
17662 removed without notice.
17663 .Sp
17664 During compilation, this points to the array containing the names part
17665 of the pad for the currently\-compiling code.
17666 .ie n .IP """PL_curpad""" 4
17667 .el .IP \f(CWPL_curpad\fR 4
17668 .IX Xref "PL_curpad"
17669 .IX Item "PL_curpad"
17670 NOTE: \f(CW\*(C`PL_curpad\*(C'\fR is \fBexperimental\fR and may change or be
17671 removed without notice.
17672 .Sp
17673 Points directly to the body of the "PL_comppad" array.
17674 (I.e., this is \f(CWPadARRAY(PL_comppad)\fR.)
17675 .ie n .IP """SVs_PADMY""" 4
17676 .el .IP \f(CWSVs_PADMY\fR 4
17677 .IX Item "SVs_PADMY"
17678 .PD 0
17679 .ie n .IP """SVs_PADTMP""" 4
17680 .el .IP \f(CWSVs_PADTMP\fR 4
17681 .IX Item "SVs_PADTMP"
17682 .PD
17683 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`SVs_PADMY\*(C'\fR
17684 from a future release of Perl. Do not use it for
17685 new code; remove it from existing code.
17686 .Sp
17687 Described in perlguts.
17688 .SH "Password and Group access"
17689 .IX Header "Password and Group access"
17690 .ie n .IP """GRPASSWD""" 4
17691 .el .IP \f(CWGRPASSWD\fR 4
17692 .IX Xref "GRPASSWD"
17693 .IX Item "GRPASSWD"
17694 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct group\*(C'\fR
17695 in \fIgrp.h\fR contains \f(CW\*(C`gr_passwd\*(C'\fR.
17696 .ie n .IP """HAS_ENDGRENT""" 4
17697 .el .IP \f(CWHAS_ENDGRENT\fR 4
17698 .IX Xref "HAS_ENDGRENT"
17699 .IX Item "HAS_ENDGRENT"
17700 This symbol, if defined, indicates that the getgrent routine is
17701 available for finalizing sequential access of the group database.
17702 .ie n .IP """HAS_ENDGRENT_R""" 4
17703 .el .IP \f(CWHAS_ENDGRENT_R\fR 4
17704 .IX Xref "HAS_ENDGRENT_R"
17705 .IX Item "HAS_ENDGRENT_R"
17706 This symbol, if defined, indicates that the \f(CW\*(C`endgrent_r\*(C'\fR routine
17707 is available to endgrent re\-entrantly.
17708 .ie n .IP """HAS_ENDPWENT""" 4
17709 .el .IP \f(CWHAS_ENDPWENT\fR 4
17710 .IX Xref "HAS_ENDPWENT"
17711 .IX Item "HAS_ENDPWENT"
17712 This symbol, if defined, indicates that the \f(CW\*(C`endpwent\*(C'\fR routine is
17713 available for finalizing sequential access of the passwd database.
17714 .ie n .IP """HAS_ENDPWENT_R""" 4
17715 .el .IP \f(CWHAS_ENDPWENT_R\fR 4
17716 .IX Xref "HAS_ENDPWENT_R"
17717 .IX Item "HAS_ENDPWENT_R"
17718 This symbol, if defined, indicates that the \f(CW\*(C`endpwent_r\*(C'\fR routine
17719 is available to endpwent re\-entrantly.
17720 .ie n .IP """HAS_GETGRENT""" 4
17721 .el .IP \f(CWHAS_GETGRENT\fR 4
17722 .IX Xref "HAS_GETGRENT"
17723 .IX Item "HAS_GETGRENT"
17724 This symbol, if defined, indicates that the \f(CW\*(C`getgrent\*(C'\fR routine is
17725 available for sequential access of the group database.
17726 .ie n .IP """HAS_GETGRENT_R""" 4
17727 .el .IP \f(CWHAS_GETGRENT_R\fR 4
17728 .IX Xref "HAS_GETGRENT_R"
17729 .IX Item "HAS_GETGRENT_R"
17730 This symbol, if defined, indicates that the \f(CW\*(C`getgrent_r\*(C'\fR routine
17731 is available to getgrent re\-entrantly.
17732 .ie n .IP """HAS_GETPWENT""" 4
17733 .el .IP \f(CWHAS_GETPWENT\fR 4
17734 .IX Xref "HAS_GETPWENT"
17735 .IX Item "HAS_GETPWENT"
17736 This symbol, if defined, indicates that the \f(CW\*(C`getpwent\*(C'\fR routine is
17737 available for sequential access of the passwd database.
17738 If this is not available, the older \f(CWgetpw()\fR function may be available.
17739 .ie n .IP """HAS_GETPWENT_R""" 4
17740 .el .IP \f(CWHAS_GETPWENT_R\fR 4
17741 .IX Xref "HAS_GETPWENT_R"
17742 .IX Item "HAS_GETPWENT_R"
17743 This symbol, if defined, indicates that the \f(CW\*(C`getpwent_r\*(C'\fR routine
17744 is available to getpwent re\-entrantly.
17745 .ie n .IP """HAS_SETGRENT""" 4
17746 .el .IP \f(CWHAS_SETGRENT\fR 4
17747 .IX Xref "HAS_SETGRENT"
17748 .IX Item "HAS_SETGRENT"
17749 This symbol, if defined, indicates that the \f(CW\*(C`setgrent\*(C'\fR routine is
17750 available for initializing sequential access of the group database.
17751 .ie n .IP """HAS_SETGRENT_R""" 4
17752 .el .IP \f(CWHAS_SETGRENT_R\fR 4
17753 .IX Xref "HAS_SETGRENT_R"
17754 .IX Item "HAS_SETGRENT_R"
17755 This symbol, if defined, indicates that the \f(CW\*(C`setgrent_r\*(C'\fR routine
17756 is available to setgrent re\-entrantly.
17757 .ie n .IP """HAS_SETPWENT""" 4
17758 .el .IP \f(CWHAS_SETPWENT\fR 4
17759 .IX Xref "HAS_SETPWENT"
17760 .IX Item "HAS_SETPWENT"
17761 This symbol, if defined, indicates that the \f(CW\*(C`setpwent\*(C'\fR routine is
17762 available for initializing sequential access of the passwd database.
17763 .ie n .IP """HAS_SETPWENT_R""" 4
17764 .el .IP \f(CWHAS_SETPWENT_R\fR 4
17765 .IX Xref "HAS_SETPWENT_R"
17766 .IX Item "HAS_SETPWENT_R"
17767 This symbol, if defined, indicates that the \f(CW\*(C`setpwent_r\*(C'\fR routine
17768 is available to setpwent re\-entrantly.
17769 .ie n .IP """PWAGE""" 4
17770 .el .IP \f(CWPWAGE\fR 4
17771 .IX Xref "PWAGE"
17772 .IX Item "PWAGE"
17773 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17774 contains \f(CW\*(C`pw_age\*(C'\fR.
17775 .ie n .IP """PWCHANGE""" 4
17776 .el .IP \f(CWPWCHANGE\fR 4
17777 .IX Xref "PWCHANGE"
17778 .IX Item "PWCHANGE"
17779 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17780 contains \f(CW\*(C`pw_change\*(C'\fR.
17781 .ie n .IP """PWCLASS""" 4
17782 .el .IP \f(CWPWCLASS\fR 4
17783 .IX Xref "PWCLASS"
17784 .IX Item "PWCLASS"
17785 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17786 contains \f(CW\*(C`pw_class\*(C'\fR.
17787 .ie n .IP """PWCOMMENT""" 4
17788 .el .IP \f(CWPWCOMMENT\fR 4
17789 .IX Xref "PWCOMMENT"
17790 .IX Item "PWCOMMENT"
17791 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17792 contains \f(CW\*(C`pw_comment\*(C'\fR.
17793 .ie n .IP """PWEXPIRE""" 4
17794 .el .IP \f(CWPWEXPIRE\fR 4
17795 .IX Xref "PWEXPIRE"
17796 .IX Item "PWEXPIRE"
17797 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17798 contains \f(CW\*(C`pw_expire\*(C'\fR.
17799 .ie n .IP """PWGECOS""" 4
17800 .el .IP \f(CWPWGECOS\fR 4
17801 .IX Xref "PWGECOS"
17802 .IX Item "PWGECOS"
17803 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17804 contains \f(CW\*(C`pw_gecos\*(C'\fR.
17805 .ie n .IP """PWPASSWD""" 4
17806 .el .IP \f(CWPWPASSWD\fR 4
17807 .IX Xref "PWPASSWD"
17808 .IX Item "PWPASSWD"
17809 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17810 contains \f(CW\*(C`pw_passwd\*(C'\fR.
17811 .ie n .IP """PWQUOTA""" 4
17812 .el .IP \f(CWPWQUOTA\fR 4
17813 .IX Xref "PWQUOTA"
17814 .IX Item "PWQUOTA"
17815 This symbol, if defined, indicates to the C program that \f(CW\*(C`struct passwd\*(C'\fR
17816 contains \f(CW\*(C`pw_quota\*(C'\fR.
17817 .SH "Paths to system commands"
17818 .IX Header "Paths to system commands"
17819 .ie n .IP """CSH""" 4
17820 .el .IP \f(CWCSH\fR 4
17821 .IX Xref "CSH"
17822 .IX Item "CSH"
17823 This symbol, if defined, contains the full pathname of csh.
17824 .ie n .IP """LOC_SED""" 4
17825 .el .IP \f(CWLOC_SED\fR 4
17826 .IX Xref "LOC_SED"
17827 .IX Item "LOC_SED"
17828 This symbol holds the complete pathname to the sed program.
17829 .ie n .IP """SH_PATH""" 4
17830 .el .IP \f(CWSH_PATH\fR 4
17831 .IX Xref "SH_PATH"
17832 .IX Item "SH_PATH"
17833 This symbol contains the full pathname to the shell used on this
17834 on this system to execute Bourne shell scripts. Usually, this will be
17835 \&\fI/bin/sh\fR, though it\*(Aqs possible that some systems will have \fI/bin/ksh\fR,
17836 \&\fI/bin/pdksh\fR, \fI/bin/ash\fR, \fI/bin/bash\fR, or even something such as
17837 D:\fI/bin/sh.exe\fR.
17838 .SH "Prototype information"
17839 .IX Header "Prototype information"
17840 .ie n .IP """CRYPT_R_PROTO""" 4
17841 .el .IP \f(CWCRYPT_R_PROTO\fR 4
17842 .IX Xref "CRYPT_R_PROTO"
17843 .IX Item "CRYPT_R_PROTO"
17844 This symbol encodes the prototype of \f(CW\*(C`crypt_r\*(C'\fR.
17845 It is zero if \f(CW\*(C`d_crypt_r\*(C'\fR is undef, and one of the
17846 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_crypt_r\*(C'\fR
17847 is defined.
17848 .ie n .IP """CTERMID_R_PROTO""" 4
17849 .el .IP \f(CWCTERMID_R_PROTO\fR 4
17850 .IX Xref "CTERMID_R_PROTO"
17851 .IX Item "CTERMID_R_PROTO"
17852 This symbol encodes the prototype of \f(CW\*(C`ctermid_r\*(C'\fR.
17853 It is zero if \f(CW\*(C`d_ctermid_r\*(C'\fR is undef, and one of the
17854 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctermid_r\*(C'\fR
17855 is defined.
17856 .ie n .IP """DRAND48_R_PROTO""" 4
17857 .el .IP \f(CWDRAND48_R_PROTO\fR 4
17858 .IX Xref "DRAND48_R_PROTO"
17859 .IX Item "DRAND48_R_PROTO"
17860 This symbol encodes the prototype of \f(CW\*(C`drand48_r\*(C'\fR.
17861 It is zero if \f(CW\*(C`d_drand48_r\*(C'\fR is undef, and one of the
17862 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_drand48_r\*(C'\fR
17863 is defined.
17864 .ie n .IP """ENDGRENT_R_PROTO""" 4
17865 .el .IP \f(CWENDGRENT_R_PROTO\fR 4
17866 .IX Xref "ENDGRENT_R_PROTO"
17867 .IX Item "ENDGRENT_R_PROTO"
17868 This symbol encodes the prototype of \f(CW\*(C`endgrent_r\*(C'\fR.
17869 It is zero if \f(CW\*(C`d_endgrent_r\*(C'\fR is undef, and one of the
17870 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endgrent_r\*(C'\fR
17871 is defined.
17872 .ie n .IP """ENDHOSTENT_R_PROTO""" 4
17873 .el .IP \f(CWENDHOSTENT_R_PROTO\fR 4
17874 .IX Xref "ENDHOSTENT_R_PROTO"
17875 .IX Item "ENDHOSTENT_R_PROTO"
17876 This symbol encodes the prototype of \f(CW\*(C`endhostent_r\*(C'\fR.
17877 It is zero if \f(CW\*(C`d_endhostent_r\*(C'\fR is undef, and one of the
17878 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endhostent_r\*(C'\fR
17879 is defined.
17880 .ie n .IP """ENDNETENT_R_PROTO""" 4
17881 .el .IP \f(CWENDNETENT_R_PROTO\fR 4
17882 .IX Xref "ENDNETENT_R_PROTO"
17883 .IX Item "ENDNETENT_R_PROTO"
17884 This symbol encodes the prototype of \f(CW\*(C`endnetent_r\*(C'\fR.
17885 It is zero if \f(CW\*(C`d_endnetent_r\*(C'\fR is undef, and one of the
17886 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endnetent_r\*(C'\fR
17887 is defined.
17888 .ie n .IP """ENDPROTOENT_R_PROTO""" 4
17889 .el .IP \f(CWENDPROTOENT_R_PROTO\fR 4
17890 .IX Xref "ENDPROTOENT_R_PROTO"
17891 .IX Item "ENDPROTOENT_R_PROTO"
17892 This symbol encodes the prototype of \f(CW\*(C`endprotoent_r\*(C'\fR.
17893 It is zero if \f(CW\*(C`d_endprotoent_r\*(C'\fR is undef, and one of the
17894 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endprotoent_r\*(C'\fR
17895 is defined.
17896 .ie n .IP """ENDPWENT_R_PROTO""" 4
17897 .el .IP \f(CWENDPWENT_R_PROTO\fR 4
17898 .IX Xref "ENDPWENT_R_PROTO"
17899 .IX Item "ENDPWENT_R_PROTO"
17900 This symbol encodes the prototype of \f(CW\*(C`endpwent_r\*(C'\fR.
17901 It is zero if \f(CW\*(C`d_endpwent_r\*(C'\fR is undef, and one of the
17902 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endpwent_r\*(C'\fR
17903 is defined.
17904 .ie n .IP """ENDSERVENT_R_PROTO""" 4
17905 .el .IP \f(CWENDSERVENT_R_PROTO\fR 4
17906 .IX Xref "ENDSERVENT_R_PROTO"
17907 .IX Item "ENDSERVENT_R_PROTO"
17908 This symbol encodes the prototype of \f(CW\*(C`endservent_r\*(C'\fR.
17909 It is zero if \f(CW\*(C`d_endservent_r\*(C'\fR is undef, and one of the
17910 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_endservent_r\*(C'\fR
17911 is defined.
17912 .ie n .IP """GDBM_NDBM_H_USES_PROTOTYPES""" 4
17913 .el .IP \f(CWGDBM_NDBM_H_USES_PROTOTYPES\fR 4
17914 .IX Xref "GDBM_NDBM_H_USES_PROTOTYPES"
17915 .IX Item "GDBM_NDBM_H_USES_PROTOTYPES"
17916 This symbol, if defined, indicates that <gdbm\-\fIndbm.h\fR> uses real \f(CW\*(C`ANSI\*(C'\fR C
17917 prototypes instead of K&R style function declarations without any
17918 parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
17919 K&R style function declarations will yield errors.
17920 .ie n .IP """GDBMNDBM_H_USES_PROTOTYPES""" 4
17921 .el .IP \f(CWGDBMNDBM_H_USES_PROTOTYPES\fR 4
17922 .IX Xref "GDBMNDBM_H_USES_PROTOTYPES"
17923 .IX Item "GDBMNDBM_H_USES_PROTOTYPES"
17924 This symbol, if defined, indicates that \fIgdbm/ndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C
17925 prototypes instead of K&R style function declarations without any
17926 parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
17927 K&R style function declarations will yield errors.
17928 .ie n .IP """GETGRENT_R_PROTO""" 4
17929 .el .IP \f(CWGETGRENT_R_PROTO\fR 4
17930 .IX Xref "GETGRENT_R_PROTO"
17931 .IX Item "GETGRENT_R_PROTO"
17932 This symbol encodes the prototype of \f(CW\*(C`getgrent_r\*(C'\fR.
17933 It is zero if \f(CW\*(C`d_getgrent_r\*(C'\fR is undef, and one of the
17934 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrent_r\*(C'\fR
17935 is defined.
17936 .ie n .IP """GETGRGID_R_PROTO""" 4
17937 .el .IP \f(CWGETGRGID_R_PROTO\fR 4
17938 .IX Xref "GETGRGID_R_PROTO"
17939 .IX Item "GETGRGID_R_PROTO"
17940 This symbol encodes the prototype of \f(CW\*(C`getgrgid_r\*(C'\fR.
17941 It is zero if \f(CW\*(C`d_getgrgid_r\*(C'\fR is undef, and one of the
17942 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrgid_r\*(C'\fR
17943 is defined.
17944 .ie n .IP """GETGRNAM_R_PROTO""" 4
17945 .el .IP \f(CWGETGRNAM_R_PROTO\fR 4
17946 .IX Xref "GETGRNAM_R_PROTO"
17947 .IX Item "GETGRNAM_R_PROTO"
17948 This symbol encodes the prototype of \f(CW\*(C`getgrnam_r\*(C'\fR.
17949 It is zero if \f(CW\*(C`d_getgrnam_r\*(C'\fR is undef, and one of the
17950 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getgrnam_r\*(C'\fR
17951 is defined.
17952 .ie n .IP """GETHOSTBYADDR_R_PROTO""" 4
17953 .el .IP \f(CWGETHOSTBYADDR_R_PROTO\fR 4
17954 .IX Xref "GETHOSTBYADDR_R_PROTO"
17955 .IX Item "GETHOSTBYADDR_R_PROTO"
17956 This symbol encodes the prototype of \f(CW\*(C`gethostbyaddr_r\*(C'\fR.
17957 It is zero if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR is undef, and one of the
17958 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyaddr_r\*(C'\fR
17959 is defined.
17960 .ie n .IP """GETHOSTBYNAME_R_PROTO""" 4
17961 .el .IP \f(CWGETHOSTBYNAME_R_PROTO\fR 4
17962 .IX Xref "GETHOSTBYNAME_R_PROTO"
17963 .IX Item "GETHOSTBYNAME_R_PROTO"
17964 This symbol encodes the prototype of \f(CW\*(C`gethostbyname_r\*(C'\fR.
17965 It is zero if \f(CW\*(C`d_gethostbyname_r\*(C'\fR is undef, and one of the
17966 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostbyname_r\*(C'\fR
17967 is defined.
17968 .ie n .IP """GETHOSTENT_R_PROTO""" 4
17969 .el .IP \f(CWGETHOSTENT_R_PROTO\fR 4
17970 .IX Xref "GETHOSTENT_R_PROTO"
17971 .IX Item "GETHOSTENT_R_PROTO"
17972 This symbol encodes the prototype of \f(CW\*(C`gethostent_r\*(C'\fR.
17973 It is zero if \f(CW\*(C`d_gethostent_r\*(C'\fR is undef, and one of the
17974 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gethostent_r\*(C'\fR
17975 is defined.
17976 .ie n .IP """GETLOGIN_R_PROTO""" 4
17977 .el .IP \f(CWGETLOGIN_R_PROTO\fR 4
17978 .IX Xref "GETLOGIN_R_PROTO"
17979 .IX Item "GETLOGIN_R_PROTO"
17980 This symbol encodes the prototype of \f(CW\*(C`getlogin_r\*(C'\fR.
17981 It is zero if \f(CW\*(C`d_getlogin_r\*(C'\fR is undef, and one of the
17982 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getlogin_r\*(C'\fR
17983 is defined.
17984 .ie n .IP """GETNETBYADDR_R_PROTO""" 4
17985 .el .IP \f(CWGETNETBYADDR_R_PROTO\fR 4
17986 .IX Xref "GETNETBYADDR_R_PROTO"
17987 .IX Item "GETNETBYADDR_R_PROTO"
17988 This symbol encodes the prototype of \f(CW\*(C`getnetbyaddr_r\*(C'\fR.
17989 It is zero if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR is undef, and one of the
17990 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyaddr_r\*(C'\fR
17991 is defined.
17992 .ie n .IP """GETNETBYNAME_R_PROTO""" 4
17993 .el .IP \f(CWGETNETBYNAME_R_PROTO\fR 4
17994 .IX Xref "GETNETBYNAME_R_PROTO"
17995 .IX Item "GETNETBYNAME_R_PROTO"
17996 This symbol encodes the prototype of \f(CW\*(C`getnetbyname_r\*(C'\fR.
17997 It is zero if \f(CW\*(C`d_getnetbyname_r\*(C'\fR is undef, and one of the
17998 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetbyname_r\*(C'\fR
17999 is defined.
18000 .ie n .IP """GETNETENT_R_PROTO""" 4
18001 .el .IP \f(CWGETNETENT_R_PROTO\fR 4
18002 .IX Xref "GETNETENT_R_PROTO"
18003 .IX Item "GETNETENT_R_PROTO"
18004 This symbol encodes the prototype of \f(CW\*(C`getnetent_r\*(C'\fR.
18005 It is zero if \f(CW\*(C`d_getnetent_r\*(C'\fR is undef, and one of the
18006 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getnetent_r\*(C'\fR
18007 is defined.
18008 .ie n .IP """GETPROTOBYNAME_R_PROTO""" 4
18009 .el .IP \f(CWGETPROTOBYNAME_R_PROTO\fR 4
18010 .IX Xref "GETPROTOBYNAME_R_PROTO"
18011 .IX Item "GETPROTOBYNAME_R_PROTO"
18012 This symbol encodes the prototype of \f(CW\*(C`getprotobyname_r\*(C'\fR.
18013 It is zero if \f(CW\*(C`d_getprotobyname_r\*(C'\fR is undef, and one of the
18014 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobyname_r\*(C'\fR
18015 is defined.
18016 .ie n .IP """GETPROTOBYNUMBER_R_PROTO""" 4
18017 .el .IP \f(CWGETPROTOBYNUMBER_R_PROTO\fR 4
18018 .IX Xref "GETPROTOBYNUMBER_R_PROTO"
18019 .IX Item "GETPROTOBYNUMBER_R_PROTO"
18020 This symbol encodes the prototype of \f(CW\*(C`getprotobynumber_r\*(C'\fR.
18021 It is zero if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR is undef, and one of the
18022 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotobynumber_r\*(C'\fR
18023 is defined.
18024 .ie n .IP """GETPROTOENT_R_PROTO""" 4
18025 .el .IP \f(CWGETPROTOENT_R_PROTO\fR 4
18026 .IX Xref "GETPROTOENT_R_PROTO"
18027 .IX Item "GETPROTOENT_R_PROTO"
18028 This symbol encodes the prototype of \f(CW\*(C`getprotoent_r\*(C'\fR.
18029 It is zero if \f(CW\*(C`d_getprotoent_r\*(C'\fR is undef, and one of the
18030 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getprotoent_r\*(C'\fR
18031 is defined.
18032 .ie n .IP """GETPWENT_R_PROTO""" 4
18033 .el .IP \f(CWGETPWENT_R_PROTO\fR 4
18034 .IX Xref "GETPWENT_R_PROTO"
18035 .IX Item "GETPWENT_R_PROTO"
18036 This symbol encodes the prototype of \f(CW\*(C`getpwent_r\*(C'\fR.
18037 It is zero if \f(CW\*(C`d_getpwent_r\*(C'\fR is undef, and one of the
18038 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwent_r\*(C'\fR
18039 is defined.
18040 .ie n .IP """GETPWNAM_R_PROTO""" 4
18041 .el .IP \f(CWGETPWNAM_R_PROTO\fR 4
18042 .IX Xref "GETPWNAM_R_PROTO"
18043 .IX Item "GETPWNAM_R_PROTO"
18044 This symbol encodes the prototype of \f(CW\*(C`getpwnam_r\*(C'\fR.
18045 It is zero if \f(CW\*(C`d_getpwnam_r\*(C'\fR is undef, and one of the
18046 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwnam_r\*(C'\fR
18047 is defined.
18048 .ie n .IP """GETPWUID_R_PROTO""" 4
18049 .el .IP \f(CWGETPWUID_R_PROTO\fR 4
18050 .IX Xref "GETPWUID_R_PROTO"
18051 .IX Item "GETPWUID_R_PROTO"
18052 This symbol encodes the prototype of \f(CW\*(C`getpwuid_r\*(C'\fR.
18053 It is zero if \f(CW\*(C`d_getpwuid_r\*(C'\fR is undef, and one of the
18054 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getpwuid_r\*(C'\fR
18055 is defined.
18056 .ie n .IP """GETSERVBYNAME_R_PROTO""" 4
18057 .el .IP \f(CWGETSERVBYNAME_R_PROTO\fR 4
18058 .IX Xref "GETSERVBYNAME_R_PROTO"
18059 .IX Item "GETSERVBYNAME_R_PROTO"
18060 This symbol encodes the prototype of \f(CW\*(C`getservbyname_r\*(C'\fR.
18061 It is zero if \f(CW\*(C`d_getservbyname_r\*(C'\fR is undef, and one of the
18062 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyname_r\*(C'\fR
18063 is defined.
18064 .ie n .IP """GETSERVBYPORT_R_PROTO""" 4
18065 .el .IP \f(CWGETSERVBYPORT_R_PROTO\fR 4
18066 .IX Xref "GETSERVBYPORT_R_PROTO"
18067 .IX Item "GETSERVBYPORT_R_PROTO"
18068 This symbol encodes the prototype of \f(CW\*(C`getservbyport_r\*(C'\fR.
18069 It is zero if \f(CW\*(C`d_getservbyport_r\*(C'\fR is undef, and one of the
18070 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservbyport_r\*(C'\fR
18071 is defined.
18072 .ie n .IP """GETSERVENT_R_PROTO""" 4
18073 .el .IP \f(CWGETSERVENT_R_PROTO\fR 4
18074 .IX Xref "GETSERVENT_R_PROTO"
18075 .IX Item "GETSERVENT_R_PROTO"
18076 This symbol encodes the prototype of \f(CW\*(C`getservent_r\*(C'\fR.
18077 It is zero if \f(CW\*(C`d_getservent_r\*(C'\fR is undef, and one of the
18078 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getservent_r\*(C'\fR
18079 is defined.
18080 .ie n .IP """GETSPNAM_R_PROTO""" 4
18081 .el .IP \f(CWGETSPNAM_R_PROTO\fR 4
18082 .IX Xref "GETSPNAM_R_PROTO"
18083 .IX Item "GETSPNAM_R_PROTO"
18084 This symbol encodes the prototype of \f(CW\*(C`getspnam_r\*(C'\fR.
18085 It is zero if \f(CW\*(C`d_getspnam_r\*(C'\fR is undef, and one of the
18086 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_getspnam_r\*(C'\fR
18087 is defined.
18088 .ie n .IP """HAS_DBMINIT_PROTO""" 4
18089 .el .IP \f(CWHAS_DBMINIT_PROTO\fR 4
18090 .IX Xref "HAS_DBMINIT_PROTO"
18091 .IX Item "HAS_DBMINIT_PROTO"
18092 This symbol, if defined, indicates that the system provides
18093 a prototype for the \f(CWdbminit()\fR function. Otherwise, it is up
18094 to the program to supply one. A good guess is
18095 .Sp
18096 .Vb 1
18097 \& extern int dbminit(char *);
18098 .Ve
18099 .ie n .IP """HAS_DRAND48_PROTO""" 4
18100 .el .IP \f(CWHAS_DRAND48_PROTO\fR 4
18101 .IX Xref "HAS_DRAND48_PROTO"
18102 .IX Item "HAS_DRAND48_PROTO"
18103 This symbol, if defined, indicates that the system provides
18104 a prototype for the \f(CWdrand48()\fR function. Otherwise, it is up
18105 to the program to supply one. A good guess is
18106 .Sp
18107 .Vb 1
18108 \& extern double drand48(void);
18109 .Ve
18110 .ie n .IP """HAS_FLOCK_PROTO""" 4
18111 .el .IP \f(CWHAS_FLOCK_PROTO\fR 4
18112 .IX Xref "HAS_FLOCK_PROTO"
18113 .IX Item "HAS_FLOCK_PROTO"
18114 This symbol, if defined, indicates that the system provides
18115 a prototype for the \f(CWflock()\fR function. Otherwise, it is up
18116 to the program to supply one. A good guess is
18117 .Sp
18118 .Vb 1
18119 \& extern int flock(int, int);
18120 .Ve
18121 .ie n .IP """HAS_GETHOST_PROTOS""" 4
18122 .el .IP \f(CWHAS_GETHOST_PROTOS\fR 4
18123 .IX Xref "HAS_GETHOST_PROTOS"
18124 .IX Item "HAS_GETHOST_PROTOS"
18125 This symbol, if defined, indicates that \fInetdb.h\fR includes
18126 prototypes for \f(CWgethostent()\fR, \f(CWgethostbyname()\fR, and
18127 \&\f(CWgethostbyaddr()\fR. Otherwise, it is up to the program to guess
18128 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
18129 .ie n .IP """HAS_GETNET_PROTOS""" 4
18130 .el .IP \f(CWHAS_GETNET_PROTOS\fR 4
18131 .IX Xref "HAS_GETNET_PROTOS"
18132 .IX Item "HAS_GETNET_PROTOS"
18133 This symbol, if defined, indicates that \fInetdb.h\fR includes
18134 prototypes for \f(CWgetnetent()\fR, \f(CWgetnetbyname()\fR, and
18135 \&\f(CWgetnetbyaddr()\fR. Otherwise, it is up to the program to guess
18136 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
18137 .ie n .IP """HAS_GETPROTO_PROTOS""" 4
18138 .el .IP \f(CWHAS_GETPROTO_PROTOS\fR 4
18139 .IX Xref "HAS_GETPROTO_PROTOS"
18140 .IX Item "HAS_GETPROTO_PROTOS"
18141 This symbol, if defined, indicates that \fInetdb.h\fR includes
18142 prototypes for \f(CWgetprotoent()\fR, \f(CWgetprotobyname()\fR, and
18143 \&\f(CWgetprotobyaddr()\fR. Otherwise, it is up to the program to guess
18144 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
18145 .ie n .IP """HAS_GETSERV_PROTOS""" 4
18146 .el .IP \f(CWHAS_GETSERV_PROTOS\fR 4
18147 .IX Xref "HAS_GETSERV_PROTOS"
18148 .IX Item "HAS_GETSERV_PROTOS"
18149 This symbol, if defined, indicates that \fInetdb.h\fR includes
18150 prototypes for \f(CWgetservent()\fR, \f(CWgetservbyname()\fR, and
18151 \&\f(CWgetservbyaddr()\fR. Otherwise, it is up to the program to guess
18152 them. See netdbtype.U (part of metaconfig) for probing for various \f(CW\*(C`Netdb_xxx_t\*(C'\fR types.
18153 .ie n .IP """HAS_MODFL_PROTO""" 4
18154 .el .IP \f(CWHAS_MODFL_PROTO\fR 4
18155 .IX Xref "HAS_MODFL_PROTO"
18156 .IX Item "HAS_MODFL_PROTO"
18157 This symbol, if defined, indicates that the system provides
18158 a prototype for the \f(CWmodfl()\fR function. Otherwise, it is up
18159 to the program to supply one.
18160 .ie n .IP """HAS_SBRK_PROTO""" 4
18161 .el .IP \f(CWHAS_SBRK_PROTO\fR 4
18162 .IX Xref "HAS_SBRK_PROTO"
18163 .IX Item "HAS_SBRK_PROTO"
18164 This symbol, if defined, indicates that the system provides
18165 a prototype for the \f(CWsbrk()\fR function. Otherwise, it is up
18166 to the program to supply one. Good guesses are
18167 .Sp
18168 .Vb 2
18169 \& extern void* sbrk(int);
18170 \& extern void* sbrk(size_t);
18171 .Ve
18172 .ie n .IP """HAS_SETRESGID_PROTO""" 4
18173 .el .IP \f(CWHAS_SETRESGID_PROTO\fR 4
18174 .IX Xref "HAS_SETRESGID_PROTO"
18175 .IX Item "HAS_SETRESGID_PROTO"
18176 This symbol, if defined, indicates that the system provides
18177 a prototype for the \f(CWsetresgid()\fR function. Otherwise, it is up
18178 to the program to supply one. Good guesses are
18179 .Sp
18180 .Vb 1
18181 \& extern int setresgid(uid_t ruid, uid_t euid, uid_t suid);
18182 .Ve
18183 .ie n .IP """HAS_SETRESUID_PROTO""" 4
18184 .el .IP \f(CWHAS_SETRESUID_PROTO\fR 4
18185 .IX Xref "HAS_SETRESUID_PROTO"
18186 .IX Item "HAS_SETRESUID_PROTO"
18187 This symbol, if defined, indicates that the system provides
18188 a prototype for the \f(CWsetresuid()\fR function. Otherwise, it is up
18189 to the program to supply one. Good guesses are
18190 .Sp
18191 .Vb 1
18192 \& extern int setresuid(uid_t ruid, uid_t euid, uid_t suid);
18193 .Ve
18194 .ie n .IP """HAS_SHMAT_PROTOTYPE""" 4
18195 .el .IP \f(CWHAS_SHMAT_PROTOTYPE\fR 4
18196 .IX Xref "HAS_SHMAT_PROTOTYPE"
18197 .IX Item "HAS_SHMAT_PROTOTYPE"
18198 This symbol, if defined, indicates that the \fIsys/shm.h\fR includes
18199 a prototype for \f(CWshmat()\fR. Otherwise, it is up to the program to
18200 guess one. \f(CW\*(C`Shmat_t\*(C'\fR \f(CW\*(C`shmat(int, Shmat_t, int)\*(C'\fR is a good guess,
18201 but not always right so it should be emitted by the program only
18202 when \f(CW\*(C`HAS_SHMAT_PROTOTYPE\*(C'\fR is not defined to avoid conflicting defs.
18203 .ie n .IP """HAS_SOCKATMARK_PROTO""" 4
18204 .el .IP \f(CWHAS_SOCKATMARK_PROTO\fR 4
18205 .IX Xref "HAS_SOCKATMARK_PROTO"
18206 .IX Item "HAS_SOCKATMARK_PROTO"
18207 This symbol, if defined, indicates that the system provides
18208 a prototype for the \f(CWsockatmark()\fR function. Otherwise, it is up
18209 to the program to supply one. A good guess is
18210 .Sp
18211 .Vb 1
18212 \& extern int sockatmark(int);
18213 .Ve
18214 .ie n .IP """HAS_SYSCALL_PROTO""" 4
18215 .el .IP \f(CWHAS_SYSCALL_PROTO\fR 4
18216 .IX Xref "HAS_SYSCALL_PROTO"
18217 .IX Item "HAS_SYSCALL_PROTO"
18218 This symbol, if defined, indicates that the system provides
18219 a prototype for the \f(CWsyscall()\fR function. Otherwise, it is up
18220 to the program to supply one. Good guesses are
18221 .Sp
18222 .Vb 2
18223 \& extern int syscall(int, ...);
18224 \& extern int syscall(long, ...);
18225 .Ve
18226 .ie n .IP """HAS_TELLDIR_PROTO""" 4
18227 .el .IP \f(CWHAS_TELLDIR_PROTO\fR 4
18228 .IX Xref "HAS_TELLDIR_PROTO"
18229 .IX Item "HAS_TELLDIR_PROTO"
18230 This symbol, if defined, indicates that the system provides
18231 a prototype for the \f(CWtelldir()\fR function. Otherwise, it is up
18232 to the program to supply one. A good guess is
18233 .Sp
18234 .Vb 1
18235 \& extern long telldir(DIR*);
18236 .Ve
18237 .ie n .IP """NDBM_H_USES_PROTOTYPES""" 4
18238 .el .IP \f(CWNDBM_H_USES_PROTOTYPES\fR 4
18239 .IX Xref "NDBM_H_USES_PROTOTYPES"
18240 .IX Item "NDBM_H_USES_PROTOTYPES"
18241 This symbol, if defined, indicates that \fIndbm.h\fR uses real \f(CW\*(C`ANSI\*(C'\fR C
18242 prototypes instead of K&R style function declarations without any
18243 parameter information. While \f(CW\*(C`ANSI\*(C'\fR C prototypes are supported in C++,
18244 K&R style function declarations will yield errors.
18245 .ie n .IP """RANDOM_R_PROTO""" 4
18246 .el .IP \f(CWRANDOM_R_PROTO\fR 4
18247 .IX Xref "RANDOM_R_PROTO"
18248 .IX Item "RANDOM_R_PROTO"
18249 This symbol encodes the prototype of \f(CW\*(C`random_r\*(C'\fR.
18250 It is zero if \f(CW\*(C`d_random_r\*(C'\fR is undef, and one of the
18251 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_random_r\*(C'\fR
18252 is defined.
18253 .ie n .IP """READDIR_R_PROTO""" 4
18254 .el .IP \f(CWREADDIR_R_PROTO\fR 4
18255 .IX Xref "READDIR_R_PROTO"
18256 .IX Item "READDIR_R_PROTO"
18257 This symbol encodes the prototype of \f(CW\*(C`readdir_r\*(C'\fR.
18258 It is zero if \f(CW\*(C`d_readdir_r\*(C'\fR is undef, and one of the
18259 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_readdir_r\*(C'\fR
18260 is defined.
18261 .ie n .IP """SETGRENT_R_PROTO""" 4
18262 .el .IP \f(CWSETGRENT_R_PROTO\fR 4
18263 .IX Xref "SETGRENT_R_PROTO"
18264 .IX Item "SETGRENT_R_PROTO"
18265 This symbol encodes the prototype of \f(CW\*(C`setgrent_r\*(C'\fR.
18266 It is zero if \f(CW\*(C`d_setgrent_r\*(C'\fR is undef, and one of the
18267 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setgrent_r\*(C'\fR
18268 is defined.
18269 .ie n .IP """SETHOSTENT_R_PROTO""" 4
18270 .el .IP \f(CWSETHOSTENT_R_PROTO\fR 4
18271 .IX Xref "SETHOSTENT_R_PROTO"
18272 .IX Item "SETHOSTENT_R_PROTO"
18273 This symbol encodes the prototype of \f(CW\*(C`sethostent_r\*(C'\fR.
18274 It is zero if \f(CW\*(C`d_sethostent_r\*(C'\fR is undef, and one of the
18275 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_sethostent_r\*(C'\fR
18276 is defined.
18277 .ie n .IP """SETLOCALE_R_PROTO""" 4
18278 .el .IP \f(CWSETLOCALE_R_PROTO\fR 4
18279 .IX Xref "SETLOCALE_R_PROTO"
18280 .IX Item "SETLOCALE_R_PROTO"
18281 This symbol encodes the prototype of \f(CW\*(C`setlocale_r\*(C'\fR.
18282 It is zero if \f(CW\*(C`d_setlocale_r\*(C'\fR is undef, and one of the
18283 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setlocale_r\*(C'\fR
18284 is defined.
18285 .ie n .IP """SETNETENT_R_PROTO""" 4
18286 .el .IP \f(CWSETNETENT_R_PROTO\fR 4
18287 .IX Xref "SETNETENT_R_PROTO"
18288 .IX Item "SETNETENT_R_PROTO"
18289 This symbol encodes the prototype of \f(CW\*(C`setnetent_r\*(C'\fR.
18290 It is zero if \f(CW\*(C`d_setnetent_r\*(C'\fR is undef, and one of the
18291 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setnetent_r\*(C'\fR
18292 is defined.
18293 .ie n .IP """SETPROTOENT_R_PROTO""" 4
18294 .el .IP \f(CWSETPROTOENT_R_PROTO\fR 4
18295 .IX Xref "SETPROTOENT_R_PROTO"
18296 .IX Item "SETPROTOENT_R_PROTO"
18297 This symbol encodes the prototype of \f(CW\*(C`setprotoent_r\*(C'\fR.
18298 It is zero if \f(CW\*(C`d_setprotoent_r\*(C'\fR is undef, and one of the
18299 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setprotoent_r\*(C'\fR
18300 is defined.
18301 .ie n .IP """SETPWENT_R_PROTO""" 4
18302 .el .IP \f(CWSETPWENT_R_PROTO\fR 4
18303 .IX Xref "SETPWENT_R_PROTO"
18304 .IX Item "SETPWENT_R_PROTO"
18305 This symbol encodes the prototype of \f(CW\*(C`setpwent_r\*(C'\fR.
18306 It is zero if \f(CW\*(C`d_setpwent_r\*(C'\fR is undef, and one of the
18307 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setpwent_r\*(C'\fR
18308 is defined.
18309 .ie n .IP """SETSERVENT_R_PROTO""" 4
18310 .el .IP \f(CWSETSERVENT_R_PROTO\fR 4
18311 .IX Xref "SETSERVENT_R_PROTO"
18312 .IX Item "SETSERVENT_R_PROTO"
18313 This symbol encodes the prototype of \f(CW\*(C`setservent_r\*(C'\fR.
18314 It is zero if \f(CW\*(C`d_setservent_r\*(C'\fR is undef, and one of the
18315 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_setservent_r\*(C'\fR
18316 is defined.
18317 .ie n .IP """SRANDOM_R_PROTO""" 4
18318 .el .IP \f(CWSRANDOM_R_PROTO\fR 4
18319 .IX Xref "SRANDOM_R_PROTO"
18320 .IX Item "SRANDOM_R_PROTO"
18321 This symbol encodes the prototype of \f(CW\*(C`srandom_r\*(C'\fR.
18322 It is zero if \f(CW\*(C`d_srandom_r\*(C'\fR is undef, and one of the
18323 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srandom_r\*(C'\fR
18324 is defined.
18325 .ie n .IP """SRAND48_R_PROTO""" 4
18326 .el .IP \f(CWSRAND48_R_PROTO\fR 4
18327 .IX Xref "SRAND48_R_PROTO"
18328 .IX Item "SRAND48_R_PROTO"
18329 This symbol encodes the prototype of \f(CW\*(C`srand48_r\*(C'\fR.
18330 It is zero if \f(CW\*(C`d_srand48_r\*(C'\fR is undef, and one of the
18331 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_srand48_r\*(C'\fR
18332 is defined.
18333 .ie n .IP """STRERROR_R_PROTO""" 4
18334 .el .IP \f(CWSTRERROR_R_PROTO\fR 4
18335 .IX Xref "STRERROR_R_PROTO"
18336 .IX Item "STRERROR_R_PROTO"
18337 This symbol encodes the prototype of \f(CW\*(C`strerror_r\*(C'\fR.
18338 It is zero if \f(CW\*(C`d_strerror_r\*(C'\fR is undef, and one of the
18339 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_strerror_r\*(C'\fR
18340 is defined.
18341 .ie n .IP """TMPNAM_R_PROTO""" 4
18342 .el .IP \f(CWTMPNAM_R_PROTO\fR 4
18343 .IX Xref "TMPNAM_R_PROTO"
18344 .IX Item "TMPNAM_R_PROTO"
18345 This symbol encodes the prototype of \f(CW\*(C`tmpnam_r\*(C'\fR.
18346 It is zero if \f(CW\*(C`d_tmpnam_r\*(C'\fR is undef, and one of the
18347 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_tmpnam_r\*(C'\fR
18348 is defined.
18349 .ie n .IP """TTYNAME_R_PROTO""" 4
18350 .el .IP \f(CWTTYNAME_R_PROTO\fR 4
18351 .IX Xref "TTYNAME_R_PROTO"
18352 .IX Item "TTYNAME_R_PROTO"
18353 This symbol encodes the prototype of \f(CW\*(C`ttyname_r\*(C'\fR.
18354 It is zero if \f(CW\*(C`d_ttyname_r\*(C'\fR is undef, and one of the
18355 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ttyname_r\*(C'\fR
18356 is defined.
18357 .SH "Reference\-counted stack manipulation"
18358 .IX Header "Reference-counted stack manipulation"
18359 Functions for pushing and pulling items on the stack when the
18360 stack is reference counted. They are intended as replacements
18361 for the old PUSHs, POPi, EXTEND etc pp macros within pp
18362 functions.
18363 .ie n .IP """rpp_context""" 4
18364 .el .IP \f(CWrpp_context\fR 4
18365 .IX Xref "rpp_context"
18366 .IX Item "rpp_context"
18367 NOTE: \f(CW\*(C`rpp_context\*(C'\fR is \fBexperimental\fR and may change or be
18368 removed without notice.
18369 .Sp
18370 Impose void, scalar or list context on the stack.
18371 First, pop \f(CW\*(C`extra\*(C'\fR items off the stack, then when \f(CW\*(C`gimme\*(C'\fR is:
18372 \&\f(CW\*(C`G_LIST\*(C'\fR: return as\-is.
18373 \&\f(CW\*(C`G_VOID\*(C'\fR: pop everything back to \f(CW\*(C`mark\*(C'\fR
18374 \&\f(CW\*(C`G_SCALAR\*(C'\fR: move the top stack item (or \f(CW&PL_sv_undef\fR if none) to
18375 \&\f(CW\*(C`mark+1\*(C'\fR and free everything above it.
18376 .RS 4
18377 .Sp
18378 .Vb 2
18379 \& void rpp_context( SV **mark, U8 gimme, SSize_t extra)
18380 \& void Perl_rpp_context(pTHX_ SV **mark, U8 gimme, SSize_t extra)
18381 .Ve
18382 .RE
18383 .RS 4
18384 .RE
18385 .ie n .IP """rpp_extend""" 4
18386 .el .IP \f(CWrpp_extend\fR 4
18387 .IX Xref "rpp_extend"
18388 .IX Item "rpp_extend"
18389 NOTE: \f(CW\*(C`rpp_extend\*(C'\fR is \fBexperimental\fR and may change or be
18390 removed without notice.
18391 .Sp
18392 Ensures that there is space on the stack to push \f(CW\*(C`n\*(C'\fR items, extending it
18393 if necessary.
18394 .RS 4
18395 .Sp
18396 .Vb 2
18397 \& void rpp_extend( SSize_t n)
18398 \& void Perl_rpp_extend(pTHX_ SSize_t n)
18399 .Ve
18400 .RE
18401 .RS 4
18402 .RE
18403 .ie n .IP """rpp_invoke_xs""" 4
18404 .el .IP \f(CWrpp_invoke_xs\fR 4
18405 .IX Xref "rpp_invoke_xs"
18406 .IX Item "rpp_invoke_xs"
18407 NOTE: \f(CW\*(C`rpp_invoke_xs\*(C'\fR is \fBexperimental\fR and may change or be
18408 removed without notice.
18409 .Sp
18410 Call the XS function associated with \f(CW\*(C`cv\*(C'\fR. Wraps the call if necessary to
18411 handle XS functions which are not aware of reference\-counted stacks.
18412 .RS 4
18413 .Sp
18414 .Vb 2
18415 \& void rpp_invoke_xs( CV *cv)
18416 \& void Perl_rpp_invoke_xs(pTHX_ CV *cv)
18417 .Ve
18418 .RE
18419 .RS 4
18420 .RE
18421 .ie n .IP """rpp_is_lone""" 4
18422 .el .IP \f(CWrpp_is_lone\fR 4
18423 .IX Xref "rpp_is_lone"
18424 .IX Item "rpp_is_lone"
18425 NOTE: \f(CW\*(C`rpp_is_lone\*(C'\fR is \fBexperimental\fR and may change or be
18426 removed without notice.
18427 .Sp
18428 Indicates whether the stacked SV \f(CW\*(C`sv\*(C'\fR (assumed to be not yet popped off
18429 the stack) is only kept alive due to a single reference from the argument
18430 stack and/or and the temps stack.
18431 .Sp
18432 This can used for example to decide whether the copying of return values
18433 in rvalue context can be skipped, or whether it shouldn\*(Aqt be assigned to
18434 in lvalue context.
18435 .RS 4
18436 .Sp
18437 .Vb 2
18438 \& bool rpp_is_lone( SV *sv)
18439 \& bool Perl_rpp_is_lone(pTHX_ SV *sv)
18440 .Ve
18441 .RE
18442 .RS 4
18443 .RE
18444 .ie n .IP """rpp_pop_1_norc""" 4
18445 .el .IP \f(CWrpp_pop_1_norc\fR 4
18446 .IX Xref "rpp_pop_1_norc"
18447 .IX Item "rpp_pop_1_norc"
18448 NOTE: \f(CW\*(C`rpp_pop_1_norc\*(C'\fR is \fBexperimental\fR and may change or be
18449 removed without notice.
18450 .Sp
18451 Pop and return the top item off the argument stack and update
18452 \&\f(CW\*(C`PL_stack_sp\*(C'\fR. It\*(Aqs similar to \fBrpp_popfree_1()\fR, except that it actually
18453 returns a value, and it \fIdoesn\*(Aqt\fR decrement the SV\*(Aqs reference count.
18454 On non\-\f(CW\*(C`PERL_RC_STACK\*(C'\fR builds it actually increments the SV\*(Aqs reference
18455 count.
18456 .Sp
18457 This is useful in cases where the popped value is immediately embedded
18458 somewhere e.g. via \fBav_store()\fR, allowing you skip decrementing and then
18459 immediately incrementing the reference count again (and risk prematurely
18460 freeing the SV if it had a RC of 1). On non\-RC builds, the reference count
18461 bookkeeping still works too, which is why it should be used rather than
18462 a simple \f(CW\*(C`*PL_stack_sp\-\-\*(C'\fR.
18463 .RS 4
18464 .Sp
18465 .Vb 2
18466 \& SV * rpp_pop_1_norc()
18467 \& SV * Perl_rpp_pop_1_norc(pTHX)
18468 .Ve
18469 .RE
18470 .RS 4
18471 .RE
18472 .ie n .IP """rpp_popfree_to""" 4
18473 .el .IP \f(CWrpp_popfree_to\fR 4
18474 .IX Xref "rpp_popfree_to"
18475 .IX Item "rpp_popfree_to"
18476 NOTE: \f(CW\*(C`rpp_popfree_to\*(C'\fR is \fBexperimental\fR and may change or be
18477 removed without notice.
18478 .Sp
18479 Pop and free all items on the argument stack above \f(CW\*(C`sp\*(C'\fR. On return,
18480 \&\f(CW\*(C`PL_stack_sp\*(C'\fR will be equal to \f(CW\*(C`sp\*(C'\fR.
18481 .RS 4
18482 .Sp
18483 .Vb 2
18484 \& void rpp_popfree_to( SV **sp)
18485 \& void Perl_rpp_popfree_to(pTHX_ SV **sp)
18486 .Ve
18487 .RE
18488 .RS 4
18489 .RE
18490 .ie n .IP """rpp_popfree_to_NN""" 4
18491 .el .IP \f(CWrpp_popfree_to_NN\fR 4
18492 .IX Xref "rpp_popfree_to_NN"
18493 .IX Item "rpp_popfree_to_NN"
18494 NOTE: \f(CW\*(C`rpp_popfree_to_NN\*(C'\fR is \fBexperimental\fR and may change or be
18495 removed without notice.
18496 .Sp
18497 A variant of \fBrpp_popfree_to()\fR which assumes that all the pointers being
18498 popped off the stack are non\-NULL.
18499 .RS 4
18500 .Sp
18501 .Vb 2
18502 \& void rpp_popfree_to_NN( SV **sp)
18503 \& void Perl_rpp_popfree_to_NN(pTHX_ SV **sp)
18504 .Ve
18505 .RE
18506 .RS 4
18507 .RE
18508 .ie n .IP """rpp_popfree_1""" 4
18509 .el .IP \f(CWrpp_popfree_1\fR 4
18510 .IX Xref "rpp_popfree_1"
18511 .IX Item "rpp_popfree_1"
18512 NOTE: \f(CW\*(C`rpp_popfree_1\*(C'\fR is \fBexperimental\fR and may change or be
18513 removed without notice.
18514 .Sp
18515 Pop and free the top item on the argument stack and update \f(CW\*(C`PL_stack_sp\*(C'\fR.
18516 .RS 4
18517 .Sp
18518 .Vb 2
18519 \& void rpp_popfree_1()
18520 \& void Perl_rpp_popfree_1(pTHX)
18521 .Ve
18522 .RE
18523 .RS 4
18524 .RE
18525 .ie n .IP """rpp_popfree_1_NN""" 4
18526 .el .IP \f(CWrpp_popfree_1_NN\fR 4
18527 .IX Xref "rpp_popfree_1_NN"
18528 .IX Item "rpp_popfree_1_NN"
18529 NOTE: \f(CW\*(C`rpp_popfree_1_NN\*(C'\fR is \fBexperimental\fR and may change or be
18530 removed without notice.
18531 .Sp
18532 A variant of \fBrpp_popfree_1()\fR which assumes that the pointer being popped
18533 off the stack is non\-NULL.
18534 .RS 4
18535 .Sp
18536 .Vb 2
18537 \& void rpp_popfree_1_NN()
18538 \& void Perl_rpp_popfree_1_NN(pTHX)
18539 .Ve
18540 .RE
18541 .RS 4
18542 .RE
18543 .ie n .IP """rpp_popfree_2""" 4
18544 .el .IP \f(CWrpp_popfree_2\fR 4
18545 .IX Xref "rpp_popfree_2"
18546 .IX Item "rpp_popfree_2"
18547 NOTE: \f(CW\*(C`rpp_popfree_2\*(C'\fR is \fBexperimental\fR and may change or be
18548 removed without notice.
18549 .Sp
18550 Pop and free the top two items on the argument stack and update
18551 \&\f(CW\*(C`PL_stack_sp\*(C'\fR.
18552 .RS 4
18553 .Sp
18554 .Vb 2
18555 \& void rpp_popfree_2()
18556 \& void Perl_rpp_popfree_2(pTHX)
18557 .Ve
18558 .RE
18559 .RS 4
18560 .RE
18561 .ie n .IP """rpp_popfree_2_NN""" 4
18562 .el .IP \f(CWrpp_popfree_2_NN\fR 4
18563 .IX Xref "rpp_popfree_2_NN"
18564 .IX Item "rpp_popfree_2_NN"
18565 NOTE: \f(CW\*(C`rpp_popfree_2_NN\*(C'\fR is \fBexperimental\fR and may change or be
18566 removed without notice.
18567 .Sp
18568 A variant of \fBrpp_popfree_2()\fR which assumes that the two pointers being
18569 popped off the stack are non\-NULL.
18570 .RS 4
18571 .Sp
18572 .Vb 2
18573 \& void rpp_popfree_2_NN()
18574 \& void Perl_rpp_popfree_2_NN(pTHX)
18575 .Ve
18576 .RE
18577 .RS 4
18578 .RE
18579 .ie n .IP """rpp_push_1""" 4
18580 .el .IP \f(CWrpp_push_1\fR 4
18581 .IX Item "rpp_push_1"
18582 .PD 0
18583 .ie n .IP """rpp_push_IMM""" 4
18584 .el .IP \f(CWrpp_push_IMM\fR 4
18585 .IX Item "rpp_push_IMM"
18586 .ie n .IP """rpp_push_2""" 4
18587 .el .IP \f(CWrpp_push_2\fR 4
18588 .IX Item "rpp_push_2"
18589 .ie n .IP """rpp_xpush_1""" 4
18590 .el .IP \f(CWrpp_xpush_1\fR 4
18591 .IX Item "rpp_xpush_1"
18592 .ie n .IP """rpp_xpush_IMM""" 4
18593 .el .IP \f(CWrpp_xpush_IMM\fR 4
18594 .IX Item "rpp_xpush_IMM"
18595 .ie n .IP """rpp_xpush_2""" 4
18596 .el .IP \f(CWrpp_xpush_2\fR 4
18597 .IX Xref "rpp_push_IMM rpp_push_1 rpp_push_2 rpp_xpush_IMM rpp_xpush_1 rpp_xpush_2"
18598 .IX Item "rpp_xpush_2"
18599 .PD
18600 NOTE: all these forms are \fBexperimental\fR and may change or be
18601 removed without notice.
18602 .Sp
18603 Push one or two SVs onto the stack, incrementing their reference counts
18604 and updating \f(CW\*(C`PL_stack_sp\*(C'\fR. With the \f(CW\*(C`x\*(C'\fR variants, it extends the stack
18605 first. The \f(CW\*(C`IMM\*(C'\fR variants assume that the single argument is an immortal
18606 such as <&PL_sv_undef> and, for efficiency, will skip incrementing its
18607 reference count.
18608 .RS 4
18609 .Sp
18610 .Vb 12
18611 \& void rpp_push_1 ( SV *sv)
18612 \& void Perl_rpp_push_1 (pTHX_ SV *sv)
18613 \& void rpp_push_IMM ( SV *sv)
18614 \& void Perl_rpp_push_IMM (pTHX_ SV *sv)
18615 \& void rpp_push_2 ( SV *sv1, SV *sv2)
18616 \& void Perl_rpp_push_2 (pTHX_ SV *sv1, SV *sv2)
18617 \& void rpp_xpush_1 ( SV *sv)
18618 \& void Perl_rpp_xpush_1 (pTHX_ SV *sv)
18619 \& void rpp_xpush_IMM( SV *sv)
18620 \& void Perl_rpp_xpush_IMM(pTHX_ SV *sv)
18621 \& void rpp_xpush_2 ( SV *sv1, SV *sv2)
18622 \& void Perl_rpp_xpush_2 (pTHX_ SV *sv1, SV *sv2)
18623 .Ve
18624 .RE
18625 .RS 4
18626 .RE
18627 .ie n .IP """rpp_push_1_norc""" 4
18628 .el .IP \f(CWrpp_push_1_norc\fR 4
18629 .IX Xref "rpp_push_1_norc"
18630 .IX Item "rpp_push_1_norc"
18631 NOTE: \f(CW\*(C`rpp_push_1_norc\*(C'\fR is \fBexperimental\fR and may change or be
18632 removed without notice.
18633 .Sp
18634 Push \f(CW\*(C`sv\*(C'\fR onto the stack without incrementing its reference count, and
18635 update \f(CW\*(C`PL_stack_sp\*(C'\fR. On non\-PERL_RC_STACK builds, mortalise too.
18636 .Sp
18637 This is most useful where an SV has just been created and already has a
18638 reference count of 1, but has not yet been anchored anywhere.
18639 .RS 4
18640 .Sp
18641 .Vb 2
18642 \& void rpp_push_1_norc( SV *sv)
18643 \& void Perl_rpp_push_1_norc(pTHX_ SV *sv)
18644 .Ve
18645 .RE
18646 .RS 4
18647 .RE
18648 .ie n .IP """rpp_push_2*""" 4
18649 .el .IP \f(CWrpp_push_2*\fR 4
18650 .IX Item "rpp_push_2*"
18651 Described under \f(CW"rpp_push_1"\fR
18652 .ie n .IP """rpp_replace_at""" 4
18653 .el .IP \f(CWrpp_replace_at\fR 4
18654 .IX Xref "rpp_replace_at"
18655 .IX Item "rpp_replace_at"
18656 NOTE: \f(CW\*(C`rpp_replace_at\*(C'\fR is \fBexperimental\fR and may change or be
18657 removed without notice.
18658 .Sp
18659 Replace the SV at address sp within the stack with \f(CW\*(C`sv\*(C'\fR, while suitably
18660 adjusting reference counts. Equivalent to \f(CW\*(C`*sp = sv\*(C'\fR, except with proper
18661 reference count handling.
18662 .RS 4
18663 .Sp
18664 .Vb 2
18665 \& void rpp_replace_at( SV **sp, SV *sv)
18666 \& void Perl_rpp_replace_at(pTHX_ SV **sp, SV *sv)
18667 .Ve
18668 .RE
18669 .RS 4
18670 .RE
18671 .ie n .IP """rpp_replace_at_NN""" 4
18672 .el .IP \f(CWrpp_replace_at_NN\fR 4
18673 .IX Xref "rpp_replace_at_NN"
18674 .IX Item "rpp_replace_at_NN"
18675 NOTE: \f(CW\*(C`rpp_replace_at_NN\*(C'\fR is \fBexperimental\fR and may change or be
18676 removed without notice.
18677 .Sp
18678 A variant of \fBrpp_replace_at()\fR which assumes that the SV pointer on the
18679 stack is non\-NULL.
18680 .RS 4
18681 .Sp
18682 .Vb 2
18683 \& void rpp_replace_at_NN( SV **sp, SV *sv)
18684 \& void Perl_rpp_replace_at_NN(pTHX_ SV **sp, SV *sv)
18685 .Ve
18686 .RE
18687 .RS 4
18688 .RE
18689 .ie n .IP """rpp_replace_at_norc""" 4
18690 .el .IP \f(CWrpp_replace_at_norc\fR 4
18691 .IX Xref "rpp_replace_at_norc"
18692 .IX Item "rpp_replace_at_norc"
18693 NOTE: \f(CW\*(C`rpp_replace_at_norc\*(C'\fR is \fBexperimental\fR and may change or be
18694 removed without notice.
18695 .Sp
18696 Replace the SV at address sp within the stack with \f(CW\*(C`sv\*(C'\fR, while suitably
18697 adjusting the reference count of the old SV. Equivalent to \f(CW\*(C`*sp = sv\*(C'\fR,
18698 except with proper reference count handling.
18699 .Sp
18700 \&\f(CW\*(C`sv\*(C'\fR\*(Aqs reference count doesn\*(Aqt get incremented. On non\-\f(CW\*(C`PERL_RC_STACK\*(C'\fR
18701 builds, it gets mortalised too.
18702 .Sp
18703 This is most useful where an SV has just been created and already has a
18704 reference count of 1, but has not yet been anchored anywhere.
18705 .RS 4
18706 .Sp
18707 .Vb 2
18708 \& void rpp_replace_at_norc( SV **sp, SV *sv)
18709 \& void Perl_rpp_replace_at_norc(pTHX_ SV **sp, SV *sv)
18710 .Ve
18711 .RE
18712 .RS 4
18713 .RE
18714 .ie n .IP """rpp_replace_at_norc_NN""" 4
18715 .el .IP \f(CWrpp_replace_at_norc_NN\fR 4
18716 .IX Xref "rpp_replace_at_norc_NN"
18717 .IX Item "rpp_replace_at_norc_NN"
18718 NOTE: \f(CW\*(C`rpp_replace_at_norc_NN\*(C'\fR is \fBexperimental\fR and may change or be
18719 removed without notice.
18720 .Sp
18721 A variant of \fBrpp_replace_at_norc()\fR which assumes that the SV pointer on the
18722 stack is non\-NULL.
18723 .RS 4
18724 .Sp
18725 .Vb 2
18726 \& void rpp_replace_at_norc_NN( SV **sp, SV *sv)
18727 \& void Perl_rpp_replace_at_norc_NN(pTHX_ SV **sp, SV *sv)
18728 .Ve
18729 .RE
18730 .RS 4
18731 .RE
18732 .ie n .IP """rpp_replace_1_1""" 4
18733 .el .IP \f(CWrpp_replace_1_1\fR 4
18734 .IX Item "rpp_replace_1_1"
18735 .PD 0
18736 .ie n .IP """rpp_replace_1_1_NN""" 4
18737 .el .IP \f(CWrpp_replace_1_1_NN\fR 4
18738 .IX Item "rpp_replace_1_1_NN"
18739 .ie n .IP """rpp_replace_1_IMM_NN""" 4
18740 .el .IP \f(CWrpp_replace_1_IMM_NN\fR 4
18741 .IX Xref "rpp_replace_1_IMM_NN rpp_replace_1_1 rpp_replace_1_1_NN"
18742 .IX Item "rpp_replace_1_IMM_NN"
18743 .PD
18744 NOTE: all these forms are \fBexperimental\fR and may change or be
18745 removed without notice.
18746 .Sp
18747 Replace the current top stack item with \f(CW\*(C`sv\*(C'\fR, while suitably adjusting
18748 reference counts. Equivalent to \fBrpp_popfree_1()\fR; rpp_push_1(sv), but
18749 is more efficient and handles both SVs being the same.
18750 .Sp
18751 The \f(CW\*(C`_NN\*(C'\fR variant assumes that the pointer on the stack to the SV being
18752 freed is non\-NULL.
18753 .Sp
18754 The \f(CW\*(C`IMM_NN\*(C'\fR variant is like the \f(CW\*(C`_NN\*(C'\fR variant, but in addition, assumes
18755 that the single argument is an immortal such as <&PL_sv_undef> and, for
18756 efficiency, will skip incrementing its reference count.
18757 .RS 4
18758 .Sp
18759 .Vb 6
18760 \& void rpp_replace_1_1 ( SV *sv)
18761 \& void Perl_rpp_replace_1_1 (pTHX_ SV *sv)
18762 \& void rpp_replace_1_1_NN ( SV *sv)
18763 \& void Perl_rpp_replace_1_1_NN (pTHX_ SV *sv)
18764 \& void rpp_replace_1_IMM_NN( SV *sv)
18765 \& void Perl_rpp_replace_1_IMM_NN(pTHX_ SV *sv)
18766 .Ve
18767 .RE
18768 .RS 4
18769 .RE
18770 .ie n .IP """rpp_replace_2_1""" 4
18771 .el .IP \f(CWrpp_replace_2_1\fR 4
18772 .IX Item "rpp_replace_2_1"
18773 .PD 0
18774 .ie n .IP """rpp_replace_2_1_NN""" 4
18775 .el .IP \f(CWrpp_replace_2_1_NN\fR 4
18776 .IX Item "rpp_replace_2_1_NN"
18777 .ie n .IP """rpp_replace_2_IMM_NN""" 4
18778 .el .IP \f(CWrpp_replace_2_IMM_NN\fR 4
18779 .IX Xref "rpp_replace_2_IMM_NN rpp_replace_2_1 rpp_replace_2_1_NN"
18780 .IX Item "rpp_replace_2_IMM_NN"
18781 .PD
18782 NOTE: all these forms are \fBexperimental\fR and may change or be
18783 removed without notice.
18784 .Sp
18785 Replace the current top to stacks item with \f(CW\*(C`sv\*(C'\fR, while suitably
18786 adjusting reference counts. Equivalent to \fBrpp_popfree_2()\fR; rpp_push_1(sv),
18787 but is more efficient and handles SVs being the same.
18788 .Sp
18789 The \f(CW\*(C`_NN\*(C'\fR variant assumes that the pointers on the stack to the SVs being
18790 freed are non\-NULL.
18791 .Sp
18792 The \f(CW\*(C`IMM_NN\*(C'\fR variant is like the \f(CW\*(C`_NN\*(C'\fR variant, but in addition, assumes
18793 that the single argument is an immortal such as <&PL_sv_undef> and, for
18794 efficiency, will skip incrementing its reference count.
18795 .RS 4
18796 .Sp
18797 .Vb 6
18798 \& void rpp_replace_2_1 ( SV *sv)
18799 \& void Perl_rpp_replace_2_1 (pTHX_ SV *sv)
18800 \& void rpp_replace_2_1_NN ( SV *sv)
18801 \& void Perl_rpp_replace_2_1_NN (pTHX_ SV *sv)
18802 \& void rpp_replace_2_IMM_NN( SV *sv)
18803 \& void Perl_rpp_replace_2_IMM_NN(pTHX_ SV *sv)
18804 .Ve
18805 .RE
18806 .RS 4
18807 .RE
18808 .ie n .IP """rpp_stack_is_rc""" 4
18809 .el .IP \f(CWrpp_stack_is_rc\fR 4
18810 .IX Xref "rpp_stack_is_rc"
18811 .IX Item "rpp_stack_is_rc"
18812 NOTE: \f(CW\*(C`rpp_stack_is_rc\*(C'\fR is \fBexperimental\fR and may change or be
18813 removed without notice.
18814 .Sp
18815 Returns a boolean value indicating whether the stack is currently
18816 reference\-counted. Note that if the stack is split (bottom half RC, top
18817 half non\-RC), this function returns false, even if the top half currently
18818 contains zero items.
18819 .RS 4
18820 .Sp
18821 .Vb 2
18822 \& bool rpp_stack_is_rc()
18823 \& bool Perl_rpp_stack_is_rc(pTHX)
18824 .Ve
18825 .RE
18826 .RS 4
18827 .RE
18828 .ie n .IP """rpp_try_AMAGIC_1""" 4
18829 .el .IP \f(CWrpp_try_AMAGIC_1\fR 4
18830 .IX Item "rpp_try_AMAGIC_1"
18831 .PD 0
18832 .ie n .IP """rpp_try_AMAGIC_2""" 4
18833 .el .IP \f(CWrpp_try_AMAGIC_2\fR 4
18834 .IX Xref "rpp_try_AMAGIC_1 rpp_try_AMAGIC_2"
18835 .IX Item "rpp_try_AMAGIC_2"
18836 .PD
18837 NOTE: both forms are \fBexperimental\fR and may change or be
18838 removed without notice.
18839 .Sp
18840 Check whether either of the one or two SVs at the top of the stack is
18841 magical or a ref, and in either case handle it specially: invoke get
18842 magic, call an overload method, or replace a ref with a temporary numeric
18843 value, as appropriate. If this function returns true, it indicates that
18844 the correct return value is already on the stack. Intended to be used at
18845 the beginning of the PP function for unary or binary ops.
18846 .RS 4
18847 .Sp
18848 .Vb 4
18849 \& bool rpp_try_AMAGIC_1( int method, int flags)
18850 \& bool Perl_rpp_try_AMAGIC_1(pTHX_ int method, int flags)
18851 \& bool rpp_try_AMAGIC_2( int method, int flags)
18852 \& bool Perl_rpp_try_AMAGIC_2(pTHX_ int method, int flags)
18853 .Ve
18854 .RE
18855 .RS 4
18856 .RE
18857 .ie n .IP """rpp_xpush_IMM*""" 4
18858 .el .IP \f(CWrpp_xpush_IMM*\fR 4
18859 .IX Item "rpp_xpush_IMM*"
18860 .PD 0
18861 .ie n .IP """rpp_xpush_1*""" 4
18862 .el .IP \f(CWrpp_xpush_1*\fR 4
18863 .IX Item "rpp_xpush_1*"
18864 .ie n .IP """rpp_xpush_2*""" 4
18865 .el .IP \f(CWrpp_xpush_2*\fR 4
18866 .IX Item "rpp_xpush_2*"
18867 .PD
18868 Described under \f(CW"rpp_push_1"\fR
18869 .ie n .IP """XSPP_wrapped""" 4
18870 .el .IP \f(CWXSPP_wrapped\fR 4
18871 .IX Xref "XSPP_wrapped"
18872 .IX Item "XSPP_wrapped"
18873 NOTE: \f(CW\*(C`XSPP_wrapped\*(C'\fR is \fBexperimental\fR and may change or be
18874 removed without notice.
18875 .Sp
18876 Declare and wrap a non\-reference\-counted PP\-style function.
18877 On traditional perl builds where the stack isn\*(Aqt reference\-counted, this
18878 just produces a function declaration like
18879 .Sp
18880 .Vb 1
18881 \& OP * xsppw_name(pTHX)
18882 .Ve
18883 .Sp
18884 Conversely, in ref\-counted builds it creates \fBxsppw_name()\fR as a small
18885 wrapper function which calls the real function via a wrapper which
18886 processes the args and return values to ensure that reference counts are
18887 properly handled for code which uses old\-style dSP, \fBPUSHs()\fR, \fBPOPs()\fR etc,
18888 which don\*(Aqt adjust the reference counts of the items they manipulate.
18889 .Sp
18890 xsppw_nargs indicates how many arguments the function consumes off the
18891 stack. It can be a constant value or an expression, such as
18892 .Sp
18893 .Vb 1
18894 \& ((PL_op\->op_flags & OPf_STACKED) ? 2 : 1)
18895 .Ve
18896 .Sp
18897 Alternatively if xsppw_nlists is 1, it indicates that the PP function
18898 consumes a list (or \- rarely \- if 2, consumes two lists, like
18899 \&\fBpp_aassign()\fR), as indicated by the top markstack position.
18900 .Sp
18901 This is intended as a temporary fix when converting XS code to run under
18902 PERL_RC_STACK builds. In the longer term, the PP function should be
18903 rewritten to replace \fBPUSHs()\fR etc with \fBrpp_push_1()\fR etc.
18904 .RS 4
18905 .Sp
18906 .Vb 1
18907 \& XSPP_wrapped(xsppw_name, I32 xsppw_nargs, I32 xsppw_nlists)
18908 .Ve
18909 .RE
18910 .RS 4
18911 .RE
18912 .SH "REGEXP Functions"
18913 .IX Xref "RX_OFFS_END RX_OFFS_START RX_OFFS_VALID RXp_OFFS_END RXp_OFFS_START RXp_OFFS_VALID"
18914 .IX Header "REGEXP Functions"
18915 .ie n .IP """pregcomp""" 4
18916 .el .IP \f(CWpregcomp\fR 4
18917 .IX Item "pregcomp"
18918 .PD 0
18919 .ie n .IP """pregexec""" 4
18920 .el .IP \f(CWpregexec\fR 4
18921 .IX Item "pregexec"
18922 .PD
18923 Described in perlreguts.
18924 .RS 4
18925 .Sp
18926 .Vb 12
18927 \& REGEXP * pregcomp( SV * const pattern,
18928 \& const U32 flags)
18929 \& REGEXP * Perl_pregcomp(pTHX_ SV * const pattern,
18930 \& const U32 flags)
18931 \& I32 pregexec( REGEXP * const prog,
18932 \& char *stringarg, char *strend,
18933 \& char *strbeg, SSize_t minend,
18934 \& SV *screamer, U32 nosave)
18935 \& I32 Perl_pregexec(pTHX_ REGEXP * const prog,
18936 \& char *stringarg, char *strend,
18937 \& char *strbeg, SSize_t minend,
18938 \& SV *screamer, U32 nosave)
18939 .Ve
18940 .RE
18941 .RS 4
18942 .RE
18943 .ie n .IP """re_compile""" 4
18944 .el .IP \f(CWre_compile\fR 4
18945 .IX Xref "re_compile"
18946 .IX Item "re_compile"
18947 Compile the regular expression pattern \f(CW\*(C`pattern\*(C'\fR, returning a pointer to the
18948 compiled object for later matching with the internal regex engine.
18949 .Sp
18950 This function is typically used by a custom regexp engine \f(CW\*(C`.comp()\*(C'\fR function
18951 to hand off to the core regexp engine those patterns it doesn\*(Aqt want to handle
18952 itself (typically passing through the same flags it was called with). In
18953 almost all other cases, a regexp should be compiled by calling "\f(CW\*(C`pregcomp\*(C'\fR"
18954 to compile using the currently active regexp engine.
18955 .Sp
18956 If \f(CW\*(C`pattern\*(C'\fR is already a \f(CW\*(C`REGEXP\*(C'\fR, this function does nothing but return a
18957 pointer to the input. Otherwise the PV is extracted and treated like a string
18958 representing a pattern. See perlre.
18959 .Sp
18960 The possible flags for \f(CW\*(C`rx_flags\*(C'\fR are documented in perlreapi. Their names
18961 all begin with \f(CW\*(C`RXf_\*(C'\fR.
18962 .RS 4
18963 .Sp
18964 .Vb 4
18965 \& REGEXP * re_compile( SV * const pattern,
18966 \& U32 orig_rx_flags)
18967 \& REGEXP * Perl_re_compile(pTHX_ SV * const pattern,
18968 \& U32 orig_rx_flags)
18969 .Ve
18970 .RE
18971 .RS 4
18972 .RE
18973 .ie n .IP """re_dup_guts""" 4
18974 .el .IP \f(CWre_dup_guts\fR 4
18975 .IX Xref "re_dup_guts"
18976 .IX Item "re_dup_guts"
18977 Duplicate a regexp.
18978 .Sp
18979 This routine is expected to clone a given regexp structure. It is only
18980 compiled under USE_ITHREADS.
18981 .Sp
18982 After all of the core data stored in struct regexp is duplicated
18983 the \f(CW\*(C`regexp_engine.dupe\*(C'\fR method is used to copy any private data
18984 stored in the *pprivate pointer. This allows extensions to handle
18985 any duplication they need to do.
18986 .RS 4
18987 .Sp
18988 .Vb 4
18989 \& void re_dup_guts( const REGEXP *sstr, REGEXP *dstr,
18990 \& CLONE_PARAMS *param)
18991 \& void Perl_re_dup_guts(pTHX_ const REGEXP *sstr, REGEXP *dstr,
18992 \& CLONE_PARAMS *param)
18993 .Ve
18994 .RE
18995 .RS 4
18996 .RE
18997 .ie n .IP """REGEX_LOCALE_CHARSET""" 4
18998 .el .IP \f(CWREGEX_LOCALE_CHARSET\fR 4
18999 .IX Item "REGEX_LOCALE_CHARSET"
19000 .PD 0
19001 .ie n .IP """REGEXP""" 4
19002 .el .IP \f(CWREGEXP\fR 4
19003 .IX Item "REGEXP"
19004 .PD
19005 Described in perlreapi.
19006 .ie n .IP """regexp""" 4
19007 .el .IP \f(CWregexp\fR 4
19008 .IX Xref "regexp"
19009 .IX Item "regexp"
19010 The regexp/REGEXP struct, see perlreapi for further documentation
19011 on the individual fields. The struct is ordered so that the most
19012 commonly used fields are placed at the start.
19013 .Sp
19014 Any patch that adds items to this struct will need to include
19015 changes to \fIsv.c\fR (\f(CWPerl_re_dup()\fR) and \fIregcomp.c\fR
19016 (\f(CWpregfree()\fR). This involves freeing or cloning items in the
19017 regexp\*(Aqs data array based on the data item\*(Aqs type.
19018 .ie n .IP """regexp_engine""" 4
19019 .el .IP \f(CWregexp_engine\fR 4
19020 .IX Xref "regexp_engine"
19021 .IX Item "regexp_engine"
19022 When a regexp is compiled, its \f(CW\*(C`engine\*(C'\fR field is then set to point at
19023 the appropriate structure, so that when it needs to be used Perl can find
19024 the right routines to do so.
19025 .Sp
19026 In order to install a new regexp handler, \f(CW$^H{regcomp}\fR is set
19027 to an integer which (when casted appropriately) resolves to one of these
19028 structures. When compiling, the \f(CW\*(C`comp\*(C'\fR method is executed, and the
19029 resulting \f(CW\*(C`regexp\*(C'\fR structure\*(Aqs engine field is expected to point back at
19030 the same structure.
19031 .Sp
19032 The pTHX_ symbol in the definition is a macro used by Perl under threading
19033 to provide an extra argument to the routine holding a pointer back to
19034 the interpreter that is executing the regexp. So under threading all
19035 routines get an extra argument.
19036 .ie n .IP """regexp_paren_pair""" 4
19037 .el .IP \f(CWregexp_paren_pair\fR 4
19038 .IX Item "regexp_paren_pair"
19039 Described in perlreapi.
19040 .ie n .IP """regmatch_info""" 4
19041 .el .IP \f(CWregmatch_info\fR 4
19042 .IX Xref "regmatch_info"
19043 .IX Item "regmatch_info"
19044 Some basic information about the current match that is created by
19045 Perl_regexec_flags and then passed to \fBregtry()\fR, \fBregmatch()\fR etc.
19046 It is allocated as a local var on the stack, so nothing should be
19047 stored in it that needs preserving or clearing up on \fBcroak()\fR.
19048 For that, see the aux_info and aux_info_eval members of the
19049 regmatch_state union.
19050 .ie n .IP """REXEC_COPY_SKIP_POST""" 4
19051 .el .IP \f(CWREXEC_COPY_SKIP_POST\fR 4
19052 .IX Item "REXEC_COPY_SKIP_POST"
19053 .PD 0
19054 .ie n .IP """REXEC_COPY_SKIP_PRE""" 4
19055 .el .IP \f(CWREXEC_COPY_SKIP_PRE\fR 4
19056 .IX Item "REXEC_COPY_SKIP_PRE"
19057 .ie n .IP """REXEC_COPY_STR""" 4
19058 .el .IP \f(CWREXEC_COPY_STR\fR 4
19059 .IX Item "REXEC_COPY_STR"
19060 .ie n .IP """RX_BUFF_IDX_CARET_FULLMATCH""" 4
19061 .el .IP \f(CWRX_BUFF_IDX_CARET_FULLMATCH\fR 4
19062 .IX Item "RX_BUFF_IDX_CARET_FULLMATCH"
19063 .ie n .IP """RX_BUFF_IDX_CARET_POSTMATCH""" 4
19064 .el .IP \f(CWRX_BUFF_IDX_CARET_POSTMATCH\fR 4
19065 .IX Item "RX_BUFF_IDX_CARET_POSTMATCH"
19066 .ie n .IP """RX_BUFF_IDX_CARET_PREMATCH""" 4
19067 .el .IP \f(CWRX_BUFF_IDX_CARET_PREMATCH\fR 4
19068 .IX Item "RX_BUFF_IDX_CARET_PREMATCH"
19069 .ie n .IP """RX_BUFF_IDX_FULLMATCH""" 4
19070 .el .IP \f(CWRX_BUFF_IDX_FULLMATCH\fR 4
19071 .IX Item "RX_BUFF_IDX_FULLMATCH"
19072 .ie n .IP """RX_BUFF_IDX_POSTMATCH""" 4
19073 .el .IP \f(CWRX_BUFF_IDX_POSTMATCH\fR 4
19074 .IX Item "RX_BUFF_IDX_POSTMATCH"
19075 .ie n .IP """RX_BUFF_IDX_PREMATCH""" 4
19076 .el .IP \f(CWRX_BUFF_IDX_PREMATCH\fR 4
19077 .IX Item "RX_BUFF_IDX_PREMATCH"
19078 .ie n .IP """RX_MATCH_COPIED""" 4
19079 .el .IP \f(CWRX_MATCH_COPIED\fR 4
19080 .IX Item "RX_MATCH_COPIED"
19081 .ie n .IP """RXapif_ALL""" 4
19082 .el .IP \f(CWRXapif_ALL\fR 4
19083 .IX Item "RXapif_ALL"
19084 .ie n .IP """RXapif_CLEAR""" 4
19085 .el .IP \f(CWRXapif_CLEAR\fR 4
19086 .IX Item "RXapif_CLEAR"
19087 .ie n .IP """RXapif_DELETE""" 4
19088 .el .IP \f(CWRXapif_DELETE\fR 4
19089 .IX Item "RXapif_DELETE"
19090 .ie n .IP """RXapif_EXISTS""" 4
19091 .el .IP \f(CWRXapif_EXISTS\fR 4
19092 .IX Item "RXapif_EXISTS"
19093 .ie n .IP """RXapif_FETCH""" 4
19094 .el .IP \f(CWRXapif_FETCH\fR 4
19095 .IX Item "RXapif_FETCH"
19096 .ie n .IP """RXapif_FIRSTKEY""" 4
19097 .el .IP \f(CWRXapif_FIRSTKEY\fR 4
19098 .IX Item "RXapif_FIRSTKEY"
19099 .ie n .IP """RXapif_NEXTKEY""" 4
19100 .el .IP \f(CWRXapif_NEXTKEY\fR 4
19101 .IX Item "RXapif_NEXTKEY"
19102 .ie n .IP """RXapif_ONE""" 4
19103 .el .IP \f(CWRXapif_ONE\fR 4
19104 .IX Item "RXapif_ONE"
19105 .ie n .IP """RXapif_REGNAME""" 4
19106 .el .IP \f(CWRXapif_REGNAME\fR 4
19107 .IX Item "RXapif_REGNAME"
19108 .ie n .IP """RXapif_REGNAMES""" 4
19109 .el .IP \f(CWRXapif_REGNAMES\fR 4
19110 .IX Item "RXapif_REGNAMES"
19111 .ie n .IP """RXapif_REGNAMES_COUNT""" 4
19112 .el .IP \f(CWRXapif_REGNAMES_COUNT\fR 4
19113 .IX Item "RXapif_REGNAMES_COUNT"
19114 .ie n .IP """RXapif_SCALAR""" 4
19115 .el .IP \f(CWRXapif_SCALAR\fR 4
19116 .IX Item "RXapif_SCALAR"
19117 .ie n .IP """RXapif_STORE""" 4
19118 .el .IP \f(CWRXapif_STORE\fR 4
19119 .IX Item "RXapif_STORE"
19120 .ie n .IP """RXf_NO_INPLACE_SUBST""" 4
19121 .el .IP \f(CWRXf_NO_INPLACE_SUBST\fR 4
19122 .IX Item "RXf_NO_INPLACE_SUBST"
19123 .ie n .IP """RXf_NULL""" 4
19124 .el .IP \f(CWRXf_NULL\fR 4
19125 .IX Item "RXf_NULL"
19126 .ie n .IP """RXf_SKIPWHITE""" 4
19127 .el .IP \f(CWRXf_SKIPWHITE\fR 4
19128 .IX Item "RXf_SKIPWHITE"
19129 .ie n .IP """RXf_SPLIT""" 4
19130 .el .IP \f(CWRXf_SPLIT\fR 4
19131 .IX Item "RXf_SPLIT"
19132 .ie n .IP """RXf_START_ONLY""" 4
19133 .el .IP \f(CWRXf_START_ONLY\fR 4
19134 .IX Item "RXf_START_ONLY"
19135 .ie n .IP """RXf_WHITE""" 4
19136 .el .IP \f(CWRXf_WHITE\fR 4
19137 .IX Item "RXf_WHITE"
19138 .ie n .IP """RXf_PMf_EXTENDED""" 4
19139 .el .IP \f(CWRXf_PMf_EXTENDED\fR 4
19140 .IX Item "RXf_PMf_EXTENDED"
19141 .ie n .IP """RXf_PMf_FOLD""" 4
19142 .el .IP \f(CWRXf_PMf_FOLD\fR 4
19143 .IX Item "RXf_PMf_FOLD"
19144 .ie n .IP """RXf_PMf_KEEPCOPY""" 4
19145 .el .IP \f(CWRXf_PMf_KEEPCOPY\fR 4
19146 .IX Item "RXf_PMf_KEEPCOPY"
19147 .ie n .IP """RXf_PMf_MULTILINE""" 4
19148 .el .IP \f(CWRXf_PMf_MULTILINE\fR 4
19149 .IX Item "RXf_PMf_MULTILINE"
19150 .ie n .IP """RXf_PMf_SINGLELINE""" 4
19151 .el .IP \f(CWRXf_PMf_SINGLELINE\fR 4
19152 .IX Item "RXf_PMf_SINGLELINE"
19153 .ie n .IP """RXf_SKIPWHITE*""" 4
19154 .el .IP \f(CWRXf_SKIPWHITE*\fR 4
19155 .IX Item "RXf_SKIPWHITE*"
19156 .ie n .IP """RXf_SPLIT*""" 4
19157 .el .IP \f(CWRXf_SPLIT*\fR 4
19158 .IX Item "RXf_SPLIT*"
19159 .ie n .IP """RXf_START_ONLY*""" 4
19160 .el .IP \f(CWRXf_START_ONLY*\fR 4
19161 .IX Item "RXf_START_ONLY*"
19162 .ie n .IP """RXf_WHITE*""" 4
19163 .el .IP \f(CWRXf_WHITE*\fR 4
19164 .IX Item "RXf_WHITE*"
19165 .ie n .IP """struct regexp""" 4
19166 .el .IP "\f(CWstruct regexp\fR" 4
19167 .IX Item "struct regexp"
19168 .ie n .IP """SV_SAVED_COPY""" 4
19169 .el .IP \f(CWSV_SAVED_COPY\fR 4
19170 .IX Item "SV_SAVED_COPY"
19171 .PD
19172 Described in perlreapi.
19173 .RS 4
19174 .Sp
19175 .Vb 1
19176 \& RX_MATCH_COPIED(const REGEXP * rx_sv)
19177 .Ve
19178 .RE
19179 .RS 4
19180 .RE
19181 .ie n .IP """SvRX""" 4
19182 .el .IP \f(CWSvRX\fR 4
19183 .IX Xref "SvRX"
19184 .IX Item "SvRX"
19185 Convenience macro to get the REGEXP from a SV. This is approximately
19186 equivalent to the following snippet:
19187 .Sp
19188 .Vb 6
19189 \& if (SvMAGICAL(sv))
19190 \& mg_get(sv);
19191 \& if (SvROK(sv))
19192 \& sv = MUTABLE_SV(SvRV(sv));
19193 \& if (SvTYPE(sv) == SVt_REGEXP)
19194 \& return (REGEXP*) sv;
19195 .Ve
19196 .Sp
19197 \&\f(CW\*(C`NULL\*(C'\fR will be returned if a REGEXP* is not found.
19198 .RS 4
19199 .Sp
19200 .Vb 1
19201 \& REGEXP * SvRX(SV *sv)
19202 .Ve
19203 .RE
19204 .RS 4
19205 .RE
19206 .ie n .IP """SvRXOK""" 4
19207 .el .IP \f(CWSvRXOK\fR 4
19208 .IX Xref "SvRXOK"
19209 .IX Item "SvRXOK"
19210 Returns a boolean indicating whether the SV (or the one it references)
19211 is a REGEXP.
19212 .Sp
19213 If you want to do something with the REGEXP* later use SvRX instead
19214 and check for NULL.
19215 .RS 4
19216 .Sp
19217 .Vb 1
19218 \& bool SvRXOK(SV* sv)
19219 .Ve
19220 .RE
19221 .RS 4
19222 .RE
19223 .SH "Reports and Formats"
19224 .IX Header "Reports and Formats"
19225 These are used in the simple report generation feature of Perl.
19226 See perlform.
19227 .ie n .IP """IoBOTTOM_GV""" 4
19228 .el .IP \f(CWIoBOTTOM_GV\fR 4
19229 .IX Item "IoBOTTOM_GV"
19230 .PD 0
19231 .ie n .IP """IoBOTTOM_NAME""" 4
19232 .el .IP \f(CWIoBOTTOM_NAME\fR 4
19233 .IX Item "IoBOTTOM_NAME"
19234 .ie n .IP """IoFMT_GV""" 4
19235 .el .IP \f(CWIoFMT_GV\fR 4
19236 .IX Item "IoFMT_GV"
19237 .ie n .IP """IoFMT_NAME""" 4
19238 .el .IP \f(CWIoFMT_NAME\fR 4
19239 .IX Item "IoFMT_NAME"
19240 .ie n .IP """IoLINES""" 4
19241 .el .IP \f(CWIoLINES\fR 4
19242 .IX Item "IoLINES"
19243 .ie n .IP """IoLINES_LEFT""" 4
19244 .el .IP \f(CWIoLINES_LEFT\fR 4
19245 .IX Item "IoLINES_LEFT"
19246 .ie n .IP """IoPAGE""" 4
19247 .el .IP \f(CWIoPAGE\fR 4
19248 .IX Item "IoPAGE"
19249 .ie n .IP """IoPAGE_LEN""" 4
19250 .el .IP \f(CWIoPAGE_LEN\fR 4
19251 .IX Item "IoPAGE_LEN"
19252 .ie n .IP """IoTOP_GV""" 4
19253 .el .IP \f(CWIoTOP_GV\fR 4
19254 .IX Item "IoTOP_GV"
19255 .ie n .IP """IoTOP_NAME""" 4
19256 .el .IP \f(CWIoTOP_NAME\fR 4
19257 .IX Item "IoTOP_NAME"
19258 .PD
19259 Described in perlguts.
19260 .RS 4
19261 .Sp
19262 .Vb 10
19263 \& GV * IoBOTTOM_GV (IO *io)
19264 \& char * IoBOTTOM_NAME(IO *io)
19265 \& GV * IoFMT_GV (IO *io)
19266 \& char * IoFMT_NAME (IO *io)
19267 \& IV IoLINES (IO *io)
19268 \& IV IoLINES_LEFT (IO *io)
19269 \& IV IoPAGE (IO *io)
19270 \& IV IoPAGE_LEN (IO *io)
19271 \& GV * IoTOP_GV (IO *io)
19272 \& char * IoTOP_NAME (IO *io)
19273 .Ve
19274 .RE
19275 .RS 4
19276 .RE
19277 .SH Signals
19278 .IX Header "Signals"
19279 .ie n .IP """HAS_SIGINFO_SI_ADDR""" 4
19280 .el .IP \f(CWHAS_SIGINFO_SI_ADDR\fR 4
19281 .IX Xref "HAS_SIGINFO_SI_ADDR"
19282 .IX Item "HAS_SIGINFO_SI_ADDR"
19283 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
19284 \&\f(CW\*(C`si_addr\*(C'\fR member
19285 .ie n .IP """HAS_SIGINFO_SI_BAND""" 4
19286 .el .IP \f(CWHAS_SIGINFO_SI_BAND\fR 4
19287 .IX Xref "HAS_SIGINFO_SI_BAND"
19288 .IX Item "HAS_SIGINFO_SI_BAND"
19289 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
19290 \&\f(CW\*(C`si_band\*(C'\fR member
19291 .ie n .IP """HAS_SIGINFO_SI_ERRNO""" 4
19292 .el .IP \f(CWHAS_SIGINFO_SI_ERRNO\fR 4
19293 .IX Xref "HAS_SIGINFO_SI_ERRNO"
19294 .IX Item "HAS_SIGINFO_SI_ERRNO"
19295 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
19296 \&\f(CW\*(C`si_errno\*(C'\fR member
19297 .ie n .IP """HAS_SIGINFO_SI_PID""" 4
19298 .el .IP \f(CWHAS_SIGINFO_SI_PID\fR 4
19299 .IX Xref "HAS_SIGINFO_SI_PID"
19300 .IX Item "HAS_SIGINFO_SI_PID"
19301 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
19302 \&\f(CW\*(C`si_pid\*(C'\fR member
19303 .ie n .IP """HAS_SIGINFO_SI_STATUS""" 4
19304 .el .IP \f(CWHAS_SIGINFO_SI_STATUS\fR 4
19305 .IX Xref "HAS_SIGINFO_SI_STATUS"
19306 .IX Item "HAS_SIGINFO_SI_STATUS"
19307 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
19308 \&\f(CW\*(C`si_status\*(C'\fR member
19309 .ie n .IP """HAS_SIGINFO_SI_UID""" 4
19310 .el .IP \f(CWHAS_SIGINFO_SI_UID\fR 4
19311 .IX Xref "HAS_SIGINFO_SI_UID"
19312 .IX Item "HAS_SIGINFO_SI_UID"
19313 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
19314 \&\f(CW\*(C`si_uid\*(C'\fR member
19315 .ie n .IP """HAS_SIGINFO_SI_VALUE""" 4
19316 .el .IP \f(CWHAS_SIGINFO_SI_VALUE\fR 4
19317 .IX Xref "HAS_SIGINFO_SI_VALUE"
19318 .IX Item "HAS_SIGINFO_SI_VALUE"
19319 This symbol, if defined, indicates that \f(CW\*(C`siginfo_t\*(C'\fR has the
19320 \&\f(CW\*(C`si_value\*(C'\fR member
19321 .ie n .IP """PERL_SIGNALS_UNSAFE_FLAG""" 4
19322 .el .IP \f(CWPERL_SIGNALS_UNSAFE_FLAG\fR 4
19323 .IX Xref "PERL_SIGNALS_UNSAFE_FLAG"
19324 .IX Item "PERL_SIGNALS_UNSAFE_FLAG"
19325 If this bit in \f(CW\*(C`PL_signals\*(C'\fR is set, the system is uing the pre\-Perl 5.8
19326 unsafe signals. See "PERL_SIGNALS" in perlrun and "Deferred Signals
19327 (Safe Signals)" in perlipc.
19328 .RS 4
19329 .Sp
19330 .Vb 1
19331 \& U32 PERL_SIGNALS_UNSAFE_FLAG
19332 .Ve
19333 .RE
19334 .RS 4
19335 .RE
19336 .ie n .IP """rsignal""" 4
19337 .el .IP \f(CWrsignal\fR 4
19338 .IX Xref "rsignal"
19339 .IX Item "rsignal"
19340 A wrapper for the C library functions \fBsigaction\fR\|(2) or \fBsignal\fR\|(2).
19341 Use this instead of those libc functions, as the Perl version gives the
19342 safest available implementation, and knows things that interact with the
19343 rest of the perl interpreter.
19344 .RS 4
19345 .Sp
19346 .Vb 2
19347 \& Sighandler_t rsignal( int i, Sighandler_t t)
19348 \& Sighandler_t Perl_rsignal(pTHX_ int i, Sighandler_t t)
19349 .Ve
19350 .RE
19351 .RS 4
19352 .RE
19353 .ie n .IP """rsignal_state""" 4
19354 .el .IP \f(CWrsignal_state\fR 4
19355 .IX Xref "rsignal_state"
19356 .IX Item "rsignal_state"
19357 Returns a the current signal handler for signal \f(CW\*(C`signo\*(C'\fR.
19358 See "\f(CW\*(C`rsignal\*(C'\fR".
19359 .RS 4
19360 .Sp
19361 .Vb 2
19362 \& Sighandler_t rsignal_state( int i)
19363 \& Sighandler_t Perl_rsignal_state(pTHX_ int i)
19364 .Ve
19365 .RE
19366 .RS 4
19367 .RE
19368 .ie n .IP """SIG_NAME""" 4
19369 .el .IP \f(CWSIG_NAME\fR 4
19370 .IX Xref "SIG_NAME"
19371 .IX Item "SIG_NAME"
19372 This symbol contains a list of signal names in order of
19373 signal number. This is intended
19374 to be used as a static array initialization, like this:
19375 .Sp
19376 .Vb 1
19377 \& char *sig_name[] = { SIG_NAME };
19378 .Ve
19379 .Sp
19380 The signals in the list are separated with commas, and each signal
19381 is surrounded by double quotes. There is no leading \f(CW\*(C`SIG\*(C'\fR in the signal
19382 name, i.e. \f(CW\*(C`SIGQUIT\*(C'\fR is known as "\f(CW\*(C`QUIT\*(C'\fR".
19383 Gaps in the signal numbers (up to \f(CW\*(C`NSIG\*(C'\fR) are filled in with \f(CW\*(C`NUMnn\*(C'\fR,
19384 etc., where nn is the actual signal number (e.g. \f(CW\*(C`NUM37\*(C'\fR).
19385 The signal number for \f(CW\*(C`sig_name[i]\*(C'\fR is stored in \f(CW\*(C`sig_num[i]\*(C'\fR.
19386 The last element is 0 to terminate the list with a \f(CW\*(C`NULL\*(C'\fR. This
19387 corresponds to the 0 at the end of the \f(CW\*(C`sig_name_init\*(C'\fR list.
19388 Note that this variable is initialized from the \f(CW\*(C`sig_name_init\*(C'\fR,
19389 not from \f(CW\*(C`sig_name\*(C'\fR (which is unused).
19390 .ie n .IP """SIG_NUM""" 4
19391 .el .IP \f(CWSIG_NUM\fR 4
19392 .IX Xref "SIG_NUM"
19393 .IX Item "SIG_NUM"
19394 This symbol contains a list of signal numbers, in the same order as the
19395 \&\f(CW\*(C`SIG_NAME\*(C'\fR list. It is suitable for static array initialization, as in:
19396 .Sp
19397 .Vb 1
19398 \& int sig_num[] = { SIG_NUM };
19399 .Ve
19400 .Sp
19401 The signals in the list are separated with commas, and the indices
19402 within that list and the \f(CW\*(C`SIG_NAME\*(C'\fR list match, so it\*(Aqs easy to compute
19403 the signal name from a number or vice versa at the price of a small
19404 dynamic linear lookup.
19405 Duplicates are allowed, but are moved to the end of the list.
19406 The signal number corresponding to \f(CW\*(C`sig_name[i]\*(C'\fR is \f(CW\*(C`sig_number[i]\*(C'\fR.
19407 if (i < \f(CW\*(C`NSIG\*(C'\fR) then \f(CW\*(C`sig_number[i]\*(C'\fR == i.
19408 The last element is 0, corresponding to the 0 at the end of
19409 the \f(CW\*(C`sig_name_init\*(C'\fR list.
19410 Note that this variable is initialized from the \f(CW\*(C`sig_num_init\*(C'\fR,
19411 not from \f(CW\*(C`sig_num\*(C'\fR (which is unused).
19412 .ie n .IP """SIG_SIZE""" 4
19413 .el .IP \f(CWSIG_SIZE\fR 4
19414 .IX Xref "SIG_SIZE"
19415 .IX Item "SIG_SIZE"
19416 This variable contains the number of elements of the \f(CW\*(C`SIG_NAME\*(C'\fR
19417 and \f(CW\*(C`SIG_NUM\*(C'\fR arrays, excluding the final \f(CW\*(C`NULL\*(C'\fR entry.
19418 .ie n .IP """Sigjmp_buf""" 4
19419 .el .IP \f(CWSigjmp_buf\fR 4
19420 .IX Xref "Sigjmp_buf"
19421 .IX Item "Sigjmp_buf"
19422 This is the buffer type to be used with Sigsetjmp and Siglongjmp.
19423 .ie n .IP """Siglongjmp""" 4
19424 .el .IP \f(CWSiglongjmp\fR 4
19425 .IX Xref "Siglongjmp"
19426 .IX Item "Siglongjmp"
19427 This macro is used in the same way as \f(CWsiglongjmp()\fR, but will invoke
19428 traditional \f(CWlongjmp()\fR if siglongjmp isn\*(Aqt available.
19429 See \f(CW"HAS_SIGSETJMP"\fR.
19430 .RS 4
19431 .Sp
19432 .Vb 1
19433 \& void Siglongjmp(jmp_buf env, int val)
19434 .Ve
19435 .RE
19436 .RS 4
19437 .RE
19438 .ie n .IP """Sigsetjmp""" 4
19439 .el .IP \f(CWSigsetjmp\fR 4
19440 .IX Xref "Sigsetjmp"
19441 .IX Item "Sigsetjmp"
19442 This macro is used in the same way as \f(CWsigsetjmp()\fR, but will invoke
19443 traditional \f(CWsetjmp()\fR if sigsetjmp isn\*(Aqt available.
19444 See \f(CW"HAS_SIGSETJMP"\fR.
19445 .RS 4
19446 .Sp
19447 .Vb 1
19448 \& int Sigsetjmp(jmp_buf env, int savesigs)
19449 .Ve
19450 .RE
19451 .RS 4
19452 .RE
19453 .ie n .IP """whichsig""" 4
19454 .el .IP \f(CWwhichsig\fR 4
19455 .IX Item "whichsig"
19456 .PD 0
19457 .ie n .IP """whichsig_pv""" 4
19458 .el .IP \f(CWwhichsig_pv\fR 4
19459 .IX Item "whichsig_pv"
19460 .ie n .IP """whichsig_pvn""" 4
19461 .el .IP \f(CWwhichsig_pvn\fR 4
19462 .IX Item "whichsig_pvn"
19463 .ie n .IP """whichsig_sv""" 4
19464 .el .IP \f(CWwhichsig_sv\fR 4
19465 .IX Xref "whichsig whichsig_pv whichsig_pvn whichsig_sv"
19466 .IX Item "whichsig_sv"
19467 .PD
19468 These all convert a signal name into its corresponding signal number;
19469 returning \-1 if no corresponding number was found.
19470 .Sp
19471 They differ only in the source of the signal name:
19472 .Sp
19473 \&\f(CW\*(C`whichsig_pv\*(C'\fR takes the name from the \f(CW\*(C`NUL\*(C'\fR\-terminated string starting at
19474 \&\f(CW\*(C`sig\*(C'\fR.
19475 .Sp
19476 \&\f(CW\*(C`whichsig\*(C'\fR is merely a different spelling, a synonym, of \f(CW\*(C`whichsig_pv\*(C'\fR.
19477 .Sp
19478 \&\f(CW\*(C`whichsig_pvn\*(C'\fR takes the name from the string starting at \f(CW\*(C`sig\*(C'\fR, with length
19479 \&\f(CW\*(C`len\*(C'\fR bytes.
19480 .Sp
19481 \&\f(CW\*(C`whichsig_sv\*(C'\fR takes the name from the PV stored in the SV \f(CW\*(C`sigsv\*(C'\fR.
19482 .RS 4
19483 .Sp
19484 .Vb 7
19485 \& I32 whichsig ( const char *sig)
19486 \& I32 whichsig_pv ( const char *sig)
19487 \& I32 Perl_whichsig_pv (pTHX_ const char *sig)
19488 \& I32 whichsig_pvn( const char *sig, STRLEN len)
19489 \& I32 Perl_whichsig_pvn(pTHX_ const char *sig, STRLEN len)
19490 \& I32 whichsig_sv ( SV *sigsv)
19491 \& I32 Perl_whichsig_sv (pTHX_ SV *sigsv)
19492 .Ve
19493 .RE
19494 .RS 4
19495 .RE
19496 .SH "Site configuration"
19497 .IX Header "Site configuration"
19498 These variables give details as to where various libraries,
19499 installation destinations, \fIetc.\fR, go, as well as what various
19500 installation options were selected
19501 .ie n .IP """ARCHLIB""" 4
19502 .el .IP \f(CWARCHLIB\fR 4
19503 .IX Xref "ARCHLIB"
19504 .IX Item "ARCHLIB"
19505 This variable, if defined, holds the name of the directory in
19506 which the user wants to put architecture\-dependent public
19507 library files for perl5. It is most often a local directory
19508 such as \fI/usr/local/lib\fR. Programs using this variable must be
19509 prepared to deal with filename expansion. If \f(CW\*(C`ARCHLIB\*(C'\fR is the
19510 same as \f(CW\*(C`PRIVLIB\*(C'\fR, it is not defined, since presumably the
19511 program already searches \f(CW\*(C`PRIVLIB\*(C'\fR.
19512 .ie n .IP """ARCHLIB_EXP""" 4
19513 .el .IP \f(CWARCHLIB_EXP\fR 4
19514 .IX Xref "ARCHLIB_EXP"
19515 .IX Item "ARCHLIB_EXP"
19516 This symbol contains the ~name expanded version of \f(CW\*(C`ARCHLIB\*(C'\fR, to be used
19517 in programs that are not prepared to deal with ~ expansion at run\-time.
19518 .ie n .IP """ARCHNAME""" 4
19519 .el .IP \f(CWARCHNAME\fR 4
19520 .IX Xref "ARCHNAME"
19521 .IX Item "ARCHNAME"
19522 This symbol holds a string representing the architecture name.
19523 It may be used to construct an architecture\-dependant pathname
19524 where library files may be held under a private library, for
19525 instance.
19526 .ie n .IP """BIN""" 4
19527 .el .IP \f(CWBIN\fR 4
19528 .IX Xref "BIN"
19529 .IX Item "BIN"
19530 This symbol holds the path of the bin directory where the package will
19531 be installed. Program must be prepared to deal with ~name substitution.
19532 .ie n .IP """BIN_EXP""" 4
19533 .el .IP \f(CWBIN_EXP\fR 4
19534 .IX Xref "BIN_EXP"
19535 .IX Item "BIN_EXP"
19536 This symbol is the filename expanded version of the \f(CW\*(C`BIN\*(C'\fR symbol, for
19537 programs that do not want to deal with that at run\-time.
19538 .ie n .IP """INSTALL_USR_BIN_PERL""" 4
19539 .el .IP \f(CWINSTALL_USR_BIN_PERL\fR 4
19540 .IX Xref "INSTALL_USR_BIN_PERL"
19541 .IX Item "INSTALL_USR_BIN_PERL"
19542 This symbol, if defined, indicates that Perl is to be installed
19543 also as \fI/usr/bin/perl\fR.
19544 .ie n .IP """MULTIARCH""" 4
19545 .el .IP \f(CWMULTIARCH\fR 4
19546 .IX Xref "MULTIARCH"
19547 .IX Item "MULTIARCH"
19548 This symbol, if defined, signifies that the build
19549 process will produce some binary files that are going to be
19550 used in a cross\-platform environment. This is the case for
19551 example with the NeXT "fat" binaries that contain executables
19552 for several \f(CW\*(C`CPUs\*(C'\fR.
19553 .ie n .IP """PERL_INC_VERSION_LIST""" 4
19554 .el .IP \f(CWPERL_INC_VERSION_LIST\fR 4
19555 .IX Xref "PERL_INC_VERSION_LIST"
19556 .IX Item "PERL_INC_VERSION_LIST"
19557 This variable specifies the list of subdirectories in over
19558 which \fIperl.c\fR:\f(CWincpush()\fR and \fIlib/lib.pm\fR will automatically
19559 search when adding directories to @\f(CW\*(C`INC\*(C'\fR, in a format suitable
19560 for a C initialization string. See the \f(CW\*(C`inc_version_list\*(C'\fR entry
19561 in Porting/Glossary for more details.
19562 .ie n .IP """PERL_OTHERLIBDIRS""" 4
19563 .el .IP \f(CWPERL_OTHERLIBDIRS\fR 4
19564 .IX Xref "PERL_OTHERLIBDIRS"
19565 .IX Item "PERL_OTHERLIBDIRS"
19566 This variable contains a colon\-separated set of paths for the perl
19567 binary to search for additional library files or modules.
19568 These directories will be tacked to the end of @\f(CW\*(C`INC\*(C'\fR.
19569 Perl will automatically search below each path for version\-
19570 and architecture\-specific directories. See \f(CW"PERL_INC_VERSION_LIST"\fR
19571 for more details.
19572 .ie n .IP """PERL_RELOCATABLE_INC""" 4
19573 .el .IP \f(CWPERL_RELOCATABLE_INC\fR 4
19574 .IX Xref "PERL_RELOCATABLE_INC"
19575 .IX Item "PERL_RELOCATABLE_INC"
19576 This symbol, if defined, indicates that we\*(Aqd like to relocate entries
19577 in @\f(CW\*(C`INC\*(C'\fR at run time based on the location of the perl binary.
19578 .ie n .IP """PERL_TARGETARCH""" 4
19579 .el .IP \f(CWPERL_TARGETARCH\fR 4
19580 .IX Xref "PERL_TARGETARCH"
19581 .IX Item "PERL_TARGETARCH"
19582 This symbol, if defined, indicates the target architecture
19583 Perl has been cross\-compiled to. Undefined if not a cross\-compile.
19584 .ie n .IP """PERL_USE_DEVEL""" 4
19585 .el .IP \f(CWPERL_USE_DEVEL\fR 4
19586 .IX Xref "PERL_USE_DEVEL"
19587 .IX Item "PERL_USE_DEVEL"
19588 This symbol, if defined, indicates that Perl was configured with
19589 \&\f(CW\*(C`\-Dusedevel\*(C'\fR, to enable development features. This should not be
19590 done for production builds.
19591 .ie n .IP """PERL_VENDORARCH""" 4
19592 .el .IP \f(CWPERL_VENDORARCH\fR 4
19593 .IX Xref "PERL_VENDORARCH"
19594 .IX Item "PERL_VENDORARCH"
19595 If defined, this symbol contains the name of a private library.
19596 The library is private in the sense that it needn\*(Aqt be in anyone\*(Aqs
19597 execution path, but it should be accessible by the world.
19598 It may have a ~ on the front.
19599 The standard distribution will put nothing in this directory.
19600 Vendors who distribute perl may wish to place their own
19601 architecture\-dependent modules and extensions in this directory with
19602 .Sp
19603 .Vb 1
19604 \& MakeMaker Makefile.PL INSTALLDIRS=vendor
19605 .Ve
19606 .Sp
19607 or equivalent. See \fIINSTALL\fR for details.
19608 .ie n .IP """PERL_VENDORARCH_EXP""" 4
19609 .el .IP \f(CWPERL_VENDORARCH_EXP\fR 4
19610 .IX Xref "PERL_VENDORARCH_EXP"
19611 .IX Item "PERL_VENDORARCH_EXP"
19612 This symbol contains the ~name expanded version of \f(CW\*(C`PERL_VENDORARCH\*(C'\fR, to be used
19613 in programs that are not prepared to deal with ~ expansion at run\-time.
19614 .ie n .IP """PERL_VENDORLIB_EXP""" 4
19615 .el .IP \f(CWPERL_VENDORLIB_EXP\fR 4
19616 .IX Xref "PERL_VENDORLIB_EXP"
19617 .IX Item "PERL_VENDORLIB_EXP"
19618 This symbol contains the ~name expanded version of \f(CW\*(C`VENDORLIB\*(C'\fR, to be used
19619 in programs that are not prepared to deal with ~ expansion at run\-time.
19620 .ie n .IP """PERL_VENDORLIB_STEM""" 4
19621 .el .IP \f(CWPERL_VENDORLIB_STEM\fR 4
19622 .IX Xref "PERL_VENDORLIB_STEM"
19623 .IX Item "PERL_VENDORLIB_STEM"
19624 This define is \f(CW\*(C`PERL_VENDORLIB_EXP\*(C'\fR with any trailing version\-specific component
19625 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
19626 be tacked onto this variable to generate a list of directories to search.
19627 .ie n .IP """PRIVLIB""" 4
19628 .el .IP \f(CWPRIVLIB\fR 4
19629 .IX Xref "PRIVLIB"
19630 .IX Item "PRIVLIB"
19631 This symbol contains the name of the private library for this package.
19632 The library is private in the sense that it needn\*(Aqt be in anyone\*(Aqs
19633 execution path, but it should be accessible by the world. The program
19634 should be prepared to do ~ expansion.
19635 .ie n .IP """PRIVLIB_EXP""" 4
19636 .el .IP \f(CWPRIVLIB_EXP\fR 4
19637 .IX Xref "PRIVLIB_EXP"
19638 .IX Item "PRIVLIB_EXP"
19639 This symbol contains the ~name expanded version of \f(CW\*(C`PRIVLIB\*(C'\fR, to be used
19640 in programs that are not prepared to deal with ~ expansion at run\-time.
19641 .ie n .IP """SITEARCH""" 4
19642 .el .IP \f(CWSITEARCH\fR 4
19643 .IX Xref "SITEARCH"
19644 .IX Item "SITEARCH"
19645 This symbol contains the name of the private library for this package.
19646 The library is private in the sense that it needn\*(Aqt be in anyone\*(Aqs
19647 execution path, but it should be accessible by the world. The program
19648 should be prepared to do ~ expansion.
19649 The standard distribution will put nothing in this directory.
19650 After perl has been installed, users may install their own local
19651 architecture\-dependent modules in this directory with
19652 .Sp
19653 .Vb 1
19654 \& MakeMaker Makefile.PL
19655 .Ve
19656 .Sp
19657 or equivalent. See \fIINSTALL\fR for details.
19658 .ie n .IP """SITEARCH_EXP""" 4
19659 .el .IP \f(CWSITEARCH_EXP\fR 4
19660 .IX Xref "SITEARCH_EXP"
19661 .IX Item "SITEARCH_EXP"
19662 This symbol contains the ~name expanded version of \f(CW\*(C`SITEARCH\*(C'\fR, to be used
19663 in programs that are not prepared to deal with ~ expansion at run\-time.
19664 .ie n .IP """SITELIB""" 4
19665 .el .IP \f(CWSITELIB\fR 4
19666 .IX Xref "SITELIB"
19667 .IX Item "SITELIB"
19668 This symbol contains the name of the private library for this package.
19669 The library is private in the sense that it needn\*(Aqt be in anyone\*(Aqs
19670 execution path, but it should be accessible by the world. The program
19671 should be prepared to do ~ expansion.
19672 The standard distribution will put nothing in this directory.
19673 After perl has been installed, users may install their own local
19674 architecture\-independent modules in this directory with
19675 .Sp
19676 .Vb 1
19677 \& MakeMaker Makefile.PL
19678 .Ve
19679 .Sp
19680 or equivalent. See \fIINSTALL\fR for details.
19681 .ie n .IP """SITELIB_EXP""" 4
19682 .el .IP \f(CWSITELIB_EXP\fR 4
19683 .IX Xref "SITELIB_EXP"
19684 .IX Item "SITELIB_EXP"
19685 This symbol contains the ~name expanded version of \f(CW\*(C`SITELIB\*(C'\fR, to be used
19686 in programs that are not prepared to deal with ~ expansion at run\-time.
19687 .ie n .IP """SITELIB_STEM""" 4
19688 .el .IP \f(CWSITELIB_STEM\fR 4
19689 .IX Xref "SITELIB_STEM"
19690 .IX Item "SITELIB_STEM"
19691 This define is \f(CW\*(C`SITELIB_EXP\*(C'\fR with any trailing version\-specific component
19692 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
19693 be tacked onto this variable to generate a list of directories to search.
19694 .ie n .IP """STARTPERL""" 4
19695 .el .IP \f(CWSTARTPERL\fR 4
19696 .IX Xref "STARTPERL"
19697 .IX Item "STARTPERL"
19698 This variable contains the string to put in front of a perl
19699 script to make sure (one hopes) that it runs with perl and not
19700 some shell.
19701 .ie n .IP """USE_BSD_GETPGRP""" 4
19702 .el .IP \f(CWUSE_BSD_GETPGRP\fR 4
19703 .IX Xref "USE_BSD_GETPGRP"
19704 .IX Item "USE_BSD_GETPGRP"
19705 This symbol, if defined, indicates that getpgrp needs one
19706 arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none.
19707 .ie n .IP """USE_BSD_SETPGRP""" 4
19708 .el .IP \f(CWUSE_BSD_SETPGRP\fR 4
19709 .IX Xref "USE_BSD_SETPGRP"
19710 .IX Item "USE_BSD_SETPGRP"
19711 This symbol, if defined, indicates that setpgrp needs two
19712 arguments whereas \f(CW\*(C`USG\*(C'\fR one needs none. See also \f(CW"HAS_SETPGID"\fR
19713 for a \f(CW\*(C`POSIX\*(C'\fR interface.
19714 .ie n .IP """USE_C_BACKTRACE""" 4
19715 .el .IP \f(CWUSE_C_BACKTRACE\fR 4
19716 .IX Xref "USE_C_BACKTRACE"
19717 .IX Item "USE_C_BACKTRACE"
19718 This symbol, if defined, indicates that Perl should
19719 be built with support for backtrace.
19720 .ie n .IP """USE_CPLUSPLUS""" 4
19721 .el .IP \f(CWUSE_CPLUSPLUS\fR 4
19722 .IX Xref "USE_CPLUSPLUS"
19723 .IX Item "USE_CPLUSPLUS"
19724 This symbol, if defined, indicates that a C++ compiler was
19725 used to compiled Perl and will be used to compile extensions.
19726 .ie n .IP """USE_CROSS_COMPILE""" 4
19727 .el .IP \f(CWUSE_CROSS_COMPILE\fR 4
19728 .IX Xref "USE_CROSS_COMPILE"
19729 .IX Item "USE_CROSS_COMPILE"
19730 This symbol, if defined, indicates that Perl is being cross\-compiled.
19731 .ie n .IP """USE_DTRACE""" 4
19732 .el .IP \f(CWUSE_DTRACE\fR 4
19733 .IX Xref "USE_DTRACE"
19734 .IX Item "USE_DTRACE"
19735 This symbol, if defined, indicates that Perl should
19736 be built with support for DTrace.
19737 .ie n .IP """USE_DYNAMIC_LOADING""" 4
19738 .el .IP \f(CWUSE_DYNAMIC_LOADING\fR 4
19739 .IX Xref "USE_DYNAMIC_LOADING"
19740 .IX Item "USE_DYNAMIC_LOADING"
19741 This symbol, if defined, indicates that dynamic loading of
19742 some sort is available.
19743 .ie n .IP """USE_FAST_STDIO""" 4
19744 .el .IP \f(CWUSE_FAST_STDIO\fR 4
19745 .IX Xref "USE_FAST_STDIO"
19746 .IX Item "USE_FAST_STDIO"
19747 This symbol, if defined, indicates that Perl should
19748 be built to use \*(Aqfast stdio\*(Aq.
19749 Defaults to define in Perls 5.8 and earlier, to undef later.
19750 .ie n .IP """USE_ITHREADS""" 4
19751 .el .IP \f(CWUSE_ITHREADS\fR 4
19752 .IX Xref "USE_ITHREADS"
19753 .IX Item "USE_ITHREADS"
19754 This symbol, if defined, indicates that Perl should be built to
19755 use the interpreter\-based threading implementation.
19756 .ie n .IP """USE_KERN_PROC_PATHNAME""" 4
19757 .el .IP \f(CWUSE_KERN_PROC_PATHNAME\fR 4
19758 .IX Xref "USE_KERN_PROC_PATHNAME"
19759 .IX Item "USE_KERN_PROC_PATHNAME"
19760 This symbol, if defined, indicates that we can use sysctl with
19761 \&\f(CW\*(C`KERN_PROC_PATHNAME\*(C'\fR to get a full path for the executable, and hence
19762 convert $^X to an absolute path.
19763 .ie n .IP """USE_LARGE_FILES""" 4
19764 .el .IP \f(CWUSE_LARGE_FILES\fR 4
19765 .IX Xref "USE_LARGE_FILES"
19766 .IX Item "USE_LARGE_FILES"
19767 This symbol, if defined, indicates that large file support
19768 should be used when available.
19769 .ie n .IP """USE_LONG_DOUBLE""" 4
19770 .el .IP \f(CWUSE_LONG_DOUBLE\fR 4
19771 .IX Xref "USE_LONG_DOUBLE"
19772 .IX Item "USE_LONG_DOUBLE"
19773 This symbol, if defined, indicates that long doubles should
19774 be used when available.
19775 .ie n .IP """USE_MORE_BITS""" 4
19776 .el .IP \f(CWUSE_MORE_BITS\fR 4
19777 .IX Xref "USE_MORE_BITS"
19778 .IX Item "USE_MORE_BITS"
19779 This symbol, if defined, indicates that 64\-bit interfaces and
19780 long doubles should be used when available.
19781 .ie n .IP """USE_NSGETEXECUTABLEPATH""" 4
19782 .el .IP \f(CWUSE_NSGETEXECUTABLEPATH\fR 4
19783 .IX Xref "USE_NSGETEXECUTABLEPATH"
19784 .IX Item "USE_NSGETEXECUTABLEPATH"
19785 This symbol, if defined, indicates that we can use \f(CW\*(C`_NSGetExecutablePath\*(C'\fR
19786 and realpath to get a full path for the executable, and hence convert
19787 $^X to an absolute path.
19788 .ie n .IP """USE_PERLIO""" 4
19789 .el .IP \f(CWUSE_PERLIO\fR 4
19790 .IX Xref "USE_PERLIO"
19791 .IX Item "USE_PERLIO"
19792 This symbol, if defined, indicates that the PerlIO abstraction should
19793 be used throughout. If not defined, stdio should be
19794 used in a fully backward compatible manner.
19795 .ie n .IP """USE_QUADMATH""" 4
19796 .el .IP \f(CWUSE_QUADMATH\fR 4
19797 .IX Xref "USE_QUADMATH"
19798 .IX Item "USE_QUADMATH"
19799 This symbol, if defined, indicates that the quadmath library should
19800 be used when available.
19801 .ie n .IP """USE_REENTRANT_API""" 4
19802 .el .IP \f(CWUSE_REENTRANT_API\fR 4
19803 .IX Xref "USE_REENTRANT_API"
19804 .IX Item "USE_REENTRANT_API"
19805 This symbol, if defined, indicates that Perl should
19806 try to use the various \f(CW\*(C`_r\*(C'\fR versions of library functions.
19807 This is extremely experimental.
19808 .ie n .IP """USE_SEMCTL_SEMID_DS""" 4
19809 .el .IP \f(CWUSE_SEMCTL_SEMID_DS\fR 4
19810 .IX Xref "USE_SEMCTL_SEMID_DS"
19811 .IX Item "USE_SEMCTL_SEMID_DS"
19812 This symbol, if defined, indicates that \f(CW\*(C`struct semid_ds\*(C'\fR * is
19813 used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR.
19814 .ie n .IP """USE_SEMCTL_SEMUN""" 4
19815 .el .IP \f(CWUSE_SEMCTL_SEMUN\fR 4
19816 .IX Xref "USE_SEMCTL_SEMUN"
19817 .IX Item "USE_SEMCTL_SEMUN"
19818 This symbol, if defined, indicates that \f(CW\*(C`union semun\*(C'\fR is
19819 used for semctl \f(CW\*(C`IPC_STAT\*(C'\fR.
19820 .ie n .IP """USE_SITECUSTOMIZE""" 4
19821 .el .IP \f(CWUSE_SITECUSTOMIZE\fR 4
19822 .IX Xref "USE_SITECUSTOMIZE"
19823 .IX Item "USE_SITECUSTOMIZE"
19824 This symbol, if defined, indicates that sitecustomize should
19825 be used.
19826 .ie n .IP """USE_SOCKS""" 4
19827 .el .IP \f(CWUSE_SOCKS\fR 4
19828 .IX Xref "USE_SOCKS"
19829 .IX Item "USE_SOCKS"
19830 This symbol, if defined, indicates that Perl should
19831 be built to use socks.
19832 .ie n .IP """USE_STAT_BLOCKS""" 4
19833 .el .IP \f(CWUSE_STAT_BLOCKS\fR 4
19834 .IX Xref "USE_STAT_BLOCKS"
19835 .IX Item "USE_STAT_BLOCKS"
19836 This symbol is defined if this system has a stat structure declaring
19837 \&\f(CW\*(C`st_blksize\*(C'\fR and \f(CW\*(C`st_blocks\*(C'\fR.
19838 .ie n .IP """USE_STDIO_BASE""" 4
19839 .el .IP \f(CWUSE_STDIO_BASE\fR 4
19840 .IX Xref "USE_STDIO_BASE"
19841 .IX Item "USE_STDIO_BASE"
19842 This symbol is defined if the \f(CW\*(C`_base\*(C'\fR field (or similar) of the
19843 stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer for
19844 a file handle. If this is defined, then the \f(CWFILE_base(fp)\fR macro
19845 will also be defined and should be used to access this field.
19846 Also, the \f(CWFILE_bufsiz(fp)\fR macro will be defined and should be used
19847 to determine the number of bytes in the buffer. \f(CW\*(C`USE_STDIO_BASE\*(C'\fR
19848 will never be defined unless \f(CW\*(C`USE_STDIO_PTR\*(C'\fR is.
19849 .ie n .IP """USE_STDIO_PTR""" 4
19850 .el .IP \f(CWUSE_STDIO_PTR\fR 4
19851 .IX Xref "USE_STDIO_PTR"
19852 .IX Item "USE_STDIO_PTR"
19853 This symbol is defined if the \f(CW\*(C`_ptr\*(C'\fR and \f(CW\*(C`_cnt\*(C'\fR fields (or similar)
19854 of the stdio \f(CW\*(C`FILE\*(C'\fR structure can be used to access the stdio buffer
19855 for a file handle. If this is defined, then the \f(CWFILE_ptr(fp)\fR
19856 and \f(CWFILE_cnt(fp)\fR macros will also be defined and should be used
19857 to access these fields.
19858 .ie n .IP """USE_STRICT_BY_DEFAULT""" 4
19859 .el .IP \f(CWUSE_STRICT_BY_DEFAULT\fR 4
19860 .IX Xref "USE_STRICT_BY_DEFAULT"
19861 .IX Item "USE_STRICT_BY_DEFAULT"
19862 This symbol, if defined, enables additional defaults.
19863 At this time it only enables implicit strict by default.
19864 .ie n .IP """USE_THREADS""" 4
19865 .el .IP \f(CWUSE_THREADS\fR 4
19866 .IX Xref "USE_THREADS"
19867 .IX Item "USE_THREADS"
19868 This symbol, if defined, indicates that Perl should
19869 be built to use threads. At present, it is a synonym for
19870 and \f(CW\*(C`USE_ITHREADS\*(C'\fR, but eventually the source ought to be
19871 changed to use this to mean \f(CW\*(C`_any_\*(C'\fR threading implementation.
19872 .ie n .IP """USE_64_BIT_ALL""" 4
19873 .el .IP \f(CWUSE_64_BIT_ALL\fR 4
19874 .IX Xref "USE_64_BIT_ALL"
19875 .IX Item "USE_64_BIT_ALL"
19876 This symbol, if defined, indicates that 64\-bit integers should
19877 be used when available. If not defined, the native integers
19878 will be used (be they 32 or 64 bits). The maximal possible
19879 64\-bitness is employed: LP64 or \f(CW\*(C`ILP64\*(C'\fR, meaning that you will
19880 be able to use more than 2 gigabytes of memory. This mode is
19881 even more binary incompatible than \f(CW\*(C`USE_64_BIT_INT\*(C'\fR. You may not
19882 be able to run the resulting executable in a 32\-bit \f(CW\*(C`CPU\*(C'\fR at all or
19883 you may need at least to reboot your OS to 64\-bit mode.
19884 .ie n .IP """USE_64_BIT_INT""" 4
19885 .el .IP \f(CWUSE_64_BIT_INT\fR 4
19886 .IX Xref "USE_64_BIT_INT"
19887 .IX Item "USE_64_BIT_INT"
19888 This symbol, if defined, indicates that 64\-bit integers should
19889 be used when available. If not defined, the native integers
19890 will be employed (be they 32 or 64 bits). The minimal possible
19891 64\-bitness is used, just enough to get 64\-bit integers into Perl.
19892 This may mean using for example "long longs", while your memory
19893 may still be limited to 2 gigabytes.
19894 .SH "Sockets configuration values"
19895 .IX Header "Sockets configuration values"
19896 .ie n .IP """HAS_SOCKADDR_IN6""" 4
19897 .el .IP \f(CWHAS_SOCKADDR_IN6\fR 4
19898 .IX Xref "HAS_SOCKADDR_IN6"
19899 .IX Item "HAS_SOCKADDR_IN6"
19900 This symbol, if defined, indicates the availability of
19901 \&\f(CW\*(C`struct sockaddr_in6\*(C'\fR;
19902 .ie n .IP """HAS_SOCKADDR_SA_LEN""" 4
19903 .el .IP \f(CWHAS_SOCKADDR_SA_LEN\fR 4
19904 .IX Xref "HAS_SOCKADDR_SA_LEN"
19905 .IX Item "HAS_SOCKADDR_SA_LEN"
19906 This symbol, if defined, indicates that the \f(CW\*(C`struct sockaddr\*(C'\fR
19907 structure has a member called \f(CW\*(C`sa_len\*(C'\fR, indicating the length of
19908 the structure.
19909 .ie n .IP """HAS_SOCKADDR_STORAGE""" 4
19910 .el .IP \f(CWHAS_SOCKADDR_STORAGE\fR 4
19911 .IX Xref "HAS_SOCKADDR_STORAGE"
19912 .IX Item "HAS_SOCKADDR_STORAGE"
19913 This symbol, if defined, indicates the availability of
19914 \&\f(CW\*(C`struct sockaddr_storage\*(C'\fR;
19915 .ie n .IP """HAS_SOCKATMARK""" 4
19916 .el .IP \f(CWHAS_SOCKATMARK\fR 4
19917 .IX Xref "HAS_SOCKATMARK"
19918 .IX Item "HAS_SOCKATMARK"
19919 This symbol, if defined, indicates that the \f(CW\*(C`sockatmark\*(C'\fR routine is
19920 available to test whether a socket is at the out\-of\-band mark.
19921 .ie n .IP """HAS_SOCKET""" 4
19922 .el .IP \f(CWHAS_SOCKET\fR 4
19923 .IX Xref "HAS_SOCKET"
19924 .IX Item "HAS_SOCKET"
19925 This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CW\*(C`socket\*(C'\fR interface is
19926 supported.
19927 .ie n .IP """HAS_SOCKETPAIR""" 4
19928 .el .IP \f(CWHAS_SOCKETPAIR\fR 4
19929 .IX Xref "HAS_SOCKETPAIR"
19930 .IX Item "HAS_SOCKETPAIR"
19931 This symbol, if defined, indicates that the \f(CW\*(C`BSD\*(C'\fR \f(CWsocketpair()\fR call is
19932 supported.
19933 .ie n .IP """HAS_SOCKS5_INIT""" 4
19934 .el .IP \f(CWHAS_SOCKS5_INIT\fR 4
19935 .IX Xref "HAS_SOCKS5_INIT"
19936 .IX Item "HAS_SOCKS5_INIT"
19937 This symbol, if defined, indicates that the \f(CW\*(C`socks5_init\*(C'\fR routine is
19938 available to initialize \f(CW\*(C`SOCKS\*(C'\fR 5.
19939 .ie n .IP """I_SOCKS""" 4
19940 .el .IP \f(CWI_SOCKS\fR 4
19941 .IX Xref "I_SOCKS"
19942 .IX Item "I_SOCKS"
19943 This symbol, if defined, indicates that \fIsocks.h\fR exists and
19944 should be included.
19945 .RS 4
19946 .Sp
19947 .Vb 3
19948 \& #ifdef I_SOCKS
19949 \& #include <socks.h>
19950 \& #endif
19951 .Ve
19952 .RE
19953 .RS 4
19954 .RE
19955 .ie n .IP """I_SYS_SOCKIO""" 4
19956 .el .IP \f(CWI_SYS_SOCKIO\fR 4
19957 .IX Xref "I_SYS_SOCKIO"
19958 .IX Item "I_SYS_SOCKIO"
19959 This symbol, if defined, indicates the \fIsys/sockio.h\fR should be included
19960 to get socket ioctl options, like \f(CW\*(C`SIOCATMARK\*(C'\fR.
19961 .RS 4
19962 .Sp
19963 .Vb 3
19964 \& #ifdef I_SYS_SOCKIO
19965 \& #include <sys_sockio.h>
19966 \& #endif
19967 .Ve
19968 .RE
19969 .RS 4
19970 .RE
19971 .SH "Source Filters"
19972 .IX Header "Source Filters"
19973 .ie n .IP """apply_builtin_cv_attributes""" 4
19974 .el .IP \f(CWapply_builtin_cv_attributes\fR 4
19975 .IX Xref "apply_builtin_cv_attributes"
19976 .IX Item "apply_builtin_cv_attributes"
19977 Given an OP_LIST containing attribute definitions, filter it for known builtin
19978 attributes to apply to the cv, returning a possibly\-smaller list containing
19979 just the remaining ones.
19980 .RS 4
19981 .Sp
19982 .Vb 4
19983 \& OP * apply_builtin_cv_attributes( CV *cv,
19984 \& OP *attrlist)
19985 \& OP * Perl_apply_builtin_cv_attributes(pTHX_ CV *cv,
19986 \& OP *attrlist)
19987 .Ve
19988 .RE
19989 .RS 4
19990 .RE
19991 .ie n .IP """filter_add""" 4
19992 .el .IP \f(CWfilter_add\fR 4
19993 .IX Item "filter_add"
19994 Described in perlfilter.
19995 .RS 4
19996 .Sp
19997 .Vb 2
19998 \& SV * filter_add( filter_t funcp, SV *datasv)
19999 \& SV * Perl_filter_add(pTHX_ filter_t funcp, SV *datasv)
20000 .Ve
20001 .RE
20002 .RS 4
20003 .RE
20004 .ie n .IP """filter_del""" 4
20005 .el .IP \f(CWfilter_del\fR 4
20006 .IX Xref "filter_del"
20007 .IX Item "filter_del"
20008 Delete most recently added instance of the filter function argument
20009 .RS 4
20010 .Sp
20011 .Vb 2
20012 \& void filter_del( filter_t funcp)
20013 \& void Perl_filter_del(pTHX_ filter_t funcp)
20014 .Ve
20015 .RE
20016 .RS 4
20017 .RE
20018 .ie n .IP """filter_read""" 4
20019 .el .IP \f(CWfilter_read\fR 4
20020 .IX Item "filter_read"
20021 Described in perlfilter.
20022 .RS 4
20023 .Sp
20024 .Vb 2
20025 \& I32 filter_read( int idx, SV *buf_sv, int maxlen)
20026 \& I32 Perl_filter_read(pTHX_ int idx, SV *buf_sv, int maxlen)
20027 .Ve
20028 .RE
20029 .RS 4
20030 .RE
20031 .ie n .IP """scan_vstring""" 4
20032 .el .IP \f(CWscan_vstring\fR 4
20033 .IX Xref "scan_vstring"
20034 .IX Item "scan_vstring"
20035 Returns a pointer to the next character after the parsed
20036 vstring, as well as updating the passed in sv.
20037 .Sp
20038 Function must be called like
20039 .Sp
20040 .Vb 2
20041 \& sv = sv_2mortal(newSV(5));
20042 \& s = scan_vstring(s,e,sv);
20043 .Ve
20044 .Sp
20045 where s and e are the start and end of the string.
20046 The sv should already be large enough to store the vstring
20047 passed in, for performance reasons.
20048 .Sp
20049 This function may croak if fatal warnings are enabled in the
20050 calling scope, hence the sv_2mortal in the example (to prevent
20051 a leak). Make sure to do SvREFCNT_inc afterwards if you use
20052 sv_2mortal.
20053 .RS 4
20054 .Sp
20055 .Vb 4
20056 \& char * scan_vstring( const char *s,
20057 \& const char * const e, SV *sv)
20058 \& char * Perl_scan_vstring(pTHX_ const char *s,
20059 \& const char * const e, SV *sv)
20060 .Ve
20061 .RE
20062 .RS 4
20063 .RE
20064 .ie n .IP """start_subparse""" 4
20065 .el .IP \f(CWstart_subparse\fR 4
20066 .IX Xref "start_subparse"
20067 .IX Item "start_subparse"
20068 Set things up for parsing a subroutine.
20069 .Sp
20070 If \f(CW\*(C`is_format\*(C'\fR is non\-zero, the input is to be considered a format sub
20071 (a specialised sub used to implement perl\*(Aqs \f(CW\*(C`format\*(C'\fR feature); else a
20072 normal \f(CW\*(C`sub\*(C'\fR.
20073 .Sp
20074 \&\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
20075 \&\f(CW\*(C`CVf_IsMETHOD\*(C'\fR bit, which causes the new subroutine to be a method.
20076 .Sp
20077 This returns the value of \f(CW\*(C`PL_savestack_ix\*(C'\fR that was in effect upon entry to
20078 the function;
20079 .RS 4
20080 .Sp
20081 .Vb 2
20082 \& I32 start_subparse( I32 is_format, U32 flags)
20083 \& I32 Perl_start_subparse(pTHX_ I32 is_format, U32 flags)
20084 .Ve
20085 .RE
20086 .RS 4
20087 .RE
20088 .SH "Stack Manipulation Macros"
20089 .IX Header "Stack Manipulation Macros"
20090 .ie n .IP """dMARK""" 4
20091 .el .IP \f(CWdMARK\fR 4
20092 .IX Xref "dMARK"
20093 .IX Item "dMARK"
20094 Declare a stack marker variable, \f(CW\*(C`mark\*(C'\fR, for the XSUB. See \f(CW"MARK"\fR and
20095 \&\f(CW"dORIGMARK"\fR.
20096 .RS 4
20097 .Sp
20098 .Vb 1
20099 \& dMARK;
20100 .Ve
20101 .RE
20102 .RS 4
20103 .RE
20104 .ie n .IP """dORIGMARK""" 4
20105 .el .IP \f(CWdORIGMARK\fR 4
20106 .IX Xref "dORIGMARK"
20107 .IX Item "dORIGMARK"
20108 Saves the original stack mark for the XSUB. See \f(CW"ORIGMARK"\fR.
20109 .RS 4
20110 .Sp
20111 .Vb 1
20112 \& dORIGMARK;
20113 .Ve
20114 .RE
20115 .RS 4
20116 .RE
20117 .ie n .IP """dSP""" 4
20118 .el .IP \f(CWdSP\fR 4
20119 .IX Xref "dSP"
20120 .IX Item "dSP"
20121 Declares a local copy of perl\*(Aqs stack pointer for the XSUB, available via
20122 the \f(CW\*(C`SP\*(C'\fR macro. See \f(CW"SP"\fR.
20123 .RS 4
20124 .Sp
20125 .Vb 1
20126 \& dSP;
20127 .Ve
20128 .RE
20129 .RS 4
20130 .RE
20131 .ie n .IP """dTARGET""" 4
20132 .el .IP \f(CWdTARGET\fR 4
20133 .IX Xref "dTARGET"
20134 .IX Item "dTARGET"
20135 Declare that this function uses \f(CW\*(C`TARG\*(C'\fR, and initializes it
20136 .RS 4
20137 .Sp
20138 .Vb 1
20139 \& dTARGET;
20140 .Ve
20141 .RE
20142 .RS 4
20143 .RE
20144 .ie n .IP """EXTEND""" 4
20145 .el .IP \f(CWEXTEND\fR 4
20146 .IX Xref "EXTEND"
20147 .IX Item "EXTEND"
20148 Used to extend the argument stack for an XSUB\*(Aqs return values. Once
20149 used, guarantees that there is room for at least \f(CW\*(C`nitems\*(C'\fR to be pushed
20150 onto the stack.
20151 .RS 4
20152 .Sp
20153 .Vb 1
20154 \& void EXTEND(SP, SSize_t nitems)
20155 .Ve
20156 .RE
20157 .RS 4
20158 .RE
20159 .ie n .IP """MARK""" 4
20160 .el .IP \f(CWMARK\fR 4
20161 .IX Xref "MARK"
20162 .IX Item "MARK"
20163 Stack marker variable for the XSUB. See \f(CW"dMARK"\fR.
20164 .ie n .IP """mPUSHi""" 4
20165 .el .IP \f(CWmPUSHi\fR 4
20166 .IX Xref "mPUSHi"
20167 .IX Item "mPUSHi"
20168 Push an integer onto the stack. The stack must have room for this element.
20169 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHi"\fR, \f(CW"mXPUSHi"\fR and \f(CW"XPUSHi"\fR.
20170 .RS 4
20171 .Sp
20172 .Vb 1
20173 \& void mPUSHi(IV iv)
20174 .Ve
20175 .RE
20176 .RS 4
20177 .RE
20178 .ie n .IP """mPUSHn""" 4
20179 .el .IP \f(CWmPUSHn\fR 4
20180 .IX Xref "mPUSHn"
20181 .IX Item "mPUSHn"
20182 Push a double onto the stack. The stack must have room for this element.
20183 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHn"\fR, \f(CW"mXPUSHn"\fR and \f(CW"XPUSHn"\fR.
20184 .RS 4
20185 .Sp
20186 .Vb 1
20187 \& void mPUSHn(NV nv)
20188 .Ve
20189 .RE
20190 .RS 4
20191 .RE
20192 .ie n .IP """mPUSHp""" 4
20193 .el .IP \f(CWmPUSHp\fR 4
20194 .IX Xref "mPUSHp"
20195 .IX Item "mPUSHp"
20196 Push a string onto the stack. The stack must have room for this element.
20197 The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Does not use \f(CW\*(C`TARG\*(C'\fR.
20198 See also \f(CW"PUSHp"\fR, \f(CW"mXPUSHp"\fR and \f(CW"XPUSHp"\fR.
20199 .RS 4
20200 .Sp
20201 .Vb 1
20202 \& void mPUSHp(char* str, STRLEN len)
20203 .Ve
20204 .RE
20205 .RS 4
20206 .RE
20207 .ie n .IP """mPUSHpvs""" 4
20208 .el .IP \f(CWmPUSHpvs\fR 4
20209 .IX Xref "mPUSHpvs"
20210 .IX Item "mPUSHpvs"
20211 A variation on \f(CW\*(C`mPUSHp\*(C'\fR that takes a literal string and calculates its size
20212 directly.
20213 .RS 4
20214 .Sp
20215 .Vb 1
20216 \& void mPUSHpvs("literal string")
20217 .Ve
20218 .RE
20219 .RS 4
20220 .RE
20221 .ie n .IP """mPUSHs""" 4
20222 .el .IP \f(CWmPUSHs\fR 4
20223 .IX Xref "mPUSHs"
20224 .IX Item "mPUSHs"
20225 Push an SV onto the stack and mortalizes the SV. The stack must have room
20226 for this element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHs"\fR and
20227 \&\f(CW"mXPUSHs"\fR.
20228 .RS 4
20229 .Sp
20230 .Vb 1
20231 \& void mPUSHs(SV* sv)
20232 .Ve
20233 .RE
20234 .RS 4
20235 .RE
20236 .ie n .IP """mPUSHu""" 4
20237 .el .IP \f(CWmPUSHu\fR 4
20238 .IX Xref "mPUSHu"
20239 .IX Item "mPUSHu"
20240 Push an unsigned integer onto the stack. The stack must have room for this
20241 element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHu"\fR, \f(CW"mXPUSHu"\fR and
20242 \&\f(CW"XPUSHu"\fR.
20243 .RS 4
20244 .Sp
20245 .Vb 1
20246 \& void mPUSHu(UV uv)
20247 .Ve
20248 .RE
20249 .RS 4
20250 .RE
20251 .ie n .IP """mXPUSHi""" 4
20252 .el .IP \f(CWmXPUSHi\fR 4
20253 .IX Xref "mXPUSHi"
20254 .IX Item "mXPUSHi"
20255 Push an integer onto the stack, extending the stack if necessary.
20256 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHi"\fR, \f(CW"mPUSHi"\fR and \f(CW"PUSHi"\fR.
20257 .RS 4
20258 .Sp
20259 .Vb 1
20260 \& void mXPUSHi(IV iv)
20261 .Ve
20262 .RE
20263 .RS 4
20264 .RE
20265 .ie n .IP """mXPUSHn""" 4
20266 .el .IP \f(CWmXPUSHn\fR 4
20267 .IX Xref "mXPUSHn"
20268 .IX Item "mXPUSHn"
20269 Push a double onto the stack, extending the stack if necessary.
20270 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHn"\fR, \f(CW"mPUSHn"\fR and \f(CW"PUSHn"\fR.
20271 .RS 4
20272 .Sp
20273 .Vb 1
20274 \& void mXPUSHn(NV nv)
20275 .Ve
20276 .RE
20277 .RS 4
20278 .RE
20279 .ie n .IP """mXPUSHp""" 4
20280 .el .IP \f(CWmXPUSHp\fR 4
20281 .IX Xref "mXPUSHp"
20282 .IX Item "mXPUSHp"
20283 Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR
20284 indicates the length of the string. Does not use \f(CW\*(C`TARG\*(C'\fR. See also
20285 \&\f(CW"XPUSHp"\fR, \f(CW\*(C`mPUSHp\*(C'\fR and \f(CW\*(C`PUSHp\*(C'\fR.
20286 .RS 4
20287 .Sp
20288 .Vb 1
20289 \& void mXPUSHp(char* str, STRLEN len)
20290 .Ve
20291 .RE
20292 .RS 4
20293 .RE
20294 .ie n .IP """mXPUSHpvs""" 4
20295 .el .IP \f(CWmXPUSHpvs\fR 4
20296 .IX Xref "mXPUSHpvs"
20297 .IX Item "mXPUSHpvs"
20298 A variation on \f(CW\*(C`mXPUSHp\*(C'\fR that takes a literal string and calculates its size
20299 directly.
20300 .RS 4
20301 .Sp
20302 .Vb 1
20303 \& void mXPUSHpvs("literal string")
20304 .Ve
20305 .RE
20306 .RS 4
20307 .RE
20308 .ie n .IP """mXPUSHs""" 4
20309 .el .IP \f(CWmXPUSHs\fR 4
20310 .IX Xref "mXPUSHs"
20311 .IX Item "mXPUSHs"
20312 Push an SV onto the stack, extending the stack if necessary and mortalizes
20313 the SV. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHs"\fR and \f(CW"mPUSHs"\fR.
20314 .RS 4
20315 .Sp
20316 .Vb 1
20317 \& void mXPUSHs(SV* sv)
20318 .Ve
20319 .RE
20320 .RS 4
20321 .RE
20322 .ie n .IP """mXPUSHu""" 4
20323 .el .IP \f(CWmXPUSHu\fR 4
20324 .IX Xref "mXPUSHu"
20325 .IX Item "mXPUSHu"
20326 Push an unsigned integer onto the stack, extending the stack if necessary.
20327 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHu"\fR, \f(CW"mPUSHu"\fR and \f(CW"PUSHu"\fR.
20328 .RS 4
20329 .Sp
20330 .Vb 1
20331 \& void mXPUSHu(UV uv)
20332 .Ve
20333 .RE
20334 .RS 4
20335 .RE
20336 .ie n .IP """newXSproto""" 4
20337 .el .IP \f(CWnewXSproto\fR 4
20338 .IX Xref "newXSproto"
20339 .IX Item "newXSproto"
20340 Used by \f(CW\*(C`xsubpp\*(C'\fR to hook up XSUBs as Perl subs. Adds Perl prototypes to
20341 the subs.
20342 .ie n .IP """ORIGMARK""" 4
20343 .el .IP \f(CWORIGMARK\fR 4
20344 .IX Xref "ORIGMARK"
20345 .IX Item "ORIGMARK"
20346 The original stack mark for the XSUB. See \f(CW"dORIGMARK"\fR.
20347 .ie n .IP """PL_markstack""" 4
20348 .el .IP \f(CWPL_markstack\fR 4
20349 .IX Item "PL_markstack"
20350 .PD 0
20351 .ie n .IP """PL_markstack_ptr""" 4
20352 .el .IP \f(CWPL_markstack_ptr\fR 4
20353 .IX Item "PL_markstack_ptr"
20354 .ie n .IP """PL_savestack""" 4
20355 .el .IP \f(CWPL_savestack\fR 4
20356 .IX Item "PL_savestack"
20357 .ie n .IP """PL_savestack_ix""" 4
20358 .el .IP \f(CWPL_savestack_ix\fR 4
20359 .IX Item "PL_savestack_ix"
20360 .ie n .IP """PL_scopestack""" 4
20361 .el .IP \f(CWPL_scopestack\fR 4
20362 .IX Item "PL_scopestack"
20363 .ie n .IP """PL_scopestack_ix""" 4
20364 .el .IP \f(CWPL_scopestack_ix\fR 4
20365 .IX Item "PL_scopestack_ix"
20366 .ie n .IP """PL_scopestack_name""" 4
20367 .el .IP \f(CWPL_scopestack_name\fR 4
20368 .IX Item "PL_scopestack_name"
20369 .ie n .IP """PL_stack_base""" 4
20370 .el .IP \f(CWPL_stack_base\fR 4
20371 .IX Item "PL_stack_base"
20372 .ie n .IP """PL_stack_sp""" 4
20373 .el .IP \f(CWPL_stack_sp\fR 4
20374 .IX Item "PL_stack_sp"
20375 .ie n .IP """PL_tmps_floor""" 4
20376 .el .IP \f(CWPL_tmps_floor\fR 4
20377 .IX Item "PL_tmps_floor"
20378 .ie n .IP """PL_tmps_ix""" 4
20379 .el .IP \f(CWPL_tmps_ix\fR 4
20380 .IX Item "PL_tmps_ix"
20381 .ie n .IP """PL_tmps_stack""" 4
20382 .el .IP \f(CWPL_tmps_stack\fR 4
20383 .IX Item "PL_tmps_stack"
20384 .PD
20385 Described in perlguts.
20386 .ie n .IP """POPi""" 4
20387 .el .IP \f(CWPOPi\fR 4
20388 .IX Xref "POPi"
20389 .IX Item "POPi"
20390 Pops an integer off the stack.
20391 .RS 4
20392 .Sp
20393 .Vb 1
20394 \& IV POPi
20395 .Ve
20396 .RE
20397 .RS 4
20398 .RE
20399 .ie n .IP """POPl""" 4
20400 .el .IP \f(CWPOPl\fR 4
20401 .IX Xref "POPl"
20402 .IX Item "POPl"
20403 Pops a long off the stack.
20404 .RS 4
20405 .Sp
20406 .Vb 1
20407 \& long POPl
20408 .Ve
20409 .RE
20410 .RS 4
20411 .RE
20412 .ie n .IP """POPn""" 4
20413 .el .IP \f(CWPOPn\fR 4
20414 .IX Xref "POPn"
20415 .IX Item "POPn"
20416 Pops a double off the stack.
20417 .RS 4
20418 .Sp
20419 .Vb 1
20420 \& NV POPn
20421 .Ve
20422 .RE
20423 .RS 4
20424 .RE
20425 .ie n .IP """POPp""" 4
20426 .el .IP \f(CWPOPp\fR 4
20427 .IX Item "POPp"
20428 .PD 0
20429 .ie n .IP """POPpx""" 4
20430 .el .IP \f(CWPOPpx\fR 4
20431 .IX Xref "POPp POPpx"
20432 .IX Item "POPpx"
20433 .PD
20434 These each pop a string off the stack.
20435 There are two names for historical reasons.
20436 .RS 4
20437 .Sp
20438 .Vb 2
20439 \& char* POPp
20440 \& char* POPpx
20441 .Ve
20442 .RE
20443 .RS 4
20444 .RE
20445 .ie n .IP """POPpbytex""" 4
20446 .el .IP \f(CWPOPpbytex\fR 4
20447 .IX Xref "POPpbytex"
20448 .IX Item "POPpbytex"
20449 Pops a string off the stack which must consist of bytes i.e. characters < 256.
20450 .RS 4
20451 .Sp
20452 .Vb 1
20453 \& char* POPpbytex
20454 .Ve
20455 .RE
20456 .RS 4
20457 .RE
20458 .ie n .IP """POPpx*""" 4
20459 .el .IP \f(CWPOPpx*\fR 4
20460 .IX Item "POPpx*"
20461 Described under \f(CW"POPp"\fR
20462 .ie n .IP """POPs""" 4
20463 .el .IP \f(CWPOPs\fR 4
20464 .IX Xref "POPs"
20465 .IX Item "POPs"
20466 Pops an SV off the stack.
20467 .RS 4
20468 .Sp
20469 .Vb 1
20470 \& SV* POPs
20471 .Ve
20472 .RE
20473 .RS 4
20474 .RE
20475 .ie n .IP """POPu""" 4
20476 .el .IP \f(CWPOPu\fR 4
20477 .IX Xref "POPu"
20478 .IX Item "POPu"
20479 Pops an unsigned integer off the stack.
20480 .RS 4
20481 .Sp
20482 .Vb 1
20483 \& UV POPu
20484 .Ve
20485 .RE
20486 .RS 4
20487 .RE
20488 .ie n .IP """POPul""" 4
20489 .el .IP \f(CWPOPul\fR 4
20490 .IX Xref "POPul"
20491 .IX Item "POPul"
20492 Pops an unsigned long off the stack.
20493 .RS 4
20494 .Sp
20495 .Vb 1
20496 \& long POPul
20497 .Ve
20498 .RE
20499 .RS 4
20500 .RE
20501 .ie n .IP """PUSHi""" 4
20502 .el .IP \f(CWPUSHi\fR 4
20503 .IX Xref "PUSHi"
20504 .IX Item "PUSHi"
20505 Push an integer onto the stack. The stack must have room for this element.
20506 Handles \*(Aqset\*(Aq magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
20507 called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
20508 return lists from XSUB\*(Aqs \- see \f(CW"mPUSHi"\fR instead. See also \f(CW"XPUSHi"\fR
20509 and \f(CW"mXPUSHi"\fR.
20510 .RS 4
20511 .Sp
20512 .Vb 1
20513 \& void PUSHi(IV iv)
20514 .Ve
20515 .RE
20516 .RS 4
20517 .RE
20518 .ie n .IP """PUSHMARK""" 4
20519 .el .IP \f(CWPUSHMARK\fR 4
20520 .IX Xref "PUSHMARK"
20521 .IX Item "PUSHMARK"
20522 Opening bracket for arguments on a callback. See \f(CW"PUTBACK"\fR and
20523 perlcall.
20524 .RS 4
20525 .Sp
20526 .Vb 1
20527 \& void PUSHMARK(SP)
20528 .Ve
20529 .RE
20530 .RS 4
20531 .RE
20532 .ie n .IP """PUSHmortal""" 4
20533 .el .IP \f(CWPUSHmortal\fR 4
20534 .IX Xref "PUSHmortal"
20535 .IX Item "PUSHmortal"
20536 Push a new mortal SV onto the stack. The stack must have room for this
20537 element. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"PUSHs"\fR, \f(CW"XPUSHmortal"\fR and
20538 \&\f(CW"XPUSHs"\fR.
20539 .RS 4
20540 .Sp
20541 .Vb 1
20542 \& void PUSHmortal
20543 .Ve
20544 .RE
20545 .RS 4
20546 .RE
20547 .ie n .IP """PUSHn""" 4
20548 .el .IP \f(CWPUSHn\fR 4
20549 .IX Xref "PUSHn"
20550 .IX Item "PUSHn"
20551 Push a double onto the stack. The stack must have room for this element.
20552 Handles \*(Aqset\*(Aq magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
20553 called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
20554 return lists from XSUB\*(Aqs \- see \f(CW"mPUSHn"\fR instead. See also \f(CW"XPUSHn"\fR
20555 and \f(CW"mXPUSHn"\fR.
20556 .RS 4
20557 .Sp
20558 .Vb 1
20559 \& void PUSHn(NV nv)
20560 .Ve
20561 .RE
20562 .RS 4
20563 .RE
20564 .ie n .IP """PUSHp""" 4
20565 .el .IP \f(CWPUSHp\fR 4
20566 .IX Xref "PUSHp"
20567 .IX Item "PUSHp"
20568 Push a string onto the stack. The stack must have room for this element.
20569 The \f(CW\*(C`len\*(C'\fR indicates the length of the string. Handles \*(Aqset\*(Aq magic. Uses
20570 \&\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
20571 call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB\*(Aqs \- see
20572 \&\f(CW"mPUSHp"\fR instead. See also \f(CW"XPUSHp"\fR and \f(CW"mXPUSHp"\fR.
20573 .RS 4
20574 .Sp
20575 .Vb 1
20576 \& void PUSHp(char* str, STRLEN len)
20577 .Ve
20578 .RE
20579 .RS 4
20580 .RE
20581 .ie n .IP """PUSHpvs""" 4
20582 .el .IP \f(CWPUSHpvs\fR 4
20583 .IX Xref "PUSHpvs"
20584 .IX Item "PUSHpvs"
20585 A variation on \f(CW\*(C`PUSHp\*(C'\fR that takes a literal string and calculates its size
20586 directly.
20587 .RS 4
20588 .Sp
20589 .Vb 1
20590 \& void PUSHpvs("literal string")
20591 .Ve
20592 .RE
20593 .RS 4
20594 .RE
20595 .ie n .IP """PUSHs""" 4
20596 .el .IP \f(CWPUSHs\fR 4
20597 .IX Xref "PUSHs"
20598 .IX Item "PUSHs"
20599 Push an SV onto the stack. The stack must have room for this element.
20600 Does not handle \*(Aqset\*(Aq magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also
20601 \&\f(CW"PUSHmortal"\fR, \f(CW"XPUSHs"\fR, and \f(CW"XPUSHmortal"\fR.
20602 .RS 4
20603 .Sp
20604 .Vb 1
20605 \& void PUSHs(SV* sv)
20606 .Ve
20607 .RE
20608 .RS 4
20609 .RE
20610 .ie n .IP """PUSHu""" 4
20611 .el .IP \f(CWPUSHu\fR 4
20612 .IX Xref "PUSHu"
20613 .IX Item "PUSHu"
20614 Push an unsigned integer onto the stack. The stack must have room for this
20615 element. Handles \*(Aqset\*(Aq magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR
20616 should be called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented
20617 macros to return lists from XSUB\*(Aqs \- see \f(CW"mPUSHu"\fR instead. See also
20618 \&\f(CW"XPUSHu"\fR and \f(CW"mXPUSHu"\fR.
20619 .RS 4
20620 .Sp
20621 .Vb 1
20622 \& void PUSHu(UV uv)
20623 .Ve
20624 .RE
20625 .RS 4
20626 .RE
20627 .ie n .IP """PUTBACK""" 4
20628 .el .IP \f(CWPUTBACK\fR 4
20629 .IX Xref "PUTBACK"
20630 .IX Item "PUTBACK"
20631 Closing bracket for XSUB arguments. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR.
20632 See \f(CW"PUSHMARK"\fR and perlcall for other uses.
20633 .RS 4
20634 .Sp
20635 .Vb 1
20636 \& PUTBACK;
20637 .Ve
20638 .RE
20639 .RS 4
20640 .RE
20641 .ie n .IP """SAVEt_INT""" 4
20642 .el .IP \f(CWSAVEt_INT\fR 4
20643 .IX Item "SAVEt_INT"
20644 Described in perlguts.
20645 .ie n .IP """SP""" 4
20646 .el .IP \f(CWSP\fR 4
20647 .IX Xref "SP"
20648 .IX Item "SP"
20649 Stack pointer. This is usually handled by \f(CW\*(C`xsubpp\*(C'\fR. See \f(CW"dSP"\fR and
20650 \&\f(CW\*(C`SPAGAIN\*(C'\fR.
20651 .ie n .IP """SPAGAIN""" 4
20652 .el .IP \f(CWSPAGAIN\fR 4
20653 .IX Xref "SPAGAIN"
20654 .IX Item "SPAGAIN"
20655 Refetch the stack pointer. Used after a callback. See perlcall.
20656 .RS 4
20657 .Sp
20658 .Vb 1
20659 \& SPAGAIN;
20660 .Ve
20661 .RE
20662 .RS 4
20663 .RE
20664 .ie n .IP """SSNEW""" 4
20665 .el .IP \f(CWSSNEW\fR 4
20666 .IX Item "SSNEW"
20667 .PD 0
20668 .ie n .IP """SSNEWa""" 4
20669 .el .IP \f(CWSSNEWa\fR 4
20670 .IX Item "SSNEWa"
20671 .ie n .IP """SSNEWat""" 4
20672 .el .IP \f(CWSSNEWat\fR 4
20673 .IX Item "SSNEWat"
20674 .ie n .IP """SSNEWt""" 4
20675 .el .IP \f(CWSSNEWt\fR 4
20676 .IX Xref "SSNEW SSNEWa SSNEWat SSNEWt"
20677 .IX Item "SSNEWt"
20678 .PD
20679 These each temporarily allocate data on the savestack, returning an SSize_t
20680 index into the savestack, because a pointer would get broken if the savestack
20681 is moved on reallocation. Use "\f(CW\*(C`SSPTR\*(C'\fR" to convert the returned index into
20682 a pointer.
20683 .Sp
20684 The forms differ in that plain \f(CW\*(C`SSNEW\*(C'\fR allocates \f(CW\*(C`size\*(C'\fR bytes;
20685 \&\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
20686 \&\f(CW\*(C`type\*(C'\fR;
20687 and <SSNEWa> and \f(CW\*(C`SSNEWat\*(C'\fR make sure to align the new data to an \f(CW\*(C`align\*(C'\fR
20688 boundary. The most useful value for the alignment is likely to be
20689 "\f(CW\*(C`MEM_ALIGNBYTES\*(C'\fR". The alignment will be preserved through savestack
20690 reallocation \fBonly\fR if realloc returns data aligned to a size divisible by
20691 "align"!
20692 .RS 4
20693 .Sp
20694 .Vb 4
20695 \& SSize_t SSNEW (Size_t size)
20696 \& SSize_t SSNEWa (Size_t size, Size_t align)
20697 \& SSize_t SSNEWat(Size_t size, type, Size_t align)
20698 \& SSize_t SSNEWt (Size_t size, type)
20699 .Ve
20700 .RE
20701 .RS 4
20702 .RE
20703 .ie n .IP """SSPTR""" 4
20704 .el .IP \f(CWSSPTR\fR 4
20705 .IX Item "SSPTR"
20706 .PD 0
20707 .ie n .IP """SSPTRt""" 4
20708 .el .IP \f(CWSSPTRt\fR 4
20709 .IX Xref "SSPTR SSPTRt"
20710 .IX Item "SSPTRt"
20711 .PD
20712 These convert the \f(CW\*(C`index\*(C'\fR returned by L/<\f(CW\*(C`SSNEW\*(C'\fR> and kin into actual pointers.
20713 .Sp
20714 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
20715 casts it to a pointer of that \f(CW\*(C`type\*(C'\fR.
20716 .RS 4
20717 .Sp
20718 .Vb 2
20719 \& type SSPTR (SSize_t index, type)
20720 \& type * SSPTRt(SSize_t index, type)
20721 .Ve
20722 .RE
20723 .RS 4
20724 .RE
20725 .ie n .IP """TARG""" 4
20726 .el .IP \f(CWTARG\fR 4
20727 .IX Xref "TARG"
20728 .IX Item "TARG"
20729 \&\f(CW\*(C`TARG\*(C'\fR is short for "target". It is an entry in the pad that an OPs
20730 \&\f(CW\*(C`op_targ\*(C'\fR refers to. It is scratchpad space, often used as a return
20731 value for the OP, but some use it for other purposes.
20732 .RS 4
20733 .Sp
20734 .Vb 1
20735 \& TARG;
20736 .Ve
20737 .RE
20738 .RS 4
20739 .RE
20740 .ie n .IP """TOPs""" 4
20741 .el .IP \f(CWTOPs\fR 4
20742 .IX Item "TOPs"
20743 Described in perlguts.
20744 .ie n .IP """XPUSHi""" 4
20745 .el .IP \f(CWXPUSHi\fR 4
20746 .IX Xref "XPUSHi"
20747 .IX Item "XPUSHi"
20748 Push an integer onto the stack, extending the stack if necessary. Handles
20749 \&\*(Aqset\*(Aq 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
20750 declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists
20751 from XSUB\*(Aqs \- see \f(CW"mXPUSHi"\fR instead. See also \f(CW"PUSHi"\fR and
20752 \&\f(CW"mPUSHi"\fR.
20753 .RS 4
20754 .Sp
20755 .Vb 1
20756 \& void XPUSHi(IV iv)
20757 .Ve
20758 .RE
20759 .RS 4
20760 .RE
20761 .ie n .IP """XPUSHmortal""" 4
20762 .el .IP \f(CWXPUSHmortal\fR 4
20763 .IX Xref "XPUSHmortal"
20764 .IX Item "XPUSHmortal"
20765 Push a new mortal SV onto the stack, extending the stack if necessary.
20766 Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHs"\fR, \f(CW"PUSHmortal"\fR and
20767 \&\f(CW"PUSHs"\fR.
20768 .RS 4
20769 .Sp
20770 .Vb 1
20771 \& void XPUSHmortal
20772 .Ve
20773 .RE
20774 .RS 4
20775 .RE
20776 .ie n .IP """XPUSHn""" 4
20777 .el .IP \f(CWXPUSHn\fR 4
20778 .IX Xref "XPUSHn"
20779 .IX Item "XPUSHn"
20780 Push a double onto the stack, extending the stack if necessary. Handles
20781 \&\*(Aqset\*(Aq 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
20782 declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists
20783 from XSUB\*(Aqs \- see \f(CW"mXPUSHn"\fR instead. See also \f(CW"PUSHn"\fR and
20784 \&\f(CW"mPUSHn"\fR.
20785 .RS 4
20786 .Sp
20787 .Vb 1
20788 \& void XPUSHn(NV nv)
20789 .Ve
20790 .RE
20791 .RS 4
20792 .RE
20793 .ie n .IP """XPUSHp""" 4
20794 .el .IP \f(CWXPUSHp\fR 4
20795 .IX Xref "XPUSHp"
20796 .IX Item "XPUSHp"
20797 Push a string onto the stack, extending the stack if necessary. The \f(CW\*(C`len\*(C'\fR
20798 indicates the length of the string. Handles \*(Aqset\*(Aq magic. Uses \f(CW\*(C`TARG\*(C'\fR, so
20799 \&\f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be called to declare it. Do not call
20800 multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to return lists from XSUB\*(Aqs \- see
20801 \&\f(CW"mXPUSHp"\fR instead. See also \f(CW"PUSHp"\fR and \f(CW"mPUSHp"\fR.
20802 .RS 4
20803 .Sp
20804 .Vb 1
20805 \& void XPUSHp(char* str, STRLEN len)
20806 .Ve
20807 .RE
20808 .RS 4
20809 .RE
20810 .ie n .IP """XPUSHpvs""" 4
20811 .el .IP \f(CWXPUSHpvs\fR 4
20812 .IX Xref "XPUSHpvs"
20813 .IX Item "XPUSHpvs"
20814 A variation on \f(CW\*(C`XPUSHp\*(C'\fR that takes a literal string and calculates its size
20815 directly.
20816 .RS 4
20817 .Sp
20818 .Vb 1
20819 \& void XPUSHpvs("literal string")
20820 .Ve
20821 .RE
20822 .RS 4
20823 .RE
20824 .ie n .IP """XPUSHs""" 4
20825 .el .IP \f(CWXPUSHs\fR 4
20826 .IX Xref "XPUSHs"
20827 .IX Item "XPUSHs"
20828 Push an SV onto the stack, extending the stack if necessary. Does not
20829 handle \*(Aqset\*(Aq magic. Does not use \f(CW\*(C`TARG\*(C'\fR. See also \f(CW"XPUSHmortal"\fR,
20830 \&\f(CW\*(C`PUSHs\*(C'\fR and \f(CW\*(C`PUSHmortal\*(C'\fR.
20831 .RS 4
20832 .Sp
20833 .Vb 1
20834 \& void XPUSHs(SV* sv)
20835 .Ve
20836 .RE
20837 .RS 4
20838 .RE
20839 .ie n .IP """XPUSHu""" 4
20840 .el .IP \f(CWXPUSHu\fR 4
20841 .IX Xref "XPUSHu"
20842 .IX Item "XPUSHu"
20843 Push an unsigned integer onto the stack, extending the stack if necessary.
20844 Handles \*(Aqset\*(Aq magic. Uses \f(CW\*(C`TARG\*(C'\fR, so \f(CW\*(C`dTARGET\*(C'\fR or \f(CW\*(C`dXSTARG\*(C'\fR should be
20845 called to declare it. Do not call multiple \f(CW\*(C`TARG\*(C'\fR\-oriented macros to
20846 return lists from XSUB\*(Aqs \- see \f(CW"mXPUSHu"\fR instead. See also \f(CW"PUSHu"\fR and
20847 \&\f(CW"mPUSHu"\fR.
20848 .RS 4
20849 .Sp
20850 .Vb 1
20851 \& void XPUSHu(UV uv)
20852 .Ve
20853 .RE
20854 .RS 4
20855 .RE
20856 .ie n .IP """XS_APIVERSION_BOOTCHECK""" 4
20857 .el .IP \f(CWXS_APIVERSION_BOOTCHECK\fR 4
20858 .IX Xref "XS_APIVERSION_BOOTCHECK"
20859 .IX Item "XS_APIVERSION_BOOTCHECK"
20860 Macro to verify that the perl api version an XS module has been compiled against
20861 matches the api version of the perl interpreter it\*(Aqs being loaded into.
20862 .RS 4
20863 .Sp
20864 .Vb 1
20865 \& XS_APIVERSION_BOOTCHECK;
20866 .Ve
20867 .RE
20868 .RS 4
20869 .RE
20870 .ie n .IP """XS_VERSION""" 4
20871 .el .IP \f(CWXS_VERSION\fR 4
20872 .IX Xref "XS_VERSION"
20873 .IX Item "XS_VERSION"
20874 The version identifier for an XS module. This is usually
20875 handled automatically by \f(CW\*(C`ExtUtils::MakeMaker\*(C'\fR. See
20876 \&\f(CW"XS_VERSION_BOOTCHECK"\fR.
20877 .ie n .IP """XS_VERSION_BOOTCHECK""" 4
20878 .el .IP \f(CWXS_VERSION_BOOTCHECK\fR 4
20879 .IX Xref "XS_VERSION_BOOTCHECK"
20880 .IX Item "XS_VERSION_BOOTCHECK"
20881 Macro to verify that a PM module\*(Aqs \f(CW$VERSION\fR variable matches the XS
20882 module\*(Aqs \f(CW\*(C`XS_VERSION\*(C'\fR variable. This is usually handled automatically by
20883 \&\f(CW\*(C`xsubpp\*(C'\fR. See "The VERSIONCHECK: Keyword" in perlxs.
20884 .RS 4
20885 .Sp
20886 .Vb 1
20887 \& XS_VERSION_BOOTCHECK;
20888 .Ve
20889 .RE
20890 .RS 4
20891 .RE
20892 .ie n .IP """XSRETURN""" 4
20893 .el .IP \f(CWXSRETURN\fR 4
20894 .IX Xref "XSRETURN"
20895 .IX Item "XSRETURN"
20896 Return from XSUB, indicating number of items on the stack. This is usually
20897 handled by \f(CW\*(C`xsubpp\*(C'\fR.
20898 .RS 4
20899 .Sp
20900 .Vb 1
20901 \& void XSRETURN(int nitems)
20902 .Ve
20903 .RE
20904 .RS 4
20905 .RE
20906 .ie n .IP """XSRETURN_EMPTY""" 4
20907 .el .IP \f(CWXSRETURN_EMPTY\fR 4
20908 .IX Xref "XSRETURN_EMPTY"
20909 .IX Item "XSRETURN_EMPTY"
20910 Return an empty list from an XSUB immediately.
20911 .RS 4
20912 .Sp
20913 .Vb 1
20914 \& XSRETURN_EMPTY;
20915 .Ve
20916 .RE
20917 .RS 4
20918 .RE
20919 .ie n .IP """XSRETURN_IV""" 4
20920 .el .IP \f(CWXSRETURN_IV\fR 4
20921 .IX Xref "XSRETURN_IV"
20922 .IX Item "XSRETURN_IV"
20923 Return an integer from an XSUB immediately. Uses \f(CW\*(C`XST_mIV\*(C'\fR.
20924 .RS 4
20925 .Sp
20926 .Vb 1
20927 \& void XSRETURN_IV(IV iv)
20928 .Ve
20929 .RE
20930 .RS 4
20931 .RE
20932 .ie n .IP """XSRETURN_NO""" 4
20933 .el .IP \f(CWXSRETURN_NO\fR 4
20934 .IX Xref "XSRETURN_NO"
20935 .IX Item "XSRETURN_NO"
20936 Return \f(CW&PL_sv_no\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mNO\*(C'\fR.
20937 .RS 4
20938 .Sp
20939 .Vb 1
20940 \& XSRETURN_NO;
20941 .Ve
20942 .RE
20943 .RS 4
20944 .RE
20945 .ie n .IP """XSRETURN_NV""" 4
20946 .el .IP \f(CWXSRETURN_NV\fR 4
20947 .IX Xref "XSRETURN_NV"
20948 .IX Item "XSRETURN_NV"
20949 Return a double from an XSUB immediately. Uses \f(CW\*(C`XST_mNV\*(C'\fR.
20950 .RS 4
20951 .Sp
20952 .Vb 1
20953 \& void XSRETURN_NV(NV nv)
20954 .Ve
20955 .RE
20956 .RS 4
20957 .RE
20958 .ie n .IP """XSRETURN_PV""" 4
20959 .el .IP \f(CWXSRETURN_PV\fR 4
20960 .IX Xref "XSRETURN_PV"
20961 .IX Item "XSRETURN_PV"
20962 Return a copy of a string from an XSUB immediately. Uses \f(CW\*(C`XST_mPV\*(C'\fR.
20963 .RS 4
20964 .Sp
20965 .Vb 1
20966 \& void XSRETURN_PV(char* str)
20967 .Ve
20968 .RE
20969 .RS 4
20970 .RE
20971 .ie n .IP """XSRETURN_UNDEF""" 4
20972 .el .IP \f(CWXSRETURN_UNDEF\fR 4
20973 .IX Xref "XSRETURN_UNDEF"
20974 .IX Item "XSRETURN_UNDEF"
20975 Return \f(CW&PL_sv_undef\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mUNDEF\*(C'\fR.
20976 .RS 4
20977 .Sp
20978 .Vb 1
20979 \& XSRETURN_UNDEF;
20980 .Ve
20981 .RE
20982 .RS 4
20983 .RE
20984 .ie n .IP """XSRETURN_UV""" 4
20985 .el .IP \f(CWXSRETURN_UV\fR 4
20986 .IX Xref "XSRETURN_UV"
20987 .IX Item "XSRETURN_UV"
20988 Return an integer from an XSUB immediately. Uses \f(CW\*(C`XST_mUV\*(C'\fR.
20989 .RS 4
20990 .Sp
20991 .Vb 1
20992 \& void XSRETURN_UV(IV uv)
20993 .Ve
20994 .RE
20995 .RS 4
20996 .RE
20997 .ie n .IP """XSRETURN_YES""" 4
20998 .el .IP \f(CWXSRETURN_YES\fR 4
20999 .IX Xref "XSRETURN_YES"
21000 .IX Item "XSRETURN_YES"
21001 Return \f(CW&PL_sv_yes\fR from an XSUB immediately. Uses \f(CW\*(C`XST_mYES\*(C'\fR.
21002 .RS 4
21003 .Sp
21004 .Vb 1
21005 \& XSRETURN_YES;
21006 .Ve
21007 .RE
21008 .RS 4
21009 .RE
21010 .ie n .IP """XST_mIV""" 4
21011 .el .IP \f(CWXST_mIV\fR 4
21012 .IX Xref "XST_mIV"
21013 .IX Item "XST_mIV"
21014 Place an integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The
21015 value is stored in a new mortal SV.
21016 .RS 4
21017 .Sp
21018 .Vb 1
21019 \& void XST_mIV(int pos, IV iv)
21020 .Ve
21021 .RE
21022 .RS 4
21023 .RE
21024 .ie n .IP """XST_mNO""" 4
21025 .el .IP \f(CWXST_mNO\fR 4
21026 .IX Xref "XST_mNO"
21027 .IX Item "XST_mNO"
21028 Place \f(CW&PL_sv_no\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
21029 stack.
21030 .RS 4
21031 .Sp
21032 .Vb 1
21033 \& void XST_mNO(int pos)
21034 .Ve
21035 .RE
21036 .RS 4
21037 .RE
21038 .ie n .IP """XST_mNV""" 4
21039 .el .IP \f(CWXST_mNV\fR 4
21040 .IX Xref "XST_mNV"
21041 .IX Item "XST_mNV"
21042 Place a double into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The value
21043 is stored in a new mortal SV.
21044 .RS 4
21045 .Sp
21046 .Vb 1
21047 \& void XST_mNV(int pos, NV nv)
21048 .Ve
21049 .RE
21050 .RS 4
21051 .RE
21052 .ie n .IP """XST_mPV""" 4
21053 .el .IP \f(CWXST_mPV\fR 4
21054 .IX Xref "XST_mPV"
21055 .IX Item "XST_mPV"
21056 Place a copy of a string into the specified position \f(CW\*(C`pos\*(C'\fR on the stack.
21057 The value is stored in a new mortal SV.
21058 .RS 4
21059 .Sp
21060 .Vb 1
21061 \& void XST_mPV(int pos, char* str)
21062 .Ve
21063 .RE
21064 .RS 4
21065 .RE
21066 .ie n .IP """XST_mUNDEF""" 4
21067 .el .IP \f(CWXST_mUNDEF\fR 4
21068 .IX Xref "XST_mUNDEF"
21069 .IX Item "XST_mUNDEF"
21070 Place \f(CW&PL_sv_undef\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
21071 stack.
21072 .RS 4
21073 .Sp
21074 .Vb 1
21075 \& void XST_mUNDEF(int pos)
21076 .Ve
21077 .RE
21078 .RS 4
21079 .RE
21080 .ie n .IP """XST_mUV""" 4
21081 .el .IP \f(CWXST_mUV\fR 4
21082 .IX Xref "XST_mUV"
21083 .IX Item "XST_mUV"
21084 Place an unsigned integer into the specified position \f(CW\*(C`pos\*(C'\fR on the stack. The
21085 value is stored in a new mortal SV.
21086 .RS 4
21087 .Sp
21088 .Vb 1
21089 \& void XST_mUV(int pos, UV uv)
21090 .Ve
21091 .RE
21092 .RS 4
21093 .RE
21094 .ie n .IP """XST_mYES""" 4
21095 .el .IP \f(CWXST_mYES\fR 4
21096 .IX Xref "XST_mYES"
21097 .IX Item "XST_mYES"
21098 Place \f(CW&PL_sv_yes\fR into the specified position \f(CW\*(C`pos\*(C'\fR on the
21099 stack.
21100 .RS 4
21101 .Sp
21102 .Vb 1
21103 \& void XST_mYES(int pos)
21104 .Ve
21105 .RE
21106 .RS 4
21107 .RE
21108 .SH "String Handling"
21109 .IX Header "String Handling"
21110 See also \f(CW"Unicode Support"\fR.
21111 .ie n .IP """Copy""" 4
21112 .el .IP \f(CWCopy\fR 4
21113 .IX Item "Copy"
21114 .PD 0
21115 .ie n .IP """CopyD""" 4
21116 .el .IP \f(CWCopyD\fR 4
21117 .IX Xref "Copy CopyD"
21118 .IX Item "CopyD"
21119 .PD
21120 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`memcpy\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the
21121 source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and
21122 \&\f(CW\*(C`type\*(C'\fR is the type. May fail on overlapping copies. See also \f(CW"Move"\fR.
21123 .Sp
21124 \&\f(CW\*(C`CopyD\*(C'\fR is like \f(CW\*(C`Copy\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful
21125 for encouraging compilers to tail\-call
21126 optimise.
21127 .RS 4
21128 .Sp
21129 .Vb 2
21130 \& void Copy (void* src, void* dest, int nitems, type)
21131 \& void * CopyD(void* src, void* dest, int nitems, type)
21132 .Ve
21133 .RE
21134 .RS 4
21135 .RE
21136 .ie n .IP """delimcpy""" 4
21137 .el .IP \f(CWdelimcpy\fR 4
21138 .IX Xref "delimcpy"
21139 .IX Item "delimcpy"
21140 Copy a source buffer to a destination buffer, stopping at (but not including)
21141 the first occurrence in the source of an unescaped (defined below) delimiter
21142 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.
21143 .Sp
21144 The number of bytes copied is written to \f(CW*retlen\fR.
21145 .Sp
21146 Returns the position of the first uncopied \f(CW\*(C`delim\*(C'\fR in the \f(CW\*(C`from\*(C'\fR buffer, but
21147 if there is no such occurrence before \f(CW\*(C`from_end\*(C'\fR, then \f(CW\*(C`from_end\*(C'\fR is returned,
21148 and the entire buffer \f(CW\*(C`from\*(C'\fR\ ..\ \f(CW\*(C`from_end\*(C'\fR\ \-\ 1 is copied.
21149 .Sp
21150 If there is room in the destination available after the copy, an extra
21151 terminating safety \f(CW\*(C`NUL\*(C'\fR byte is appended (not included in the returned
21152 length).
21153 .Sp
21154 The error case is if the destination buffer is not large enough to accommodate
21155 everything that should be copied. In this situation, a value larger than
21156 \&\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
21157 fits will be written to the destination. Not having room for the safety \f(CW\*(C`NUL\*(C'\fR
21158 is not considered an error.
21159 .Sp
21160 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
21161 byte (\fBNOT\fR the digit \f(CW0\fR). Then we would have
21162 .Sp
21163 .Vb 2
21164 \& Source Destination
21165 \& abcxdef abc0
21166 .Ve
21167 .Sp
21168 provided the destination buffer is at least 4 bytes long.
21169 .Sp
21170 An escaped delimiter is one which is immediately preceded by a single
21171 backslash. Escaped delimiters are copied, and the copy continues past the
21172 delimiter; the backslash is not copied:
21173 .Sp
21174 .Vb 2
21175 \& Source Destination
21176 \& abc\exdef abcxdef0
21177 .Ve
21178 .Sp
21179 (provided the destination buffer is at least 8 bytes long).
21180 .Sp
21181 It\*(Aqs actually somewhat more complicated than that. A sequence of any odd number
21182 of backslashes escapes the following delimiter, and the copy continues with
21183 exactly one of the backslashes stripped.
21184 .Sp
21185 .Vb 4
21186 \& Source Destination
21187 \& abc\exdef abcxdef0
21188 \& abc\e\e\exdef abc\e\exdef0
21189 \& abc\e\e\e\e\exdef abc\e\e\e\exdef0
21190 .Ve
21191 .Sp
21192 (as always, if the destination is large enough)
21193 .Sp
21194 An even number of preceding backslashes does not escape the delimiter, so that
21195 the copy stops just before it, and includes all the backslashes (no stripping;
21196 zero is considered even):
21197 .Sp
21198 .Vb 4
21199 \& Source Destination
21200 \& abcxdef abc0
21201 \& abc\e\exdef abc\e\e0
21202 \& abc\e\e\e\exdef abc\e\e\e\e0
21203 .Ve
21204 .RS 4
21205 .Sp
21206 .Vb 6
21207 \& char * delimcpy(char *to, const char *to_end,
21208 \& const char *from, const char *from_end,
21209 \& const int delim, I32 *retlen)
21210 \& char * Perl_delimcpy(char *to, const char *to_end,
21211 \& const char *from, const char *from_end,
21212 \& const int delim, I32 *retlen)
21213 .Ve
21214 .RE
21215 .RS 4
21216 .RE
21217 .ie n .IP """do_join""" 4
21218 .el .IP \f(CWdo_join\fR 4
21219 .IX Xref "do_join"
21220 .IX Item "do_join"
21221 This performs a Perl \f(CW\*(C`join\*(C'\fR, placing the joined output
21222 into \f(CW\*(C`sv\*(C'\fR.
21223 .Sp
21224 The elements to join are in SVs, stored in a C array of pointers to SVs, from
21225 \&\f(CW**mark\fR to \f(CW\*(C`**sp\ \-\ 1\*(C'\fR. Hence \f(CW*mark\fR is a reference to the first SV.
21226 Each SV will be coerced into a PV if not one already.
21227 .Sp
21228 \&\f(CW\*(C`delim\*(C'\fR contains the string (or coerced into a string) that is to separate
21229 each of the joined elements.
21230 .Sp
21231 If any component is in UTF\-8, the result will be as well, and all non\-UTF\-8
21232 components will be converted to UTF\-8 as necessary.
21233 .Sp
21234 Magic and tainting are handled.
21235 .RS 4
21236 .Sp
21237 .Vb 2
21238 \& void do_join( SV *sv, SV *delim, SV **mark, SV **sp)
21239 \& void Perl_do_join(pTHX_ SV *sv, SV *delim, SV **mark, SV **sp)
21240 .Ve
21241 .RE
21242 .RS 4
21243 .RE
21244 .ie n .IP """do_sprintf""" 4
21245 .el .IP \f(CWdo_sprintf\fR 4
21246 .IX Xref "do_sprintf"
21247 .IX Item "do_sprintf"
21248 This performs a Perl \f(CW\*(C`sprintf\*(C'\fR placing the string output
21249 into \f(CW\*(C`sv\*(C'\fR.
21250 .Sp
21251 The elements to format are in SVs, stored in a C array of pointers to SVs of
21252 length \f(CW\*(C`len\*(C'\fR> and beginning at \f(CW**sarg\fR. The element referenced by \f(CW*sarg\fR
21253 is the format.
21254 .Sp
21255 Magic and tainting are handled.
21256 .RS 4
21257 .Sp
21258 .Vb 2
21259 \& void do_sprintf( SV *sv, SSize_t len, SV **sarg)
21260 \& void Perl_do_sprintf(pTHX_ SV *sv, SSize_t len, SV **sarg)
21261 .Ve
21262 .RE
21263 .RS 4
21264 .RE
21265 .ie n .IP """fbm_compile""" 4
21266 .el .IP \f(CWfbm_compile\fR 4
21267 .IX Xref "fbm_compile"
21268 .IX Item "fbm_compile"
21269 Analyzes the string in order to make fast searches on it using \f(CWfbm_instr()\fR
21270 \&\-\- the Boyer\-Moore algorithm.
21271 .RS 4
21272 .Sp
21273 .Vb 2
21274 \& void fbm_compile( SV *sv, U32 flags)
21275 \& void Perl_fbm_compile(pTHX_ SV *sv, U32 flags)
21276 .Ve
21277 .RE
21278 .RS 4
21279 .RE
21280 .ie n .IP """fbm_instr""" 4
21281 .el .IP \f(CWfbm_instr\fR 4
21282 .IX Xref "fbm_instr"
21283 .IX Item "fbm_instr"
21284 Returns the location of the SV in the string delimited by \f(CW\*(C`big\*(C'\fR and
21285 \&\f(CW\*(C`bigend\*(C'\fR (\f(CW\*(C`bigend\*(C'\fR) is the char following the last char).
21286 It returns \f(CW\*(C`NULL\*(C'\fR if the string can\*(Aqt be found. The \f(CW\*(C`sv\*(C'\fR
21287 does not have to be \f(CW\*(C`fbm_compiled\*(C'\fR, but the search will not be as fast
21288 then.
21289 .RS 4
21290 .Sp
21291 .Vb 6
21292 \& char * fbm_instr( unsigned char *big,
21293 \& unsigned char *bigend,
21294 \& SV *littlestr, U32 flags)
21295 \& char * Perl_fbm_instr(pTHX_ unsigned char *big,
21296 \& unsigned char *bigend,
21297 \& SV *littlestr, U32 flags)
21298 .Ve
21299 .RE
21300 .RS 4
21301 .RE
21302 .ie n .IP """foldEQ""" 4
21303 .el .IP \f(CWfoldEQ\fR 4
21304 .IX Item "foldEQ"
21305 .PD 0
21306 .ie n .IP """foldEQ_locale""" 4
21307 .el .IP \f(CWfoldEQ_locale\fR 4
21308 .IX Xref "foldEQ foldEQ_locale"
21309 .IX Item "foldEQ_locale"
21310 .PD
21311 These each return true if the leading \f(CW\*(C`len\*(C'\fR bytes of the strings \f(CW\*(C`s1\*(C'\fR and
21312 \&\f(CW\*(C`s2\*(C'\fR are the same case\-insensitively; false otherwise.
21313 .Sp
21314 In \f(CW\*(C`foldEQ\*(C'\fR, uppercase and lowercase ASCII range bytes match themselves and
21315 their opposite case counterparts. Non\-cased and non\-ASCII range bytes match
21316 only themselves.
21317 .Sp
21318 In \f(CW\*(C`foldEQ_locale\*(C'\fR, the comparison is based on the current locale.
21319 If that locale is UTF\-8, the results are the same as \f(CW\*(C`foldEQ\*(C'\fR, leading to
21320 incorrect values for non\-ASCII range code points. Use \f(CW"foldEQ_utf8"\fR
21321 instead.
21322 .RS 4
21323 .Sp
21324 .Vb 8
21325 \& I32 foldEQ ( const char *a, const char *b,
21326 \& I32 len)
21327 \& I32 Perl_foldEQ (pTHX_ const char *a, const char *b,
21328 \& I32 len)
21329 \& I32 foldEQ_locale( const char *a, const char *b,
21330 \& I32 len)
21331 \& I32 Perl_foldEQ_locale(pTHX_ const char *a, const char *b,
21332 \& I32 len)
21333 .Ve
21334 .RE
21335 .RS 4
21336 .RE
21337 .ie n .IP """ibcmp""" 4
21338 .el .IP \f(CWibcmp\fR 4
21339 .IX Item "ibcmp"
21340 .PD 0
21341 .ie n .IP """ibcmp_locale""" 4
21342 .el .IP \f(CWibcmp_locale\fR 4
21343 .IX Item "ibcmp_locale"
21344 .ie n .IP """ibcmp_utf8""" 4
21345 .el .IP \f(CWibcmp_utf8\fR 4
21346 .IX Xref "ibcmp ibcmp_locale ibcmp_utf8"
21347 .IX Item "ibcmp_utf8"
21348 .PD
21349 These return the complement of \f(CW"foldEQ"\fR, \f(CW"foldEQ_locale"\fR, and
21350 \&\f(CW"foldEQ_utf8"\fR respectively. Those other names are preferred, as being
21351 clearer.
21352 .Sp
21353 Hence, for example, \f(CWibcmp()\fR is \f(CW\*(C`(!\ foldEQ())\*(C'\fR
21354 .RS 4
21355 .Sp
21356 .Vb 4
21357 \& I32 ibcmp (const char *a, const char *b, I32 len)
21358 \& I32 ibcmp_locale(const char *a, const char *b, I32 len)
21359 \& I32 ibcmp_utf8 (const char *s1, char **pe1, UV l1, bool u1,
21360 \& const char *s2, char **pe2, UV l2, bool u2)
21361 .Ve
21362 .RE
21363 .RS 4
21364 .RE
21365 .ie n .IP """instr""" 4
21366 .el .IP \f(CWinstr\fR 4
21367 .IX Xref "instr"
21368 .IX Item "instr"
21369 Same as \fBstrstr\fR\|(3), which finds and returns a pointer to the first occurrence
21370 of the NUL\-terminated substring \f(CW\*(C`little\*(C'\fR in the NUL\-terminated string \f(CW\*(C`big\*(C'\fR,
21371 returning NULL if not found. The terminating NUL bytes are not compared.
21372 .RS 4
21373 .Sp
21374 .Vb 2
21375 \& char * instr(const char *big, const char *little)
21376 \& char * Perl_instr(const char *big, const char *little)
21377 .Ve
21378 .RE
21379 .RS 4
21380 .RE
21381 .ie n .IP """memCHRs""" 4
21382 .el .IP \f(CWmemCHRs\fR 4
21383 .IX Xref "memCHRs"
21384 .IX Item "memCHRs"
21385 Returns the position of the first occurrence of the byte \f(CW\*(C`c\*(C'\fR in the literal
21386 string \f(CW"list"\fR, or NULL if \f(CW\*(C`c\*(C'\fR doesn\*(Aqt appear in \f(CW"list"\fR. All bytes are
21387 treated as unsigned char. Thus this macro can be used to determine if \f(CW\*(C`c\*(C'\fR is
21388 in a set of particular characters. Unlike \fBstrchr\fR\|(3), it works even if \f(CW\*(C`c\*(C'\fR
21389 is \f(CW\*(C`NUL\*(C'\fR (and the set doesn\*(Aqt include \f(CW\*(C`NUL\*(C'\fR).
21390 .RS 4
21391 .Sp
21392 .Vb 1
21393 \& bool memCHRs("list", char c)
21394 .Ve
21395 .RE
21396 .RS 4
21397 .RE
21398 .ie n .IP """memEQ""" 4
21399 .el .IP \f(CWmemEQ\fR 4
21400 .IX Xref "memEQ"
21401 .IX Item "memEQ"
21402 Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they
21403 are equal. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare.
21404 Returns true or false. It is undefined behavior if either of the buffers
21405 doesn\*(Aqt contain at least \f(CW\*(C`len\*(C'\fR bytes.
21406 .RS 4
21407 .Sp
21408 .Vb 1
21409 \& bool memEQ(char* s1, char* s2, STRLEN len)
21410 .Ve
21411 .RE
21412 .RS 4
21413 .RE
21414 .ie n .IP """memEQs""" 4
21415 .el .IP \f(CWmemEQs\fR 4
21416 .IX Xref "memEQs"
21417 .IX Item "memEQs"
21418 Like "memEQ", but the second string is a literal enclosed in double quotes,
21419 \&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR.
21420 Returns true or false.
21421 .RS 4
21422 .Sp
21423 .Vb 1
21424 \& bool memEQs(char* s1, STRLEN l1, "s2")
21425 .Ve
21426 .RE
21427 .RS 4
21428 .RE
21429 .ie n .IP """memNE""" 4
21430 .el .IP \f(CWmemNE\fR 4
21431 .IX Xref "memNE"
21432 .IX Item "memNE"
21433 Test two buffers (which may contain embedded \f(CW\*(C`NUL\*(C'\fR characters, to see if they
21434 are not equal. The \f(CW\*(C`len\*(C'\fR parameter indicates the number of bytes to compare.
21435 Returns true or false. It is undefined behavior if either of the buffers
21436 doesn\*(Aqt contain at least \f(CW\*(C`len\*(C'\fR bytes.
21437 .RS 4
21438 .Sp
21439 .Vb 1
21440 \& bool memNE(char* s1, char* s2, STRLEN len)
21441 .Ve
21442 .RE
21443 .RS 4
21444 .RE
21445 .ie n .IP """memNEs""" 4
21446 .el .IP \f(CWmemNEs\fR 4
21447 .IX Xref "memNEs"
21448 .IX Item "memNEs"
21449 Like "memNE", but the second string is a literal enclosed in double quotes,
21450 \&\f(CW\*(C`l1\*(C'\fR gives the number of bytes in \f(CW\*(C`s1\*(C'\fR.
21451 Returns true or false.
21452 .RS 4
21453 .Sp
21454 .Vb 1
21455 \& bool memNEs(char* s1, STRLEN l1, "s2")
21456 .Ve
21457 .RE
21458 .RS 4
21459 .RE
21460 .ie n .IP """Move""" 4
21461 .el .IP \f(CWMove\fR 4
21462 .IX Item "Move"
21463 .PD 0
21464 .ie n .IP """MoveD""" 4
21465 .el .IP \f(CWMoveD\fR 4
21466 .IX Xref "Move MoveD"
21467 .IX Item "MoveD"
21468 .PD
21469 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`memmove\*(C'\fR function. The \f(CW\*(C`src\*(C'\fR is the
21470 source, \f(CW\*(C`dest\*(C'\fR is the destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and
21471 \&\f(CW\*(C`type\*(C'\fR is the type. Can do overlapping moves. See also \f(CW"Copy"\fR.
21472 .Sp
21473 \&\f(CW\*(C`MoveD\*(C'\fR is like \f(CW\*(C`Move\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful
21474 for encouraging compilers to tail\-call
21475 optimise.
21476 .RS 4
21477 .Sp
21478 .Vb 2
21479 \& void Move (void* src, void* dest, int nitems, type)
21480 \& void * MoveD(void* src, void* dest, int nitems, type)
21481 .Ve
21482 .RE
21483 .RS 4
21484 .RE
21485 .ie n .IP """my_snprintf""" 4
21486 .el .IP \f(CWmy_snprintf\fR 4
21487 .IX Xref "my_snprintf"
21488 .IX Item "my_snprintf"
21489 The C library \f(CW\*(C`snprintf\*(C'\fR functionality, if available and
21490 standards\-compliant (uses \f(CW\*(C`vsnprintf\*(C'\fR, actually). However, if the
21491 \&\f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately use the unsafe
21492 \&\f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an overrun check,
21493 but that may be too late). Consider using \f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or
21494 getting \f(CW\*(C`vsnprintf\*(C'\fR.
21495 .RS 4
21496 .Sp
21497 .Vb 4
21498 \& int my_snprintf(char *buffer, const Size_t len,
21499 \& const char *format, ...)
21500 \& int Perl_my_snprintf(char *buffer, const Size_t len,
21501 \& const char *format, ...)
21502 .Ve
21503 .RE
21504 .RS 4
21505 .RE
21506 .ie n .IP """my_sprintf""" 4
21507 .el .IP \f(CWmy_sprintf\fR 4
21508 .IX Xref "my_sprintf"
21509 .IX Item "my_sprintf"
21510 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`my_sprintf\*(C'\fR
21511 from a future release of Perl. Do not use it for
21512 new code; remove it from existing code.
21513 .Sp
21514 Do NOT use this due to the possibility of overflowing \f(CW\*(C`buffer\*(C'\fR. Instead use
21515 \&\fBmy_snprintf()\fR
21516 .RS 4
21517 .Sp
21518 .Vb 1
21519 \& int my_sprintf(char *buffer, const char *pat, ...)
21520 .Ve
21521 .RE
21522 .RS 4
21523 .RE
21524 .ie n .IP """my_strlcat""" 4
21525 .el .IP \f(CWmy_strlcat\fR 4
21526 .IX Xref "my_strlcat"
21527 .IX Item "my_strlcat"
21528 The C library \f(CW\*(C`strlcat\*(C'\fR if available, or a Perl implementation of it.
21529 This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings.
21530 .Sp
21531 \&\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
21532 most \f(CW\*(C`size\ \-\ strlen(dst)\ \-\ 1\*(C'\fR bytes. It will then \f(CW\*(C`NUL\*(C'\fR\-terminate,
21533 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
21534 practice this should not happen as it means that either \f(CW\*(C`size\*(C'\fR is incorrect or
21535 that \f(CW\*(C`dst\*(C'\fR is not a proper \f(CW\*(C`NUL\*(C'\fR\-terminated string).
21536 .Sp
21537 Note that \f(CW\*(C`size\*(C'\fR is the full size of the destination buffer and
21538 the result is guaranteed to be \f(CW\*(C`NUL\*(C'\fR\-terminated if there is room. Note that
21539 room for the \f(CW\*(C`NUL\*(C'\fR should be included in \f(CW\*(C`size\*(C'\fR.
21540 .Sp
21541 The return value is the total length that \f(CW\*(C`dst\*(C'\fR would have if \f(CW\*(C`size\*(C'\fR is
21542 sufficiently large. Thus it is the initial length of \f(CW\*(C`dst\*(C'\fR plus the length of
21543 \&\f(CW\*(C`src\*(C'\fR. If \f(CW\*(C`size\*(C'\fR is smaller than the return, the excess was not appended.
21544 .RS 4
21545 .Sp
21546 .Vb 2
21547 \& Size_t my_strlcat(char *dst, const char *src, Size_t size)
21548 \& Size_t Perl_my_strlcat(char *dst, const char *src, Size_t size)
21549 .Ve
21550 .RE
21551 .RS 4
21552 .RE
21553 .ie n .IP """my_strlcpy""" 4
21554 .el .IP \f(CWmy_strlcpy\fR 4
21555 .IX Xref "my_strlcpy"
21556 .IX Item "my_strlcpy"
21557 The C library \f(CW\*(C`strlcpy\*(C'\fR if available, or a Perl implementation of it.
21558 This operates on C \f(CW\*(C`NUL\*(C'\fR\-terminated strings.
21559 .Sp
21560 \&\f(CWmy_strlcpy()\fR copies up to \f(CW\*(C`size\ \-\ 1\*(C'\fR bytes from the string \f(CW\*(C`src\*(C'\fR
21561 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.
21562 .Sp
21563 The return value is the total length \f(CW\*(C`src\*(C'\fR would be if the copy completely
21564 succeeded. If it is larger than \f(CW\*(C`size\*(C'\fR, the excess was not copied.
21565 .RS 4
21566 .Sp
21567 .Vb 1
21568 \& Size_t my_strlcpy(char *dst, const char *src, Size_t size)
21569 .Ve
21570 .RE
21571 .RS 4
21572 .RE
21573 .ie n .IP """my_strnlen""" 4
21574 .el .IP \f(CWmy_strnlen\fR 4
21575 .IX Xref "my_strnlen"
21576 .IX Item "my_strnlen"
21577 The C library \f(CW\*(C`strnlen\*(C'\fR if available, or a Perl implementation of it.
21578 .Sp
21579 \&\f(CWmy_strnlen()\fR computes the length of the string, up to \f(CW\*(C`maxlen\*(C'\fR
21580 bytes. It will never attempt to address more than \f(CW\*(C`maxlen\*(C'\fR
21581 bytes, making it suitable for use with strings that are not
21582 guaranteed to be NUL\-terminated.
21583 .RS 4
21584 .Sp
21585 .Vb 2
21586 \& Size_t my_strnlen(const char *str, Size_t maxlen)
21587 \& Size_t Perl_my_strnlen(const char *str, Size_t maxlen)
21588 .Ve
21589 .RE
21590 .RS 4
21591 .RE
21592 .ie n .IP """my_vsnprintf""" 4
21593 .el .IP \f(CWmy_vsnprintf\fR 4
21594 .IX Xref "my_vsnprintf"
21595 .IX Item "my_vsnprintf"
21596 The C library \f(CW\*(C`vsnprintf\*(C'\fR if available and standards\-compliant.
21597 However, if the \f(CW\*(C`vsnprintf\*(C'\fR is not available, will unfortunately
21598 use the unsafe \f(CW\*(C`vsprintf\*(C'\fR which can overrun the buffer (there is an
21599 overrun check, but that may be too late). Consider using
21600 \&\f(CW\*(C`sv_vcatpvf\*(C'\fR instead, or getting \f(CW\*(C`vsnprintf\*(C'\fR.
21601 .RS 4
21602 .Sp
21603 .Vb 4
21604 \& int my_vsnprintf(char *buffer, const Size_t len,
21605 \& const char *format, va_list ap)
21606 \& int Perl_my_vsnprintf(char *buffer, const Size_t len,
21607 \& const char *format, va_list ap)
21608 .Ve
21609 .RE
21610 .RS 4
21611 .RE
21612 .ie n .IP """NewCopy""" 4
21613 .el .IP \f(CWNewCopy\fR 4
21614 .IX Xref "NewCopy"
21615 .IX Item "NewCopy"
21616 Combines \fBNewx()\fR and \fBCopy()\fR into a single macro. Dest will be allocated
21617 using \fBNewx()\fR and then src will be copied into it.
21618 .RS 4
21619 .Sp
21620 .Vb 1
21621 \& void NewCopy(void* src, void* dest, int nitems, type)
21622 .Ve
21623 .RE
21624 .RS 4
21625 .RE
21626 .ie n .IP """ninstr""" 4
21627 .el .IP \f(CWninstr\fR 4
21628 .IX Xref "ninstr"
21629 .IX Item "ninstr"
21630 Find the first (leftmost) occurrence of a sequence of bytes within another
21631 sequence. This is the Perl version of \f(CWstrstr()\fR, extended to handle
21632 arbitrary sequences, potentially containing embedded \f(CW\*(C`NUL\*(C'\fR characters (\f(CW\*(C`NUL\*(C'\fR
21633 is what the initial \f(CW\*(C`n\*(C'\fR in the function name stands for; some systems have an
21634 equivalent, \f(CWmemmem()\fR, but with a somewhat different API).
21635 .Sp
21636 Another way of thinking about this function is finding a needle in a haystack.
21637 \&\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
21638 beyond the final byte in the haystack. \f(CW\*(C`little\*(C'\fR points to the first byte in
21639 the needle. \f(CW\*(C`little_end\*(C'\fR points to one byte beyond the final byte in the
21640 needle. All the parameters must be non\-\f(CW\*(C`NULL\*(C'\fR.
21641 .Sp
21642 The function returns \f(CW\*(C`NULL\*(C'\fR if there is no occurrence of \f(CW\*(C`little\*(C'\fR within
21643 \&\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.
21644 .Sp
21645 Because this function operates at the byte level, and because of the inherent
21646 characteristics of UTF\-8 (or UTF\-EBCDIC), it will work properly if both the
21647 needle and the haystack are strings with the same UTF\-8ness, but not if the
21648 UTF\-8ness differs.
21649 .RS 4
21650 .Sp
21651 .Vb 4
21652 \& char * ninstr(const char *big, const char *bigend,
21653 \& const char *little, const char *lend)
21654 \& char * Perl_ninstr(const char *big, const char *bigend,
21655 \& const char *little, const char *lend)
21656 .Ve
21657 .RE
21658 .RS 4
21659 .RE
21660 .ie n .IP """Nullch""" 4
21661 .el .IP \f(CWNullch\fR 4
21662 .IX Xref "Nullch"
21663 .IX Item "Nullch"
21664 Null character pointer. (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is
21665 defined.)
21666 .ie n .IP """PL_na""" 4
21667 .el .IP \f(CWPL_na\fR 4
21668 .IX Xref "PL_na"
21669 .IX Item "PL_na"
21670 A scratch pad variable in which to store a \f(CW\*(C`STRLEN\*(C'\fR value. If would have been
21671 better named something like \f(CW\*(C`PL_temp_strlen\*(C'\fR.
21672 .Sp
21673 It is is typically used with \f(CW\*(C`SvPV\*(C'\fR when one is actually planning to discard
21674 the returned length, (hence the length is "Not Applicable", which is how this
21675 variable got its name).
21676 .Sp
21677 \&\fBBUT BEWARE\fR, if this is used in a situation where something that is using it
21678 is in a call stack with something else that is using it, this variable would
21679 get zapped, leading to hard\-to\-diagnose errors.
21680 .Sp
21681 It is usually more efficient to either declare a local variable and use that
21682 instead, or to use the \f(CW\*(C`SvPV_nolen\*(C'\fR macro.
21683 .RS 4
21684 .Sp
21685 .Vb 1
21686 \& STRLEN PL_na
21687 .Ve
21688 .RE
21689 .RS 4
21690 .RE
21691 .ie n .IP """rninstr""" 4
21692 .el .IP \f(CWrninstr\fR 4
21693 .IX Xref "rninstr"
21694 .IX Item "rninstr"
21695 Like \f(CW"ninstr"\fR, but instead finds the final (rightmost) occurrence of a
21696 sequence of bytes within another sequence, returning \f(CW\*(C`NULL\*(C'\fR if there is no
21697 such occurrence.
21698 .RS 4
21699 .Sp
21700 .Vb 4
21701 \& char * rninstr(const char *big, const char *bigend,
21702 \& const char *little, const char *lend)
21703 \& char * Perl_rninstr(const char *big, const char *bigend,
21704 \& const char *little, const char *lend)
21705 .Ve
21706 .RE
21707 .RS 4
21708 .RE
21709 .ie n .IP """savepv""" 4
21710 .el .IP \f(CWsavepv\fR 4
21711 .IX Item "savepv"
21712 .PD 0
21713 .ie n .IP """savepvn""" 4
21714 .el .IP \f(CWsavepvn\fR 4
21715 .IX Item "savepvn"
21716 .ie n .IP """savepvs""" 4
21717 .el .IP \f(CWsavepvs\fR 4
21718 .IX Item "savepvs"
21719 .ie n .IP """savesvpv""" 4
21720 .el .IP \f(CWsavesvpv\fR 4
21721 .IX Item "savesvpv"
21722 .ie n .IP """savesharedpv""" 4
21723 .el .IP \f(CWsavesharedpv\fR 4
21724 .IX Item "savesharedpv"
21725 .ie n .IP """savesharedpvn""" 4
21726 .el .IP \f(CWsavesharedpvn\fR 4
21727 .IX Item "savesharedpvn"
21728 .ie n .IP """savesharedpvs""" 4
21729 .el .IP \f(CWsavesharedpvs\fR 4
21730 .IX Item "savesharedpvs"
21731 .ie n .IP """savesharedsvpv""" 4
21732 .el .IP \f(CWsavesharedsvpv\fR 4
21733 .IX Xref "savepv savepvn savepvs savesharedpv savesharedpvn savesharedpvs savesharedsvpv savesvpv"
21734 .IX Item "savesharedsvpv"
21735 .PD
21736 Perl\*(Aqs version of \f(CWstrdup()\fR (or \f(CWstrndup()\fR would be if it existed).
21737 .Sp
21738 These each return a pointer to a newly allocated string which is a duplicate of
21739 the input string.
21740 .Sp
21741 The forms differ in how the string to be copied is specified, and where the new
21742 memory is allocated from.
21743 .Sp
21744 To prevent memory leaks, the memory allocated for the new string needs to be
21745 freed when no longer needed. This can be done with the \f(CW"Safefree"\fR
21746 function, or \f(CW\*(C`SAVEFREEPV\*(C'\fR.
21747 .Sp
21748 The forms whose names contain \f(CW\*(C`shared\*(C'\fR differ from the corresponding form
21749 without that in its name, only in that the memory in the former comes from
21750 memory shared between threads. This is needed, because on some platforms,
21751 Windows for example, all allocated memory owned by a thread is deallocated when
21752 that thread ends. So if you need that not to happen, you need to use the
21753 shared memory forms.
21754 .Sp
21755 The string to copy in \f(CW\*(C`savepvs\*(C'\fR is a C language string literal surrounded by
21756 double quotes.
21757 .Sp
21758 The string to copy in the forms whose name contains \f(CW\*(C`svpv\*(C'\fR comes from the PV
21759 in the SV argument \f(CW\*(C`sv\*(C'\fR, using \f(CWSvPV()\fR
21760 .Sp
21761 The string to copy in the remaining forms comes from the \f(CW\*(C`pv\*(C'\fR argument.
21762 .Sp
21763 In the case of \f(CW\*(C`savepv\*(C'\fR, the size of the string is determined by \f(CWstrlen()\fR,
21764 which means it may not contain embedded \f(CW\*(C`NUL\*(C'\fR characters, and must have a
21765 trailing \f(CW\*(C`NUL\*(C'\fR.
21766 .Sp
21767 In the case of \f(CW\*(C`savepvn\*(C'\fR, \f(CW\*(C`len\*(C'\fR gives the length of \f(CW\*(C`pv\*(C'\fR, hence it may
21768 contain embedded \f(CW\*(C`NUL\*(C'\fR characters. The copy will be guaranteed to have a
21769 trailing NUL added if not already present.
21770 .RS 4
21771 .Sp
21772 .Vb 10
21773 \& char * savepv ( const char *pv)
21774 \& char * Perl_savepv (pTHX_ const char *pv)
21775 \& char * savepvn ( const char *pv, Size_t len)
21776 \& char * Perl_savepvn (pTHX_ const char *pv, Size_t len)
21777 \& char* savepvs ( "literal string")
21778 \& char * savesvpv ( SV *sv)
21779 \& char * Perl_savesvpv (pTHX_ SV *sv)
21780 \& char * savesharedpv ( const char *pv)
21781 \& char * Perl_savesharedpv (pTHX_ const char *pv)
21782 \& char * savesharedpvn ( const char * const pv,
21783 \& const STRLEN len)
21784 \& char * Perl_savesharedpvn (pTHX_ const char * const pv,
21785 \& const STRLEN len)
21786 \& char* savesharedpvs ( "literal string")
21787 \& char * savesharedsvpv( SV *sv)
21788 \& char * Perl_savesharedsvpv(pTHX_ SV *sv)
21789 .Ve
21790 .RE
21791 .RS 4
21792 .RE
21793 .ie n .IP """STR_WITH_LEN""" 4
21794 .el .IP \f(CWSTR_WITH_LEN\fR 4
21795 .IX Xref "STR_WITH_LEN"
21796 .IX Item "STR_WITH_LEN"
21797 Returns two comma separated tokens of the input literal string, and its length.
21798 This is convenience macro which helps out in some API calls.
21799 Note that it can\*(Aqt be used as an argument to macros or functions that under
21800 some configurations might be macros, which means that it requires the full
21801 Perl_xxx(aTHX_ ...) form for any API calls where it\*(Aqs used.
21802 .RS 4
21803 .Sp
21804 .Vb 1
21805 \& pair STR_WITH_LEN("literal string")
21806 .Ve
21807 .RE
21808 .RS 4
21809 .RE
21810 .ie n .IP """strEQ""" 4
21811 .el .IP \f(CWstrEQ\fR 4
21812 .IX Xref "strEQ"
21813 .IX Item "strEQ"
21814 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal. Returns true or
21815 false.
21816 .RS 4
21817 .Sp
21818 .Vb 1
21819 \& bool strEQ(char* s1, char* s2)
21820 .Ve
21821 .RE
21822 .RS 4
21823 .RE
21824 .ie n .IP """strGE""" 4
21825 .el .IP \f(CWstrGE\fR 4
21826 .IX Xref "strGE"
21827 .IX Item "strGE"
21828 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than
21829 or equal to the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21830 .RS 4
21831 .Sp
21832 .Vb 1
21833 \& bool strGE(char* s1, char* s2)
21834 .Ve
21835 .RE
21836 .RS 4
21837 .RE
21838 .ie n .IP """strGT""" 4
21839 .el .IP \f(CWstrGT\fR 4
21840 .IX Xref "strGT"
21841 .IX Item "strGT"
21842 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if the first, \f(CW\*(C`s1\*(C'\fR, is greater than
21843 the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21844 .RS 4
21845 .Sp
21846 .Vb 1
21847 \& bool strGT(char* s1, char* s2)
21848 .Ve
21849 .RE
21850 .RS 4
21851 .RE
21852 .ie n .IP """strLE""" 4
21853 .el .IP \f(CWstrLE\fR 4
21854 .IX Xref "strLE"
21855 .IX Item "strLE"
21856 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
21857 equal to the second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21858 .RS 4
21859 .Sp
21860 .Vb 1
21861 \& bool strLE(char* s1, char* s2)
21862 .Ve
21863 .RE
21864 .RS 4
21865 .RE
21866 .ie n .IP """STRLEN""" 4
21867 .el .IP \f(CWSTRLEN\fR 4
21868 .IX Item "STRLEN"
21869 Described in perlguts.
21870 .ie n .IP """strLT""" 4
21871 .el .IP \f(CWstrLT\fR 4
21872 .IX Xref "strLT"
21873 .IX Item "strLT"
21874 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
21875 second, \f(CW\*(C`s2\*(C'\fR. Returns true or false.
21876 .RS 4
21877 .Sp
21878 .Vb 1
21879 \& bool strLT(char* s1, char* s2)
21880 .Ve
21881 .RE
21882 .RS 4
21883 .RE
21884 .ie n .IP """strNE""" 4
21885 .el .IP \f(CWstrNE\fR 4
21886 .IX Xref "strNE"
21887 .IX Item "strNE"
21888 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different. Returns true
21889 or false.
21890 .RS 4
21891 .Sp
21892 .Vb 1
21893 \& bool strNE(char* s1, char* s2)
21894 .Ve
21895 .RE
21896 .RS 4
21897 .RE
21898 .ie n .IP """strnEQ""" 4
21899 .el .IP \f(CWstrnEQ\fR 4
21900 .IX Xref "strnEQ"
21901 .IX Item "strnEQ"
21902 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are equal. The \f(CW\*(C`len\*(C'\fR
21903 parameter indicates the number of bytes to compare. Returns true or false. (A
21904 wrapper for \f(CW\*(C`strncmp\*(C'\fR).
21905 .RS 4
21906 .Sp
21907 .Vb 1
21908 \& bool strnEQ(char* s1, char* s2, STRLEN len)
21909 .Ve
21910 .RE
21911 .RS 4
21912 .RE
21913 .ie n .IP """strnNE""" 4
21914 .el .IP \f(CWstrnNE\fR 4
21915 .IX Xref "strnNE"
21916 .IX Item "strnNE"
21917 Test two \f(CW\*(C`NUL\*(C'\fR\-terminated strings to see if they are different. The \f(CW\*(C`len\*(C'\fR
21918 parameter indicates the number of bytes to compare. Returns true or false. (A
21919 wrapper for \f(CW\*(C`strncmp\*(C'\fR).
21920 .RS 4
21921 .Sp
21922 .Vb 1
21923 \& bool strnNE(char* s1, char* s2, STRLEN len)
21924 .Ve
21925 .RE
21926 .RS 4
21927 .RE
21928 .ie n .IP """Zero""" 4
21929 .el .IP \f(CWZero\fR 4
21930 .IX Item "Zero"
21931 .PD 0
21932 .ie n .IP """ZeroD""" 4
21933 .el .IP \f(CWZeroD\fR 4
21934 .IX Xref "Zero ZeroD"
21935 .IX Item "ZeroD"
21936 .PD
21937 The XSUB\-writer\*(Aqs interface to the C \f(CW\*(C`memzero\*(C'\fR function. The \f(CW\*(C`dest\*(C'\fR is the
21938 destination, \f(CW\*(C`nitems\*(C'\fR is the number of items, and \f(CW\*(C`type\*(C'\fR is the type.
21939 .Sp
21940 \&\f(CW\*(C`ZeroD\*(C'\fR is like \f(CW\*(C`Zero\*(C'\fR but returns \f(CW\*(C`dest\*(C'\fR. Useful
21941 for encouraging compilers to tail\-call
21942 optimise.
21943 .RS 4
21944 .Sp
21945 .Vb 2
21946 \& void Zero (void* dest, int nitems, type)
21947 \& void * ZeroD(void* dest, int nitems, type)
21948 .Ve
21949 .RE
21950 .RS 4
21951 .RE
21952 .SH "SV Flags"
21953 .IX Header "SV Flags"
21954 .ie n .IP """SVt_IV""" 4
21955 .el .IP \f(CWSVt_IV\fR 4
21956 .IX Item "SVt_IV"
21957 .PD 0
21958 .ie n .IP """SVt_NULL""" 4
21959 .el .IP \f(CWSVt_NULL\fR 4
21960 .IX Item "SVt_NULL"
21961 .ie n .IP """SVt_NV""" 4
21962 .el .IP \f(CWSVt_NV\fR 4
21963 .IX Item "SVt_NV"
21964 .ie n .IP """SVt_PV""" 4
21965 .el .IP \f(CWSVt_PV\fR 4
21966 .IX Xref "SVt_IV SVt_NULL SVt_NV SVt_PV"
21967 .IX Item "SVt_PV"
21968 .PD
21969 Type flag for scalars. See "svtype".
21970 .ie n .IP """SVt_PVAV""" 4
21971 .el .IP \f(CWSVt_PVAV\fR 4
21972 .IX Xref "SVt_PVAV"
21973 .IX Item "SVt_PVAV"
21974 Type flag for arrays. See "svtype".
21975 .ie n .IP """SVt_PVCV""" 4
21976 .el .IP \f(CWSVt_PVCV\fR 4
21977 .IX Xref "SVt_PVCV"
21978 .IX Item "SVt_PVCV"
21979 Type flag for subroutines. See "svtype".
21980 .ie n .IP """SVt_PVFM""" 4
21981 .el .IP \f(CWSVt_PVFM\fR 4
21982 .IX Xref "SVt_PVFM"
21983 .IX Item "SVt_PVFM"
21984 Type flag for formats. See "svtype".
21985 .ie n .IP """SVt_PVGV""" 4
21986 .el .IP \f(CWSVt_PVGV\fR 4
21987 .IX Xref "SVt_PVGV"
21988 .IX Item "SVt_PVGV"
21989 Type flag for typeglobs. See "svtype".
21990 .ie n .IP """SVt_PVHV""" 4
21991 .el .IP \f(CWSVt_PVHV\fR 4
21992 .IX Xref "SVt_PVHV"
21993 .IX Item "SVt_PVHV"
21994 Type flag for hashes. See "svtype".
21995 .ie n .IP """SVt_PVIO""" 4
21996 .el .IP \f(CWSVt_PVIO\fR 4
21997 .IX Xref "SVt_PVIO"
21998 .IX Item "SVt_PVIO"
21999 Type flag for I/O objects. See "svtype".
22000 .ie n .IP """SVt_PVIV""" 4
22001 .el .IP \f(CWSVt_PVIV\fR 4
22002 .IX Item "SVt_PVIV"
22003 .PD 0
22004 .ie n .IP """SVt_PVLV""" 4
22005 .el .IP \f(CWSVt_PVLV\fR 4
22006 .IX Item "SVt_PVLV"
22007 .ie n .IP """SVt_PVMG""" 4
22008 .el .IP \f(CWSVt_PVMG\fR 4
22009 .IX Item "SVt_PVMG"
22010 .ie n .IP """SVt_PVNV""" 4
22011 .el .IP \f(CWSVt_PVNV\fR 4
22012 .IX Xref "SVt_PVIV SVt_PVLV SVt_PVMG SVt_PVNV"
22013 .IX Item "SVt_PVNV"
22014 .PD
22015 Type flag for scalars. See "svtype".
22016 .ie n .IP """SVt_PVOBJ""" 4
22017 .el .IP \f(CWSVt_PVOBJ\fR 4
22018 .IX Xref "SVt_PVOBJ"
22019 .IX Item "SVt_PVOBJ"
22020 NOTE: \f(CW\*(C`SVt_PVOBJ\*(C'\fR is \fBexperimental\fR and may change or be
22021 removed without notice.
22022 .Sp
22023 Type flag for object instances. See "svtype".
22024 .ie n .IP """SVt_REGEXP""" 4
22025 .el .IP \f(CWSVt_REGEXP\fR 4
22026 .IX Xref "SVt_REGEXP"
22027 .IX Item "SVt_REGEXP"
22028 Type flag for regular expressions. See "svtype".
22029 .ie n .IP """svtype""" 4
22030 .el .IP \f(CWsvtype\fR 4
22031 .IX Xref "svtype"
22032 .IX Item "svtype"
22033 An enum of flags for Perl types. These are found in the file \fIsv.h\fR
22034 in the \f(CW\*(C`svtype\*(C'\fR enum. Test these flags with the \f(CW\*(C`SvTYPE\*(C'\fR macro.
22035 .Sp
22036 The types are:
22037 .Sp
22038 .Vb 10
22039 \& SVt_NULL
22040 \& SVt_IV
22041 \& SVt_NV
22042 \& SVt_RV
22043 \& SVt_PV
22044 \& SVt_PVIV
22045 \& SVt_PVNV
22046 \& SVt_PVMG
22047 \& SVt_INVLIST
22048 \& SVt_REGEXP
22049 \& SVt_PVGV
22050 \& SVt_PVLV
22051 \& SVt_PVAV
22052 \& SVt_PVHV
22053 \& SVt_PVCV
22054 \& SVt_PVFM
22055 \& SVt_PVIO
22056 \& SVt_PVOBJ
22057 .Ve
22058 .Sp
22059 These are most easily explained from the bottom up.
22060 .Sp
22061 \&\f(CW\*(C`SVt_PVOBJ\*(C'\fR is for object instances of the new \`use feature \*(Aqclass\*(Aq\` kind.
22062 \&\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
22063 subroutines, \f(CW\*(C`SVt_PVHV\*(C'\fR for hashes and \f(CW\*(C`SVt_PVAV\*(C'\fR for arrays.
22064 .Sp
22065 All the others are scalar types, that is, things that can be bound to a
22066 \&\f(CW\*(C`$\*(C'\fR variable. For these, the internal types are mostly orthogonal to
22067 types in the Perl language.
22068 .Sp
22069 Hence, checking \f(CW\*(C`SvTYPE(sv) < SVt_PVAV\*(C'\fR is the best way to see whether
22070 something is a scalar.
22071 .Sp
22072 \&\f(CW\*(C`SVt_PVGV\*(C'\fR represents a typeglob. If \f(CW\*(C`!SvFAKE(sv)\*(C'\fR, then it is a real,
22073 incoercible typeglob. If \f(CWSvFAKE(sv)\fR, then it is a scalar to which a
22074 typeglob has been assigned. Assigning to it again will stop it from being
22075 a typeglob. \f(CW\*(C`SVt_PVLV\*(C'\fR represents a scalar that delegates to another scalar
22076 behind the scenes. It is used, e.g., for the return value of \f(CW\*(C`substr\*(C'\fR and
22077 for tied hash and array elements. It can hold any scalar value, including
22078 a typeglob. \f(CW\*(C`SVt_REGEXP\*(C'\fR is for regular
22079 expressions. \f(CW\*(C`SVt_INVLIST\*(C'\fR is for Perl
22080 core internal use only.
22081 .Sp
22082 \&\f(CW\*(C`SVt_PVMG\*(C'\fR represents a "normal" scalar (not a typeglob, regular expression,
22083 or delegate). Since most scalars do not need all the internal fields of a
22084 PVMG, we save memory by allocating smaller structs when possible. All the
22085 other types are just simpler forms of \f(CW\*(C`SVt_PVMG\*(C'\fR, with fewer internal fields.
22086 \&\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
22087 reference. (\f(CW\*(C`SVt_RV\*(C'\fR is an alias for \f(CW\*(C`SVt_IV\*(C'\fR, which exists for backward
22088 compatibility.) \f(CW\*(C`SVt_NV\*(C'\fR can hold undef or a double. (In builds that support
22089 headless NVs, these could also hold a reference via a suitable offset, in the
22090 same way that SVt_IV does, but this is not currently supported and seems to
22091 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.
22092 \&\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
22093 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
22094 can hold, but it may also be blessed or magical.
22095 .SH "SV Handling"
22096 .IX Xref "PERL_MAGIC_utf8 SV_CATBYTES SV_CATUTF8 SV_COW_DROP_PV SV_FORCE_UTF8_UPGRADE SV_GMAGIC SV_HAS_TRAILING_NUL SV_IMMEDIATE_UNREF SV_NOSTEAL SV_SKIP_OVERLOAD SV_SMAGIC SV_UTF8_NO_ENCODING SVs_TEMP"
22097 .IX Header "SV Handling"
22098 .ie n .IP """AV_FROM_REF""" 4
22099 .el .IP \f(CWAV_FROM_REF\fR 4
22100 .IX Item "AV_FROM_REF"
22101 .PD 0
22102 .ie n .IP """CV_FROM_REF""" 4
22103 .el .IP \f(CWCV_FROM_REF\fR 4
22104 .IX Item "CV_FROM_REF"
22105 .ie n .IP """GV_FROM_REF""" 4
22106 .el .IP \f(CWGV_FROM_REF\fR 4
22107 .IX Item "GV_FROM_REF"
22108 .ie n .IP """HV_FROM_REF""" 4
22109 .el .IP \f(CWHV_FROM_REF\fR 4
22110 .IX Xref "AV_FROM_REF CV_FROM_REF GV_FROM_REF HV_FROM_REF"
22111 .IX Item "HV_FROM_REF"
22112 .PD
22113 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
22114 and return a suitably\-cast to pointer to the referenced SV. When running
22115 under \f(CW\*(C`\-DDEBUGGING\*(C'\fR, assertions are also applied that check that \fIref\fR is
22116 definitely a reference SV that refers to an SV of the right type.
22117 .RS 4
22118 .Sp
22119 .Vb 4
22120 \& AV * AV_FROM_REF(SV * ref)
22121 \& CV * CV_FROM_REF(SV * ref)
22122 \& GV * GV_FROM_REF(SV * ref)
22123 \& HV * HV_FROM_REF(SV * ref)
22124 .Ve
22125 .RE
22126 .RS 4
22127 .RE
22128 .ie n .IP """BOOL_INTERNALS_sv_isbool""" 4
22129 .el .IP \f(CWBOOL_INTERNALS_sv_isbool\fR 4
22130 .IX Xref "BOOL_INTERNALS_sv_isbool"
22131 .IX Item "BOOL_INTERNALS_sv_isbool"
22132 Checks if a \f(CWSvBoolFlagsOK()\fR sv is a bool. \fBNote\fR that it is the
22133 caller\*(Aqs responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR before
22134 calling this. This is only useful in specialized logic like
22135 serialization code where performance is critical and the flags have
22136 already been checked to be correct. Almost always you should be using
22137 \&\f(CWsv_isbool(sv)\fR instead.
22138 .RS 4
22139 .Sp
22140 .Vb 1
22141 \& bool BOOL_INTERNALS_sv_isbool(SV* sv)
22142 .Ve
22143 .RE
22144 .RS 4
22145 .RE
22146 .ie n .IP """BOOL_INTERNALS_sv_isbool_false""" 4
22147 .el .IP \f(CWBOOL_INTERNALS_sv_isbool_false\fR 4
22148 .IX Xref "BOOL_INTERNALS_sv_isbool_false"
22149 .IX Item "BOOL_INTERNALS_sv_isbool_false"
22150 Checks if a \f(CWSvBoolFlagsOK()\fR sv is a false bool. \fBNote\fR that it is
22151 the caller\*(Aqs responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR
22152 before calling this. This is only useful in specialized logic like
22153 serialization code where performance is critical and the flags have
22154 already been checked to be correct. This is \fBNOT\fR what you should use
22155 to check if an SV is "false", for that you should be using
22156 \&\f(CW\*(C`!SvTRUE(sv)\*(C'\fR instead.
22157 .RS 4
22158 .Sp
22159 .Vb 1
22160 \& bool BOOL_INTERNALS_sv_isbool_false(SV* sv)
22161 .Ve
22162 .RE
22163 .RS 4
22164 .RE
22165 .ie n .IP """BOOL_INTERNALS_sv_isbool_true""" 4
22166 .el .IP \f(CWBOOL_INTERNALS_sv_isbool_true\fR 4
22167 .IX Xref "BOOL_INTERNALS_sv_isbool_true"
22168 .IX Item "BOOL_INTERNALS_sv_isbool_true"
22169 Checks if a \f(CWSvBoolFlagsOK()\fR sv is a true bool. \fBNote\fR that it is
22170 the caller\*(Aqs responsibility to ensure that the sv is \f(CWSvBoolFlagsOK()\fR
22171 before calling this. This is only useful in specialized logic like
22172 serialization code where performance is critical and the flags have
22173 already been checked to be correct. This is \fBNOT\fR what you should use
22174 to check if an SV is "true", for that you should be using
22175 \&\f(CWSvTRUE(sv)\fR instead.
22176 .RS 4
22177 .Sp
22178 .Vb 1
22179 \& bool BOOL_INTERNALS_sv_isbool_true(SV* sv)
22180 .Ve
22181 .RE
22182 .RS 4
22183 .RE
22184 .ie n .IP """boolSV""" 4
22185 .el .IP \f(CWboolSV\fR 4
22186 .IX Xref "boolSV"
22187 .IX Item "boolSV"
22188 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.
22189 .Sp
22190 See also \f(CW"PL_sv_yes"\fR and \f(CW"PL_sv_no"\fR.
22191 .RS 4
22192 .Sp
22193 .Vb 1
22194 \& SV * boolSV(bool b)
22195 .Ve
22196 .RE
22197 .RS 4
22198 .RE
22199 .ie n .IP """croak_xs_usage""" 4
22200 .el .IP \f(CWcroak_xs_usage\fR 4
22201 .IX Xref "croak_xs_usage"
22202 .IX Item "croak_xs_usage"
22203 A specialised variant of \f(CWcroak()\fR for emitting the usage message for xsubs
22204 .Sp
22205 .Vb 1
22206 \& croak_xs_usage(cv, "eee_yow");
22207 .Ve
22208 .Sp
22209 works out the package name and subroutine name from \f(CW\*(C`cv\*(C'\fR, and then calls
22210 \&\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:
22211 .Sp
22212 .Vb 3
22213 \& diag_listed_as: SKIPME
22214 \& croak("Usage: %" SVf "::%" SVf "(%s)", "ouch" "awk",
22215 \& "eee_yow");
22216 .Ve
22217 .RS 4
22218 .Sp
22219 .Vb 4
22220 \& void croak_xs_usage(const CV * const cv,
22221 \& const char * const params)
22222 \& void Perl_croak_xs_usage(const CV * const cv,
22223 \& const char * const params)
22224 .Ve
22225 .RE
22226 .RS 4
22227 .RE
22228 .ie n .IP """CV_FROM_REF*""" 4
22229 .el .IP \f(CWCV_FROM_REF*\fR 4
22230 .IX Item "CV_FROM_REF*"
22231 Described under \f(CW"AV_FROM_REF"\fR
22232 .ie n .IP """DEFSV""" 4
22233 .el .IP \f(CWDEFSV\fR 4
22234 .IX Xref "DEFSV"
22235 .IX Item "DEFSV"
22236 Returns the SV associated with \f(CW$_\fR
22237 .RS 4
22238 .Sp
22239 .Vb 1
22240 \& SV * DEFSV
22241 .Ve
22242 .RE
22243 .RS 4
22244 .RE
22245 .ie n .IP """DEFSV_set""" 4
22246 .el .IP \f(CWDEFSV_set\fR 4
22247 .IX Xref "DEFSV_set"
22248 .IX Item "DEFSV_set"
22249 Associate \f(CW\*(C`sv\*(C'\fR with \f(CW$_\fR
22250 .RS 4
22251 .Sp
22252 .Vb 1
22253 \& void DEFSV_set(SV * sv)
22254 .Ve
22255 .RE
22256 .RS 4
22257 .RE
22258 .ie n .IP """get_sv""" 4
22259 .el .IP \f(CWget_sv\fR 4
22260 .IX Xref "get_sv"
22261 .IX Item "get_sv"
22262 Returns the SV of the specified Perl scalar. \f(CW\*(C`flags\*(C'\fR are passed to
22263 "\f(CW\*(C`gv_fetchpv\*(C'\fR". If \f(CW\*(C`GV_ADD\*(C'\fR is set and the
22264 Perl variable does not exist then it will be created. If \f(CW\*(C`flags\*(C'\fR is zero
22265 and the variable does not exist then NULL is returned.
22266 .Sp
22267 NOTE: the \f(CWperl_get_sv()\fR form is \fBdeprecated\fR.
22268 .RS 4
22269 .Sp
22270 .Vb 2
22271 \& SV * get_sv( const char *name, I32 flags)
22272 \& SV * Perl_get_sv(pTHX_ const char *name, I32 flags)
22273 .Ve
22274 .RE
22275 .RS 4
22276 .RE
22277 .ie n .IP """GV_FROM_REF*""" 4
22278 .el .IP \f(CWGV_FROM_REF*\fR 4
22279 .IX Item "GV_FROM_REF*"
22280 .PD 0
22281 .ie n .IP """HV_FROM_REF*""" 4
22282 .el .IP \f(CWHV_FROM_REF*\fR 4
22283 .IX Item "HV_FROM_REF*"
22284 .PD
22285 Described under \f(CW"AV_FROM_REF"\fR
22286 .ie n .IP """isGV_with_GP""" 4
22287 .el .IP \f(CWisGV_with_GP\fR 4
22288 .IX Xref "isGV_with_GP"
22289 .IX Item "isGV_with_GP"
22290 Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR is a GV with a pointer to a GP
22291 (glob pointer).
22292 .RS 4
22293 .Sp
22294 .Vb 1
22295 \& bool isGV_with_GP(SV * sv)
22296 .Ve
22297 .RE
22298 .RS 4
22299 .RE
22300 .ie n .IP """looks_like_number""" 4
22301 .el .IP \f(CWlooks_like_number\fR 4
22302 .IX Xref "looks_like_number"
22303 .IX Item "looks_like_number"
22304 Test if the content of an SV looks like a number (or is a number).
22305 \&\f(CW\*(C`Inf\*(C'\fR and \f(CW\*(C`Infinity\*(C'\fR are treated as numbers (so will not issue a
22306 non\-numeric warning), even if your \f(CWatof()\fR doesn\*(Aqt grok them. Get\-magic is
22307 ignored.
22308 .RS 4
22309 .Sp
22310 .Vb 2
22311 \& I32 looks_like_number( SV * const sv)
22312 \& I32 Perl_looks_like_number(pTHX_ SV * const sv)
22313 .Ve
22314 .RE
22315 .RS 4
22316 .RE
22317 .ie n .IP """MUTABLE_AV""" 4
22318 .el .IP \f(CWMUTABLE_AV\fR 4
22319 .IX Item "MUTABLE_AV"
22320 .PD 0
22321 .ie n .IP """MUTABLE_CV""" 4
22322 .el .IP \f(CWMUTABLE_CV\fR 4
22323 .IX Item "MUTABLE_CV"
22324 .ie n .IP """MUTABLE_GV""" 4
22325 .el .IP \f(CWMUTABLE_GV\fR 4
22326 .IX Item "MUTABLE_GV"
22327 .ie n .IP """MUTABLE_HV""" 4
22328 .el .IP \f(CWMUTABLE_HV\fR 4
22329 .IX Item "MUTABLE_HV"
22330 .ie n .IP """MUTABLE_IO""" 4
22331 .el .IP \f(CWMUTABLE_IO\fR 4
22332 .IX Item "MUTABLE_IO"
22333 .ie n .IP """MUTABLE_PTR""" 4
22334 .el .IP \f(CWMUTABLE_PTR\fR 4
22335 .IX Item "MUTABLE_PTR"
22336 .ie n .IP """MUTABLE_SV""" 4
22337 .el .IP \f(CWMUTABLE_SV\fR 4
22338 .IX Xref "MUTABLE_AV MUTABLE_CV MUTABLE_GV MUTABLE_HV MUTABLE_IO MUTABLE_PTR MUTABLE_SV"
22339 .IX Item "MUTABLE_SV"
22340 .PD
22341 The \f(CW\*(C`MUTABLE_\fR\f(CI*\fR\f(CW\*(C'\fR() macros cast pointers to the types shown, in such a way
22342 (compiler permitting) that casting away const\-ness will give a warning;
22343 e.g.:
22344 .Sp
22345 .Vb 4
22346 \& const SV *sv = ...;
22347 \& AV *av1 = (AV*)sv; <== BAD: the const has been silently
22348 \& cast away
22349 \& AV *av2 = MUTABLE_AV(sv); <== GOOD: it may warn
22350 .Ve
22351 .Sp
22352 \&\f(CW\*(C`MUTABLE_PTR\*(C'\fR is the base macro used to derive new casts. The other
22353 already\-built\-in ones return pointers to what their names indicate.
22354 .RS 4
22355 .Sp
22356 .Vb 7
22357 \& AV * MUTABLE_AV (AV * p)
22358 \& CV * MUTABLE_CV (CV * p)
22359 \& GV * MUTABLE_GV (GV * p)
22360 \& HV * MUTABLE_HV (HV * p)
22361 \& IO * MUTABLE_IO (IO * p)
22362 \& void * MUTABLE_PTR(void * p)
22363 \& SV * MUTABLE_SV (SV * p)
22364 .Ve
22365 .RE
22366 .RS 4
22367 .RE
22368 .ie n .IP """newRV""" 4
22369 .el .IP \f(CWnewRV\fR 4
22370 .IX Item "newRV"
22371 .PD 0
22372 .ie n .IP """newRV_inc""" 4
22373 .el .IP \f(CWnewRV_inc\fR 4
22374 .IX Xref "newRV newRV_inc"
22375 .IX Item "newRV_inc"
22376 .PD
22377 These are identical. They create an RV wrapper for an SV. The reference count
22378 for the original SV is incremented.
22379 .RS 4
22380 .Sp
22381 .Vb 3
22382 \& SV * newRV ( SV * const sv)
22383 \& SV * Perl_newRV (pTHX_ SV * const sv)
22384 \& SV * newRV_inc( SV * const sv)
22385 .Ve
22386 .RE
22387 .RS 4
22388 .RE
22389 .ie n .IP """newRV_noinc""" 4
22390 .el .IP \f(CWnewRV_noinc\fR 4
22391 .IX Xref "newRV_noinc"
22392 .IX Item "newRV_noinc"
22393 Creates an RV wrapper for an SV. The reference count for the original
22394 SV is \fBnot\fR incremented.
22395 .RS 4
22396 .Sp
22397 .Vb 2
22398 \& SV * newRV_noinc( SV * const tmpRef)
22399 \& SV * Perl_newRV_noinc(pTHX_ SV * const tmpRef)
22400 .Ve
22401 .RE
22402 .RS 4
22403 .RE
22404 .ie n .IP """newSV""" 4
22405 .el .IP \f(CWnewSV\fR 4
22406 .IX Xref "newSV"
22407 .IX Item "newSV"
22408 Creates a new SV. A non\-zero \f(CW\*(C`len\*(C'\fR parameter indicates the number of
22409 bytes of preallocated string space the SV should have. An extra byte for a
22410 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
22411 space is allocated.) The reference count for the new SV is set to 1.
22412 .Sp
22413 In 5.9.3, \f(CWnewSV()\fR replaces the older \f(CWNEWSV()\fR API, and drops the first
22414 parameter, \fIx\fR, a debug aid which allowed callers to identify themselves.
22415 This aid has been superseded by a new build option, \f(CW\*(C`PERL_MEM_LOG\*(C'\fR (see
22416 "PERL_MEM_LOG" in perlhacktips). The older API is still there for use in XS
22417 modules supporting older perls.
22418 .RS 4
22419 .Sp
22420 .Vb 2
22421 \& SV * newSV( const STRLEN len)
22422 \& SV * Perl_newSV(pTHX_ const STRLEN len)
22423 .Ve
22424 .RE
22425 .RS 4
22426 .RE
22427 .ie n .IP """newSV_false""" 4
22428 .el .IP \f(CWnewSV_false\fR 4
22429 .IX Xref "newSV_false"
22430 .IX Item "newSV_false"
22431 Creates a new SV that is a boolean false.
22432 .RS 4
22433 .Sp
22434 .Vb 2
22435 \& SV * newSV_false()
22436 \& SV * Perl_newSV_false(pTHX)
22437 .Ve
22438 .RE
22439 .RS 4
22440 .RE
22441 .ie n .IP """newSV_true""" 4
22442 .el .IP \f(CWnewSV_true\fR 4
22443 .IX Xref "newSV_true"
22444 .IX Item "newSV_true"
22445 Creates a new SV that is a boolean true.
22446 .RS 4
22447 .Sp
22448 .Vb 2
22449 \& SV * newSV_true()
22450 \& SV * Perl_newSV_true(pTHX)
22451 .Ve
22452 .RE
22453 .RS 4
22454 .RE
22455 .ie n .IP """newSV_type""" 4
22456 .el .IP \f(CWnewSV_type\fR 4
22457 .IX Xref "newSV_type"
22458 .IX Item "newSV_type"
22459 Creates a new SV, of the type specified. The reference count for the new SV
22460 is set to 1.
22461 .RS 4
22462 .Sp
22463 .Vb 2
22464 \& SV * newSV_type( const svtype type)
22465 \& SV * Perl_newSV_type(pTHX_ const svtype type)
22466 .Ve
22467 .RE
22468 .RS 4
22469 .RE
22470 .ie n .IP """newSV_type_mortal""" 4
22471 .el .IP \f(CWnewSV_type_mortal\fR 4
22472 .IX Xref "newSV_type_mortal"
22473 .IX Item "newSV_type_mortal"
22474 Creates a new mortal SV, of the type specified. The reference count for the
22475 new SV is set to 1.
22476 .Sp
22477 This is equivalent to
22478 SV* sv = sv_2mortal(newSV_type(<some type>))
22479 and
22480 SV* sv = \fBsv_newmortal()\fR;
22481 sv_upgrade(sv, <some_type>)
22482 but should be more efficient than both of them. (Unless sv_2mortal is inlined
22483 at some point in the future.)
22484 .RS 4
22485 .Sp
22486 .Vb 2
22487 \& SV * newSV_type_mortal( const svtype type)
22488 \& SV * Perl_newSV_type_mortal(pTHX_ const svtype type)
22489 .Ve
22490 .RE
22491 .RS 4
22492 .RE
22493 .ie n .IP """newSVbool""" 4
22494 .el .IP \f(CWnewSVbool\fR 4
22495 .IX Xref "newSVbool"
22496 .IX Item "newSVbool"
22497 Creates a new SV boolean.
22498 .RS 4
22499 .Sp
22500 .Vb 2
22501 \& SV * newSVbool( const bool bool_val)
22502 \& SV * Perl_newSVbool(pTHX_ const bool bool_val)
22503 .Ve
22504 .RE
22505 .RS 4
22506 .RE
22507 .ie n .IP """newSVhek""" 4
22508 .el .IP \f(CWnewSVhek\fR 4
22509 .IX Xref "newSVhek"
22510 .IX Item "newSVhek"
22511 Creates a new SV from the hash key structure. It will generate scalars that
22512 point to the shared string table where possible. Returns a new (undefined)
22513 SV if \f(CW\*(C`hek\*(C'\fR is NULL.
22514 .RS 4
22515 .Sp
22516 .Vb 2
22517 \& SV * newSVhek( const HEK * const hek)
22518 \& SV * Perl_newSVhek(pTHX_ const HEK * const hek)
22519 .Ve
22520 .RE
22521 .RS 4
22522 .RE
22523 .ie n .IP """newSVhek_mortal""" 4
22524 .el .IP \f(CWnewSVhek_mortal\fR 4
22525 .IX Xref "newSVhek_mortal"
22526 .IX Item "newSVhek_mortal"
22527 Creates a new mortal SV from the hash key structure. It will generate
22528 scalars that point to the shared string table where possible. Returns
22529 a new (undefined) SV if \f(CW\*(C`hek\*(C'\fR is NULL.
22530 .Sp
22531 This is more efficient than using sv_2mortal(newSVhek( ... ))
22532 .RS 4
22533 .Sp
22534 .Vb 2
22535 \& SV * newSVhek_mortal( const HEK * const hek)
22536 \& SV * Perl_newSVhek_mortal(pTHX_ const HEK * const hek)
22537 .Ve
22538 .RE
22539 .RS 4
22540 .RE
22541 .ie n .IP """newSViv""" 4
22542 .el .IP \f(CWnewSViv\fR 4
22543 .IX Xref "newSViv"
22544 .IX Item "newSViv"
22545 Creates a new SV and copies an integer into it. The reference count for the
22546 SV is set to 1.
22547 .RS 4
22548 .Sp
22549 .Vb 2
22550 \& SV * newSViv( const IV i)
22551 \& SV * Perl_newSViv(pTHX_ const IV i)
22552 .Ve
22553 .RE
22554 .RS 4
22555 .RE
22556 .ie n .IP """newSVnv""" 4
22557 .el .IP \f(CWnewSVnv\fR 4
22558 .IX Xref "newSVnv"
22559 .IX Item "newSVnv"
22560 Creates a new SV and copies a floating point value into it.
22561 The reference count for the SV is set to 1.
22562 .RS 4
22563 .Sp
22564 .Vb 2
22565 \& SV * newSVnv( const NV n)
22566 \& SV * Perl_newSVnv(pTHX_ const NV n)
22567 .Ve
22568 .RE
22569 .RS 4
22570 .RE
22571 .ie n .IP """newSVpadname""" 4
22572 .el .IP \f(CWnewSVpadname\fR 4
22573 .IX Xref "newSVpadname"
22574 .IX Item "newSVpadname"
22575 NOTE: \f(CW\*(C`newSVpadname\*(C'\fR is \fBexperimental\fR and may change or be
22576 removed without notice.
22577 .Sp
22578 Creates a new SV containing the pad name.
22579 .RS 4
22580 .Sp
22581 .Vb 1
22582 \& SV* newSVpadname(PADNAME *pn)
22583 .Ve
22584 .RE
22585 .RS 4
22586 .RE
22587 .ie n .IP """newSVpv""" 4
22588 .el .IP \f(CWnewSVpv\fR 4
22589 .IX Xref "newSVpv"
22590 .IX Item "newSVpv"
22591 Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
22592 characters) into it. The reference count for the
22593 SV is set to 1. If \f(CW\*(C`len\*(C'\fR is zero, Perl will compute the length using
22594 \&\f(CWstrlen()\fR, (which means if you use this option, that \f(CW\*(C`s\*(C'\fR can\*(Aqt have embedded
22595 \&\f(CW\*(C`NUL\*(C'\fR characters and has to have a terminating \f(CW\*(C`NUL\*(C'\fR byte).
22596 .Sp
22597 This function can cause reliability issues if you are likely to pass in
22598 empty strings that are not null terminated, because it will run
22599 strlen on the string and potentially run past valid memory.
22600 .Sp
22601 Using "newSVpvn" is a safer alternative for non \f(CW\*(C`NUL\*(C'\fR terminated strings.
22602 For string literals use "newSVpvs" instead. This function will work fine for
22603 \&\f(CW\*(C`NUL\*(C'\fR terminated strings, but if you want to avoid the if statement on whether
22604 to call \f(CW\*(C`strlen\*(C'\fR use \f(CW\*(C`newSVpvn\*(C'\fR instead (calling \f(CW\*(C`strlen\*(C'\fR yourself).
22605 .RS 4
22606 .Sp
22607 .Vb 2
22608 \& SV * newSVpv( const char * const s, const STRLEN len)
22609 \& SV * Perl_newSVpv(pTHX_ const char * const s, const STRLEN len)
22610 .Ve
22611 .RE
22612 .RS 4
22613 .RE
22614 .ie n .IP """newSVpv_share""" 4
22615 .el .IP \f(CWnewSVpv_share\fR 4
22616 .IX Xref "newSVpv_share"
22617 .IX Item "newSVpv_share"
22618 Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a \f(CW\*(C`NUL\*(C'\fR\-terminated string instead of a
22619 string/length pair.
22620 .RS 4
22621 .Sp
22622 .Vb 2
22623 \& SV * newSVpv_share( const char *s, U32 hash)
22624 \& SV * Perl_newSVpv_share(pTHX_ const char *s, U32 hash)
22625 .Ve
22626 .RE
22627 .RS 4
22628 .RE
22629 .ie n .IP """newSVpvf""" 4
22630 .el .IP \f(CWnewSVpvf\fR 4
22631 .IX Xref "newSVpvf"
22632 .IX Item "newSVpvf"
22633 Creates a new SV and initializes it with the string formatted like
22634 \&\f(CW\*(C`sv_catpvf\*(C'\fR.
22635 .RS 4
22636 .Sp
22637 .Vb 1
22638 \& SV * Perl_newSVpvf(pTHX_ const char * const pat, ...)
22639 .Ve
22640 .RE
22641 .RS 4
22642 .RE
22643 .ie n .IP """newSVpvf_nocontext""" 4
22644 .el .IP \f(CWnewSVpvf_nocontext\fR 4
22645 .IX Xref "newSVpvf_nocontext"
22646 .IX Item "newSVpvf_nocontext"
22647 Like \f(CW"newSVpvf"\fR but does not take a thread context (\f(CW\*(C`aTHX\*(C'\fR) parameter,
22648 so is used in situations where the caller doesn\*(Aqt already have the thread
22649 context.
22650 .RS 4
22651 .Sp
22652 .Vb 2
22653 \& SV * newSVpvf_nocontext(const char * const pat, ...)
22654 \& SV * Perl_newSVpvf_nocontext(const char * const pat, ...)
22655 .Ve
22656 .RE
22657 .RS 4
22658 .RE
22659 .ie n .IP """newSVpvn""" 4
22660 .el .IP \f(CWnewSVpvn\fR 4
22661 .IX Xref "newSVpvn"
22662 .IX Item "newSVpvn"
22663 Creates a new SV and copies a string into it, which may contain \f(CW\*(C`NUL\*(C'\fR characters
22664 (\f(CW\*(C`\e0\*(C'\fR) and other binary data. The reference count for the SV is set to 1.
22665 Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length (Perl) string. You
22666 are responsible for ensuring that the source buffer is at least
22667 \&\f(CW\*(C`len\*(C'\fR bytes long. If the \f(CW\*(C`buffer\*(C'\fR argument is NULL the new SV will be
22668 undefined.
22669 .RS 4
22670 .Sp
22671 .Vb 2
22672 \& SV * newSVpvn( const char * const s, const STRLEN len)
22673 \& SV * Perl_newSVpvn(pTHX_ const char * const s, const STRLEN len)
22674 .Ve
22675 .RE
22676 .RS 4
22677 .RE
22678 .ie n .IP """newSVpvn_flags""" 4
22679 .el .IP \f(CWnewSVpvn_flags\fR 4
22680 .IX Xref "newSVpvn_flags"
22681 .IX Item "newSVpvn_flags"
22682 Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
22683 characters) into it. The reference count for the
22684 SV is set to 1. Note that if \f(CW\*(C`len\*(C'\fR is zero, Perl will create a zero length
22685 string. You are responsible for ensuring that the source string is at least
22686 \&\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.
22687 Currently the only flag bits accepted are \f(CW\*(C`SVf_UTF8\*(C'\fR and \f(CW\*(C`SVs_TEMP\*(C'\fR.
22688 If \f(CW\*(C`SVs_TEMP\*(C'\fR is set, then \f(CWsv_2mortal()\fR is called on the result before
22689 returning. If \f(CW\*(C`SVf_UTF8\*(C'\fR is set, \f(CW\*(C`s\*(C'\fR
22690 is considered to be in UTF\-8 and the
22691 \&\f(CW\*(C`SVf_UTF8\*(C'\fR flag will be set on the new SV.
22692 \&\f(CWnewSVpvn_utf8()\fR is a convenience wrapper for this function, defined as
22693 .Sp
22694 .Vb 2
22695 \& #define newSVpvn_utf8(s, len, u) \e
22696 \& newSVpvn_flags((s), (len), (u) ? SVf_UTF8 : 0)
22697 .Ve
22698 .RS 4
22699 .Sp
22700 .Vb 6
22701 \& SV * newSVpvn_flags( const char * const s,
22702 \& const STRLEN len,
22703 \& const U32 flags)
22704 \& SV * Perl_newSVpvn_flags(pTHX_ const char * const s,
22705 \& const STRLEN len,
22706 \& const U32 flags)
22707 .Ve
22708 .RE
22709 .RS 4
22710 .RE
22711 .ie n .IP """newSVpvn_share""" 4
22712 .el .IP \f(CWnewSVpvn_share\fR 4
22713 .IX Xref "newSVpvn_share"
22714 .IX Item "newSVpvn_share"
22715 Creates a new SV with its \f(CW\*(C`SvPVX_const\*(C'\fR pointing to a shared string in the string
22716 table. If the string does not already exist in the table, it is
22717 created first. Turns on the \f(CW\*(C`SvIsCOW\*(C'\fR flag (or \f(CW\*(C`READONLY\*(C'\fR
22718 and \f(CW\*(C`FAKE\*(C'\fR in 5.16 and earlier). If the \f(CW\*(C`hash\*(C'\fR parameter
22719 is non\-zero, that value is used; otherwise the hash is computed.
22720 The string\*(Aqs hash can later be retrieved from the SV
22721 with the \f(CW"SvSHARED_HASH"\fR macro. The idea here is
22722 that as the string table is used for shared hash keys these strings will have
22723 \&\f(CW\*(C`SvPVX_const == HeKEY\*(C'\fR and hash lookup will avoid string compare.
22724 .RS 4
22725 .Sp
22726 .Vb 2
22727 \& SV * newSVpvn_share( const char *s, I32 len, U32 hash)
22728 \& SV * Perl_newSVpvn_share(pTHX_ const char *s, I32 len, U32 hash)
22729 .Ve
22730 .RE
22731 .RS 4
22732 .RE
22733 .ie n .IP """newSVpvn_utf8""" 4
22734 .el .IP \f(CWnewSVpvn_utf8\fR 4
22735 .IX Xref "newSVpvn_utf8"
22736 .IX Item "newSVpvn_utf8"
22737 Creates a new SV and copies a string (which may contain \f(CW\*(C`NUL\*(C'\fR (\f(CW\*(C`\e0\*(C'\fR)
22738 characters) into it. If \f(CW\*(C`utf8\*(C'\fR is true, calls
22739 \&\f(CW\*(C`SvUTF8_on\*(C'\fR on the new SV. Implemented as a wrapper around \f(CW\*(C`newSVpvn_flags\*(C'\fR.
22740 .RS 4
22741 .Sp
22742 .Vb 1
22743 \& SV* newSVpvn_utf8(const char* s, STRLEN len, U32 utf8)
22744 .Ve
22745 .RE
22746 .RS 4
22747 .RE
22748 .ie n .IP """newSVpvs""" 4
22749 .el .IP \f(CWnewSVpvs\fR 4
22750 .IX Xref "newSVpvs"
22751 .IX Item "newSVpvs"
22752 Like \f(CW\*(C`newSVpvn\*(C'\fR, but takes a literal string instead of a
22753 string/length pair.
22754 .RS 4
22755 .Sp
22756 .Vb 1
22757 \& SV* newSVpvs("literal string")
22758 .Ve
22759 .RE
22760 .RS 4
22761 .RE
22762 .ie n .IP """newSVpvs_flags""" 4
22763 .el .IP \f(CWnewSVpvs_flags\fR 4
22764 .IX Xref "newSVpvs_flags"
22765 .IX Item "newSVpvs_flags"
22766 Like \f(CW\*(C`newSVpvn_flags\*(C'\fR, but takes a literal string instead of
22767 a string/length pair.
22768 .RS 4
22769 .Sp
22770 .Vb 1
22771 \& SV* newSVpvs_flags("literal string", U32 flags)
22772 .Ve
22773 .RE
22774 .RS 4
22775 .RE
22776 .ie n .IP """newSVpvs_share""" 4
22777 .el .IP \f(CWnewSVpvs_share\fR 4
22778 .IX Xref "newSVpvs_share"
22779 .IX Item "newSVpvs_share"
22780 Like \f(CW\*(C`newSVpvn_share\*(C'\fR, but takes a literal string instead of
22781 a string/length pair and omits the hash parameter.
22782 .RS 4
22783 .Sp
22784 .Vb 1
22785 \& SV* newSVpvs_share("literal string")
22786 .Ve
22787 .RE
22788 .RS 4
22789 .RE
22790 .ie n .IP """newSVpvz""" 4
22791 .el .IP \f(CWnewSVpvz\fR 4
22792 .IX Xref "newSVpvz"
22793 .IX Item "newSVpvz"
22794 Creates a new SV initialized with an empty string, like \f(CWnewSVpvs("")\fR, but
22795 with enough available space to hold a string of \f(CW\*(C`len\*(C'\fR bytes (plus a trailing
22796 NUL) without needing to grow. It differs from \f(CW"newSV"\fR in that the string
22797 is defined and initialized.
22798 .Sp
22799 The reference count for the new SV is set to 1.
22800 .RS 4
22801 .Sp
22802 .Vb 2
22803 \& SV * newSVpvz( const STRLEN len)
22804 \& SV * Perl_newSVpvz(pTHX_ const STRLEN len)
22805 .Ve
22806 .RE
22807 .RS 4
22808 .RE
22809 .ie n .IP """newSVrv""" 4
22810 .el .IP \f(CWnewSVrv\fR 4
22811 .IX Xref "newSVrv"
22812 .IX Item "newSVrv"
22813 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
22814 RV then it will be upgraded to one. If \f(CW\*(C`classname\*(C'\fR is non\-null then the new
22815 SV will be blessed in the specified package. The new SV is returned and its
22816 reference count is 1. The reference count 1 is owned by \f(CW\*(C`rv\*(C'\fR. See also
22817 \&\fBnewRV_inc()\fR and \fBnewRV_noinc()\fR for creating a new RV properly.
22818 .RS 4
22819 .Sp
22820 .Vb 4
22821 \& SV * newSVrv( SV * const rv,
22822 \& const char * const classname)
22823 \& SV * Perl_newSVrv(pTHX_ SV * const rv,
22824 \& const char * const classname)
22825 .Ve
22826 .RE
22827 .RS 4
22828 .RE
22829 .ie n .IP """newSVsv""" 4
22830 .el .IP \f(CWnewSVsv\fR 4
22831 .IX Item "newSVsv"
22832 .PD 0
22833 .ie n .IP """newSVsv_flags""" 4
22834 .el .IP \f(CWnewSVsv_flags\fR 4
22835 .IX Item "newSVsv_flags"
22836 .ie n .IP """newSVsv_nomg""" 4
22837 .el .IP \f(CWnewSVsv_nomg\fR 4
22838 .IX Xref "newSVsv newSVsv_flags newSVsv_nomg"
22839 .IX Item "newSVsv_nomg"
22840 .PD
22841 These create a new SV which is an exact duplicate of the original SV
22842 (using \f(CW\*(C`sv_setsv\*(C'\fR.)
22843 .Sp
22844 They differ only in that \f(CW\*(C`newSVsv\*(C'\fR performs \*(Aqget\*(Aq magic; \f(CW\*(C`newSVsv_nomg\*(C'\fR skips
22845 any magic; and \f(CW\*(C`newSVsv_flags\*(C'\fR allows you to explicitly set a \f(CW\*(C`flags\*(C'\fR
22846 parameter.
22847 .RS 4
22848 .Sp
22849 .Vb 5
22850 \& SV * newSVsv ( SV * const old)
22851 \& SV * Perl_newSVsv (pTHX_ SV * const old)
22852 \& SV * newSVsv_flags( SV * const old, I32 flags)
22853 \& SV * Perl_newSVsv_flags(pTHX_ SV * const old, I32 flags)
22854 \& SV * newSVsv_nomg ( SV * const old)
22855 .Ve
22856 .RE
22857 .RS 4
22858 .RE
22859 .ie n .IP """newSVuv""" 4
22860 .el .IP \f(CWnewSVuv\fR 4
22861 .IX Xref "newSVuv"
22862 .IX Item "newSVuv"
22863 Creates a new SV and copies an unsigned integer into it.
22864 The reference count for the SV is set to 1.
22865 .RS 4
22866 .Sp
22867 .Vb 2
22868 \& SV * newSVuv( const UV u)
22869 \& SV * Perl_newSVuv(pTHX_ const UV u)
22870 .Ve
22871 .RE
22872 .RS 4
22873 .RE
22874 .ie n .IP """Nullsv""" 4
22875 .el .IP \f(CWNullsv\fR 4
22876 .IX Xref "Nullsv"
22877 .IX Item "Nullsv"
22878 Null SV pointer. (No longer available when \f(CW\*(C`PERL_CORE\*(C'\fR is defined.)
22879 .ie n .IP """PL_sv_no""" 4
22880 .el .IP \f(CWPL_sv_no\fR 4
22881 .IX Xref "PL_sv_no"
22882 .IX Item "PL_sv_no"
22883 This is the \f(CW\*(C`false\*(C'\fR SV. It is readonly. See \f(CW"PL_sv_yes"\fR. Always refer
22884 to this as \f(CW&PL_sv_no\fR.
22885 .RS 4
22886 .Sp
22887 .Vb 1
22888 \& SV PL_sv_no
22889 .Ve
22890 .RE
22891 .RS 4
22892 .RE
22893 .ie n .IP """PL_sv_undef""" 4
22894 .el .IP \f(CWPL_sv_undef\fR 4
22895 .IX Xref "PL_sv_undef"
22896 .IX Item "PL_sv_undef"
22897 This is the \f(CW\*(C`undef\*(C'\fR SV. It is readonly. Always refer to this as
22898 \&\f(CW&PL_sv_undef\fR.
22899 .RS 4
22900 .Sp
22901 .Vb 1
22902 \& SV PL_sv_undef
22903 .Ve
22904 .RE
22905 .RS 4
22906 .RE
22907 .ie n .IP """PL_sv_yes""" 4
22908 .el .IP \f(CWPL_sv_yes\fR 4
22909 .IX Xref "PL_sv_yes"
22910 .IX Item "PL_sv_yes"
22911 This is the \f(CW\*(C`true\*(C'\fR SV. It is readonly. See \f(CW"PL_sv_no"\fR. Always refer to
22912 this as \f(CW&PL_sv_yes\fR.
22913 .RS 4
22914 .Sp
22915 .Vb 1
22916 \& SV PL_sv_yes
22917 .Ve
22918 .RE
22919 .RS 4
22920 .RE
22921 .ie n .IP """PL_sv_zero""" 4
22922 .el .IP \f(CWPL_sv_zero\fR 4
22923 .IX Xref "PL_sv_zero"
22924 .IX Item "PL_sv_zero"
22925 This readonly SV has a zero numeric value and a \f(CW"0"\fR string value. It\*(Aqs
22926 similar to \f(CW"PL_sv_no"\fR except for its string value. Can be used as a
22927 cheap alternative to \f(CWmXPUSHi(0)\fR for example. Always refer to this as
22928 \&\f(CW&PL_sv_zero\fR. Introduced in 5.28.
22929 .RS 4
22930 .Sp
22931 .Vb 1
22932 \& SV PL_sv_zero
22933 .Ve
22934 .RE
22935 .RS 4
22936 .RE
22937 .ie n .IP """SAVE_DEFSV""" 4
22938 .el .IP \f(CWSAVE_DEFSV\fR 4
22939 .IX Xref "SAVE_DEFSV"
22940 .IX Item "SAVE_DEFSV"
22941 Localize \f(CW$_\fR. See "Localizing changes" in perlguts.
22942 .RS 4
22943 .Sp
22944 .Vb 1
22945 \& void SAVE_DEFSV
22946 .Ve
22947 .RE
22948 .RS 4
22949 .RE
22950 .ie n .IP """sortsv""" 4
22951 .el .IP \f(CWsortsv\fR 4
22952 .IX Xref "sortsv"
22953 .IX Item "sortsv"
22954 In\-place sort an array of SV pointers with the given comparison routine.
22955 .Sp
22956 Currently this always uses mergesort. See \f(CW"sortsv_flags"\fR for a more
22957 flexible routine.
22958 .RS 4
22959 .Sp
22960 .Vb 4
22961 \& void sortsv( SV **array, size_t num_elts,
22962 \& SVCOMPARE_t cmp)
22963 \& void Perl_sortsv(pTHX_ SV **array, size_t num_elts,
22964 \& SVCOMPARE_t cmp)
22965 .Ve
22966 .RE
22967 .RS 4
22968 .RE
22969 .ie n .IP """sortsv_flags""" 4
22970 .el .IP \f(CWsortsv_flags\fR 4
22971 .IX Xref "sortsv_flags"
22972 .IX Item "sortsv_flags"
22973 In\-place sort an array of SV pointers with the given comparison routine,
22974 with various SORTf_* flag options.
22975 .RS 4
22976 .Sp
22977 .Vb 4
22978 \& void sortsv_flags( SV **array, size_t num_elts,
22979 \& SVCOMPARE_t cmp, U32 flags)
22980 \& void Perl_sortsv_flags(pTHX_ SV **array, size_t num_elts,
22981 \& SVCOMPARE_t cmp, U32 flags)
22982 .Ve
22983 .RE
22984 .RS 4
22985 .RE
22986 .ie n .IP """SV""" 4
22987 .el .IP \f(CWSV\fR 4
22988 .IX Item "SV"
22989 Described in perlguts.
22990 .ie n .IP """sv_backoff""" 4
22991 .el .IP \f(CWsv_backoff\fR 4
22992 .IX Xref "sv_backoff"
22993 .IX Item "sv_backoff"
22994 Remove any string offset. You should normally use the \f(CW\*(C`SvOOK_off\*(C'\fR macro
22995 wrapper instead.
22996 .RS 4
22997 .Sp
22998 .Vb 2
22999 \& void sv_backoff(SV * const sv)
23000 \& void Perl_sv_backoff(SV * const sv)
23001 .Ve
23002 .RE
23003 .RS 4
23004 .RE
23005 .ie n .IP """sv_bless""" 4
23006 .el .IP \f(CWsv_bless\fR 4
23007 .IX Xref "sv_bless"
23008 .IX Item "sv_bless"
23009 Blesses an SV into a specified package. The SV must be an RV. The package
23010 must be designated by its stash (see \f(CW"gv_stashpv"\fR). The reference count
23011 of the SV is unaffected.
23012 .RS 4
23013 .Sp
23014 .Vb 4
23015 \& SV * sv_bless( SV * const sv,
23016 \& NOCHECK HV * const stash)
23017 \& SV * Perl_sv_bless(pTHX_ SV * const sv,
23018 \& NOCHECK HV * const stash)
23019 .Ve
23020 .RE
23021 .RS 4
23022 .RE
23023 .ie n .IP """sv_catpv""" 4
23024 .el .IP \f(CWsv_catpv\fR 4
23025 .IX Item "sv_catpv"
23026 .PD 0
23027 .ie n .IP """sv_catpv_flags""" 4
23028 .el .IP \f(CWsv_catpv_flags\fR 4
23029 .IX Item "sv_catpv_flags"
23030 .ie n .IP """sv_catpv_mg""" 4
23031 .el .IP \f(CWsv_catpv_mg\fR 4
23032 .IX Item "sv_catpv_mg"
23033 .ie n .IP """sv_catpv_nomg""" 4
23034 .el .IP \f(CWsv_catpv_nomg\fR 4
23035 .IX Item "sv_catpv_nomg"
23036 .ie n .IP """sv_catpvn""" 4
23037 .el .IP \f(CWsv_catpvn\fR 4
23038 .IX Item "sv_catpvn"
23039 .ie n .IP """sv_catpvn_flags""" 4
23040 .el .IP \f(CWsv_catpvn_flags\fR 4
23041 .IX Item "sv_catpvn_flags"
23042 .ie n .IP """sv_catpvn_mg""" 4
23043 .el .IP \f(CWsv_catpvn_mg\fR 4
23044 .IX Item "sv_catpvn_mg"
23045 .ie n .IP """sv_catpvn_nomg""" 4
23046 .el .IP \f(CWsv_catpvn_nomg\fR 4
23047 .IX Item "sv_catpvn_nomg"
23048 .ie n .IP """sv_catpvn_nomg_maybeutf8""" 4
23049 .el .IP \f(CWsv_catpvn_nomg_maybeutf8\fR 4
23050 .IX Item "sv_catpvn_nomg_maybeutf8"
23051 .ie n .IP """sv_catpvs""" 4
23052 .el .IP \f(CWsv_catpvs\fR 4
23053 .IX Item "sv_catpvs"
23054 .ie n .IP """sv_catpvs_flags""" 4
23055 .el .IP \f(CWsv_catpvs_flags\fR 4
23056 .IX Item "sv_catpvs_flags"
23057 .ie n .IP """sv_catpvs_mg""" 4
23058 .el .IP \f(CWsv_catpvs_mg\fR 4
23059 .IX Item "sv_catpvs_mg"
23060 .ie n .IP """sv_catpvs_nomg""" 4
23061 .el .IP \f(CWsv_catpvs_nomg\fR 4
23062 .IX Xref "sv_catpv sv_catpv_flags sv_catpv_mg sv_catpv_nomg sv_catpvn sv_catpvn_flags sv_catpvn_mg sv_catpvn_nomg sv_catpvn_nomg_maybeutf8 sv_catpvs sv_catpvs_flags sv_catpvs_mg sv_catpvs_nomg"
23063 .IX Item "sv_catpvs_nomg"
23064 .PD
23065 These each concatenate a string onto the end of the string which is in \f(CW\*(C`dsv\*(C'\fR.
23066 They differ in how the catenated string is specified and in the handling of
23067 magic and UTF\-8ness.
23068 .Sp
23069 In the \f(CW\*(C`pvs\*(C'\fR forms, the catenated string is a C language string literal,
23070 enclosed in double quotes.
23071 .Sp
23072 In the \f(CW\*(C`pvn\*(C'\fR forms, \f(CW\*(C`sstr\*(C'\fR points to the first byte of the string to
23073 concatenate, and an additional parameter, \f(CW\*(C`len\*(C'\fR, specifies the number of
23074 bytes to copy. Hence, \f(CW\*(C`sstr\*(C'\fR may contain embedded\-NUL characters.
23075 The caller must make sure \f(CW\*(C`sstr\*(C'\fR contains at least \f(CW\*(C`len\*(C'\fR bytes.
23076 .Sp
23077 In the plain \f(CW\*(C`pv\*(C'\fR forms, the catenated string is a C language NUL\-terminated
23078 string.
23079 .Sp
23080 The \f(CW\*(C`_mg\*(C'\fR forms perform both \*(Aqget\*(Aq and \*(Aqset\*(Aq magic on \f(CW\*(C`dsv\*(C'\fR.
23081 .Sp
23082 The \f(CW\*(C`_nomg\*(C'\fR forms skip all magic.
23083 .Sp
23084 The other forms perform only \*(Aqget\*(Aq magic.
23085 .Sp
23086 The \f(CW\*(C`_flags\*(C'\fR forms have an extra parameter, \f(CW\*(C`flags\*(C'\fR, which allows you to also
23087 override the UTF\-8 handling. By supplying the \f(CW\*(C`SV_CATBYTES\*(C'\fR flag, the
23088 appended string is interpreted as plain bytes; by supplying instead the
23089 \&\f(CW\*(C`SV_CATUTF8\*(C'\fR flag, it will be interpreted as UTF\-8, and \f(CW\*(C`dsv\*(C'\fR will be
23090 upgraded to UTF\-8 if necessary.
23091 .Sp
23092 \&\f(CW\*(C`sv_catpvn_nomg_maybeutf8\*(C'\fR has an extra boolean parameter, \f(CW\*(C`is_utf8\*(C'\fR, which
23093 if \f(CW\*(C`true\*(C'\fR indicates that \f(CW\*(C`sstr\*(C'\fR is encoded in UTF\-8; otherwise not.
23094 .Sp
23095 For all other forms, the string appended is assumed to be valid UTF\-8
23096 if and only if the \f(CW\*(C`dsv\*(C'\fR has the UTF\-8 status set.
23097 .RS 4
23098 .Sp
23099 .Vb 10
23100 \& void sv_catpv ( SV * const dsv,
23101 \& const char *sstr)
23102 \& void Perl_sv_catpv (pTHX_ SV * const dsv,
23103 \& const char *sstr)
23104 \& void sv_catpv_flags ( SV * const dsv,
23105 \& const char *sstr,
23106 \& const I32 flags)
23107 \& void Perl_sv_catpv_flags (pTHX_ SV * const dsv,
23108 \& const char *sstr,
23109 \& const I32 flags)
23110 \& void sv_catpv_mg ( SV * const dsv,
23111 \& const char * const sstr)
23112 \& void Perl_sv_catpv_mg (pTHX_ SV * const dsv,
23113 \& const char * const sstr)
23114 \& void sv_catpv_nomg ( SV * const dsv,
23115 \& const char * sstr
23116 \&)
23117 \& void sv_catpvn ( SV * const dsv,
23118 \& const char *sstr,
23119 \& STRLEN len)
23120 \& void Perl_sv_catpvn (pTHX_ SV * const dsv,
23121 \& const char *sstr,
23122 \& STRLEN len)
23123 \& void sv_catpvn_flags ( SV * const dsv,
23124 \& const char *sstr,
23125 \& const STRLEN len,
23126 \& const I32 flags)
23127 \& void Perl_sv_catpvn_flags (pTHX_ SV * const dsv,
23128 \& const char *sstr,
23129 \& const STRLEN len,
23130 \& const I32 flags)
23131 \& void sv_catpvn_mg ( SV * const dsv,
23132 \& const char *sstr,
23133 \& STRLEN len)
23134 \& void Perl_sv_catpvn_mg (pTHX_ SV * const dsv,
23135 \& const char *sstr,
23136 \& STRLEN len)
23137 \& void sv_catpvn_nomg ( SV * const dsv,
23138 \& const char * sstr,
23139 \& const STRLEN len
23140 \&)
23141 \& void sv_catpvn_nomg_maybeutf8( SV * const dsv,
23142 \& const char *sstr,
23143 \& const STRLEN len,
23144 \& const I32 flags
23145 \&)
23146 \& void sv_catpvs ( SV * const dsv,
23147 \& "literal string")
23148 \& void sv_catpvs_flags ( SV * const dsv,
23149 \& "literal string",
23150 \& I32 flags)
23151 \& void sv_catpvs_mg ( SV * const dsv,
23152 \& "literal string")
23153 \& void sv_catpvs_nomg ( SV * const dsv,
23154 \& "literal string")
23155 .Ve
23156 .RE
23157 .RS 4
23158 .RE
23159 .ie n .IP """sv_catpvf""" 4
23160 .el .IP \f(CWsv_catpvf\fR 4
23161 .IX Item "sv_catpvf"
23162 .PD 0
23163 .ie n .IP """sv_catpvf_nocontext""" 4
23164 .el .IP \f(CWsv_catpvf_nocontext\fR 4
23165 .IX Item "sv_catpvf_nocontext"
23166 .ie n .IP """sv_catpvf_mg""" 4
23167 .el .IP \f(CWsv_catpvf_mg\fR 4
23168 .IX Item "sv_catpvf_mg"
23169 .ie n .IP """sv_catpvf_mg_nocontext""" 4
23170 .el .IP \f(CWsv_catpvf_mg_nocontext\fR 4
23171 .IX Item "sv_catpvf_mg_nocontext"
23172 .ie n .IP """sv_vcatpvf""" 4
23173 .el .IP \f(CWsv_vcatpvf\fR 4
23174 .IX Item "sv_vcatpvf"
23175 .ie n .IP """sv_vcatpvf_mg""" 4
23176 .el .IP \f(CWsv_vcatpvf_mg\fR 4
23177 .IX Item "sv_vcatpvf_mg"
23178 .ie n .IP """sv_vcatpvfn""" 4
23179 .el .IP \f(CWsv_vcatpvfn\fR 4
23180 .IX Item "sv_vcatpvfn"
23181 .ie n .IP """sv_vcatpvfn_flags""" 4
23182 .el .IP \f(CWsv_vcatpvfn_flags\fR 4
23183 .IX Xref "sv_catpvf sv_catpvf_mg sv_catpvf_mg_nocontext sv_catpvf_nocontext sv_vcatpvf sv_vcatpvf_mg sv_vcatpvfn sv_vcatpvfn_flags"
23184 .IX Item "sv_vcatpvfn_flags"
23185 .PD
23186 These each append to \f(CW\*(C`sv\*(C'\fR the result of formatting their arguments using
23187 \&\f(CW\*(C`pat\*(C'\fR as the \f(CW\*(C`sprintf\*(C'\fR\-like pattern. They assume that \f(CW\*(C`pat\*(C'\fR has the same
23188 UTF8ness as \f(CW\*(C`sv\*(C'\fR. It\*(Aqs the caller\*(Aqs responsibility to ensure that this is
23189 so.
23190 .Sp
23191 If the destination \f(CW\*(C`sv\*(C'\fR isn\*(Aqt already in UTF\-8, but the appended data contains
23192 "wide" characters, \f(CW\*(C`sv\*(C'\fR will be converted to be UTF\-8. An example is the
23193 \&\f(CW%c\fR format with the code point > 255. (This is an enhancement to what libc
23194 \&\f(CW\*(C`sprintf\*(C'\fR would do in this situation.) Other examples are given below.
23195 .Sp
23196 The forms differ in how their arguments are specified and in the handling of
23197 magic.
23198 .Sp
23199 \&\f(CW\*(C`sv_vcatpvfn_flags\*(C'\fR is the most general, and all the other forms are
23200 implemented by eventually calling it.
23201 .Sp
23202 It has two sets of argument lists, only one of which is used in any given call.
23203 The first set, \f(CW\*(C`args\*(C'\fR, is an encapsulated argument list of pointers to C
23204 strings. If it is NULL, the other list, \f(CW\*(C`svargs\*(C'\fR, is used; it is an array
23205 of pointers to SV\*(Aqs. \f(CW\*(C`sv_count\*(C'\fR gives how many there are in the list.
23206 .Sp
23207 See \f(CWsprintf(3)\fR for details on how the formatting is done. Some
23208 platforms support extensions to the standard C99 definition of this function.
23209 None of those are supported by Perl. For example, neither \f(CW\*(C`\*(Aq\*(C'\fR (to get digit
23210 grouping), nor \f(CW\*(C`I\*(C'\fR (to get alternate digits) are supported.
23211 .Sp
23212 Also, argument reordering (using format specifiers like \f(CW\*(C`%2$d\*(C'\fR or \f(CW\*(C`%*2$d\*(C'\fR) is
23213 supported only when using the \f(CW\*(C`svargs\*(C'\fR array of SVs; an exception is raised if
23214 \&\f(CW\*(C`arg\*(C'\fR is not NULL and \f(CW\*(C`pat\*(C'\fR contains the \f(CW\*(C`$\*(C'\fR reordering specifier.
23215 .Sp
23216 \&\f(CW\*(C`*\ maybe_tainted\*(C'\fR is supposed to be set when running with taint checks
23217 enabled if the results are untrustworthy (often due to the use of locales).
23218 However, this is not currently implemented. This argument is not used.
23219 .Sp
23220 \&\f(CW\*(C`patlen\*(C'\fR gives the length in bytes of \f(CW\*(C`pat\*(C'\fR. Currently, the pattern must be
23221 NUL\-terminated anyway.
23222 .Sp
23223 \&\f(CW\*(C`flags\*(C'\fR is used to specify which magic to handle or to skip, by setting or
23224 clearing the \f(CW\*(C`SV_GMAGIC\*(C'\fR and/or SV_SMAGIC flags.
23225 .Sp
23226 Plain \f(CW\*(C`sv_vcatpvfn\*(C'\fR just calls \f(CW\*(C`sv_vcatpvfn_flags\*(C'\fR setting both the
23227 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR and SV_SMAGIC flags, so it always handles both set and get
23228 magic.
23229 .Sp
23230 All the remaining forms handle \*(Aqget\*(Aq magic; the forms whose name contains
23231 \&\f(CW\*(C`_mg\*(C'\fR additionally handle \*(Aqset\*(Aq magic.
23232 .Sp
23233 When using the \f(CW\*(C`svargs\*(C'\fR array, if any of the SVs in it have their UTF\-8 flag
23234 set, \f(CW\*(C`sv\*(C'\fR will be converted to be so too, as necessary.
23235 .Sp
23236 None of the remaining forms use the \f(CW\*(C`svargs\*(C'\fR array, meaning argument
23237 reordering is not possible with them. The arguments are generally considered
23238 to be the same UTF8ness as the destination \f(CW\*(C`sv\*(C'\fR, though certain Perl
23239 extensions to the standard set of \f(CW%formats\fR can override this (see
23240 "Formatted Printing of Strings" in perlguts and adjacent sections).
23241 .Sp
23242 The forms whose name contains \f(CW\*(C`_no_context\*(C'\fR do not take a thread
23243 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller
23244 doesn\*(Aqt already have the thread context.
23245 .Sp
23246 The forms whose name contains \f(CW\*(C`vcat\*(C'\fR use an encapsulated argument list, the
23247 other forms use \f(CW\*(C`sprintf\*(C'\fR\-style arguments.
23248 .Sp
23249 There are no other differences between the forms.
23250 .RS 4
23251 .Sp
23252 .Vb 10
23253 \& void Perl_sv_catpvf (pTHX_ SV * const sv,
23254 \& const char * const pat,
23255 \& ...)
23256 \& void sv_catpvf_nocontext ( SV * const sv,
23257 \& const char * const pat,
23258 \& ...)
23259 \& void Perl_sv_catpvf_nocontext ( SV * const sv,
23260 \& const char * const pat,
23261 \& ...)
23262 \& void Perl_sv_catpvf_mg (pTHX_ SV * const sv,
23263 \& const char * const pat,
23264 \& ...)
23265 \& void sv_catpvf_mg_nocontext( SV * const sv,
23266 \& const char * const pat,
23267 \& ...)
23268 \& void Perl_sv_catpvf_mg_nocontext( SV * const sv,
23269 \& const char * const pat,
23270 \& ...)
23271 \& void sv_vcatpvf ( SV * const sv,
23272 \& const char * const pat,
23273 \& va_list * const args)
23274 \& void Perl_sv_vcatpvf (pTHX_ SV * const sv,
23275 \& const char * const pat,
23276 \& va_list * const args)
23277 \& void sv_vcatpvf_mg ( SV * const sv,
23278 \& const char * const pat,
23279 \& va_list * const args)
23280 \& void Perl_sv_vcatpvf_mg (pTHX_ SV * const sv,
23281 \& const char * const pat,
23282 \& va_list * const args)
23283 \& void sv_vcatpvfn ( SV * const sv,
23284 \& const char * const pat,
23285 \& const STRLEN patlen,
23286 \& va_list * const args,
23287 \& SV ** const svargs,
23288 \& const Size_t sv_count,
23289 \& bool * const maybe_tainted)
23290 \& void Perl_sv_vcatpvfn (pTHX_ SV * const sv,
23291 \& const char * const pat,
23292 \& const STRLEN patlen,
23293 \& va_list * const args,
23294 \& SV ** const svargs,
23295 \& const Size_t sv_count,
23296 \& bool * const maybe_tainted)
23297 \& void sv_vcatpvfn_flags ( SV * const sv,
23298 \& const char * const pat,
23299 \& const STRLEN patlen,
23300 \& va_list * const args,
23301 \& SV ** const svargs,
23302 \& const Size_t sv_count,
23303 \& bool * const maybe_tainted,
23304 \& const U32 flags)
23305 \& void Perl_sv_vcatpvfn_flags (pTHX_ SV * const sv,
23306 \& const char * const pat,
23307 \& const STRLEN patlen,
23308 \& va_list * const args,
23309 \& SV ** const svargs,
23310 \& const Size_t sv_count,
23311 \& bool * const maybe_tainted,
23312 \& const U32 flags)
23313 .Ve
23314 .RE
23315 .RS 4
23316 .RE
23317 .ie n .IP """sv_catpvn*""" 4
23318 .el .IP \f(CWsv_catpvn*\fR 4
23319 .IX Item "sv_catpvn*"
23320 .PD 0
23321 .ie n .IP """sv_catpvn_flags*""" 4
23322 .el .IP \f(CWsv_catpvn_flags*\fR 4
23323 .IX Item "sv_catpvn_flags*"
23324 .ie n .IP """sv_catpvn_mg*""" 4
23325 .el .IP \f(CWsv_catpvn_mg*\fR 4
23326 .IX Item "sv_catpvn_mg*"
23327 .ie n .IP """sv_catpvn_nomg*""" 4
23328 .el .IP \f(CWsv_catpvn_nomg*\fR 4
23329 .IX Item "sv_catpvn_nomg*"
23330 .ie n .IP """sv_catpvn_nomg_maybeutf8*""" 4
23331 .el .IP \f(CWsv_catpvn_nomg_maybeutf8*\fR 4
23332 .IX Item "sv_catpvn_nomg_maybeutf8*"
23333 .ie n .IP """sv_catpvs*""" 4
23334 .el .IP \f(CWsv_catpvs*\fR 4
23335 .IX Item "sv_catpvs*"
23336 .ie n .IP """sv_catpvs_flags*""" 4
23337 .el .IP \f(CWsv_catpvs_flags*\fR 4
23338 .IX Item "sv_catpvs_flags*"
23339 .ie n .IP """sv_catpvs_mg*""" 4
23340 .el .IP \f(CWsv_catpvs_mg*\fR 4
23341 .IX Item "sv_catpvs_mg*"
23342 .ie n .IP """sv_catpvs_nomg*""" 4
23343 .el .IP \f(CWsv_catpvs_nomg*\fR 4
23344 .IX Item "sv_catpvs_nomg*"
23345 .PD
23346 Described under \f(CW"sv_catpv"\fR
23347 .ie n .IP """sv_catsv""" 4
23348 .el .IP \f(CWsv_catsv\fR 4
23349 .IX Item "sv_catsv"
23350 .PD 0
23351 .ie n .IP """sv_catsv_flags""" 4
23352 .el .IP \f(CWsv_catsv_flags\fR 4
23353 .IX Item "sv_catsv_flags"
23354 .ie n .IP """sv_catsv_mg""" 4
23355 .el .IP \f(CWsv_catsv_mg\fR 4
23356 .IX Item "sv_catsv_mg"
23357 .ie n .IP """sv_catsv_nomg""" 4
23358 .el .IP \f(CWsv_catsv_nomg\fR 4
23359 .IX Xref "sv_catsv sv_catsv_flags sv_catsv_mg sv_catsv_nomg"
23360 .IX Item "sv_catsv_nomg"
23361 .PD
23362 These concatenate the string from SV \f(CW\*(C`sstr\*(C'\fR onto the end of the string in SV
23363 \&\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
23364 modified.
23365 .Sp
23366 They differ only in what magic they perform:
23367 .Sp
23368 \&\f(CW\*(C`sv_catsv_mg\*(C'\fR performs \*(Aqget\*(Aq magic on both SVs before the copy, and \*(Aqset\*(Aq magic
23369 on \f(CW\*(C`dsv\*(C'\fR afterwards.
23370 .Sp
23371 \&\f(CW\*(C`sv_catsv\*(C'\fR performs just \*(Aqget\*(Aq magic, on both SVs.
23372 .Sp
23373 \&\f(CW\*(C`sv_catsv_nomg\*(C'\fR skips all magic.
23374 .Sp
23375 \&\f(CW\*(C`sv_catsv_flags\*(C'\fR has an extra \f(CW\*(C`flags\*(C'\fR parameter which allows you to use
23376 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR and/or \f(CW\*(C`SV_SMAGIC\*(C'\fR to specify any combination of magic handling
23377 (although either both or neither SV will have \*(Aqget\*(Aq magic applied to it.)
23378 .Sp
23379 \&\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
23380 in terms of \f(CW\*(C`sv_catsv_flags\*(C'\fR.
23381 .RS 4
23382 .Sp
23383 .Vb 9
23384 \& void sv_catsv ( SV * const dsv, SV * const sstr)
23385 \& void Perl_sv_catsv (pTHX_ SV * const dsv, SV * const sstr)
23386 \& void sv_catsv_flags( SV * const dsv, SV * const sstr,
23387 \& const I32 flags)
23388 \& void Perl_sv_catsv_flags(pTHX_ SV * const dsv, SV * const sstr,
23389 \& const I32 flags)
23390 \& void sv_catsv_mg ( SV * const dsv, SV * const sstr)
23391 \& void Perl_sv_catsv_mg (pTHX_ SV * const dsv, SV * const sstr)
23392 \& void sv_catsv_nomg ( SV * const dsv, SV * const sstr)
23393 .Ve
23394 .RE
23395 .RS 4
23396 .RE
23397 .ie n .IP """SV_CHECK_THINKFIRST""" 4
23398 .el .IP \f(CWSV_CHECK_THINKFIRST\fR 4
23399 .IX Xref "SV_CHECK_THINKFIRST"
23400 .IX Item "SV_CHECK_THINKFIRST"
23401 Remove any encumbrances from \f(CW\*(C`sv\*(C'\fR, that need to be taken care of before it
23402 is modifiable. For example if it is Copy on Write (COW), now is the time to
23403 make that copy.
23404 .Sp
23405 If you know that you are about to change the PV value of \f(CW\*(C`sv\*(C'\fR, instead use
23406 "\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" to avoid the write that would be
23407 immediately written again.
23408 .RS 4
23409 .Sp
23410 .Vb 1
23411 \& void SV_CHECK_THINKFIRST(SV * sv)
23412 .Ve
23413 .RE
23414 .RS 4
23415 .RE
23416 .ie n .IP """SV_CHECK_THINKFIRST_COW_DROP""" 4
23417 .el .IP \f(CWSV_CHECK_THINKFIRST_COW_DROP\fR 4
23418 .IX Xref "SV_CHECK_THINKFIRST_COW_DROP"
23419 .IX Item "SV_CHECK_THINKFIRST_COW_DROP"
23420 Call this when you are about to replace the PV value in \f(CW\*(C`sv\*(C'\fR, which is
23421 potentially copy\-on\-write. It stops any sharing with other SVs, so that no
23422 Copy on Write (COW) actually happens. This COW would be useless, as it would
23423 immediately get changed to something else. This function also removes any
23424 other encumbrances that would be problematic when changing \f(CW\*(C`sv\*(C'\fR.
23425 .RS 4
23426 .Sp
23427 .Vb 1
23428 \& void SV_CHECK_THINKFIRST_COW_DROP(SV * sv)
23429 .Ve
23430 .RE
23431 .RS 4
23432 .RE
23433 .ie n .IP """sv_chop""" 4
23434 .el .IP \f(CWsv_chop\fR 4
23435 .IX Xref "sv_chop"
23436 .IX Item "sv_chop"
23437 Efficient removal of characters from the beginning of the string buffer.
23438 \&\f(CWSvPOK(sv)\fR, or at least \f(CWSvPOKp(sv)\fR, must be true and \f(CW\*(C`ptr\*(C'\fR must be a
23439 pointer to somewhere inside the string buffer. \f(CW\*(C`ptr\*(C'\fR becomes the first
23440 character of the adjusted string. Uses the \f(CW\*(C`OOK\*(C'\fR hack. On return, only
23441 \&\f(CWSvPOK(sv)\fR and \f(CWSvPOKp(sv)\fR among the \f(CW\*(C`OK\*(C'\fR flags will be true.
23442 .Sp
23443 Beware: after this function returns, \f(CW\*(C`ptr\*(C'\fR and SvPVX_const(sv) may no longer
23444 refer to the same chunk of data.
23445 .Sp
23446 The unfortunate similarity of this function\*(Aqs name to that of Perl\*(Aqs \f(CW\*(C`chop\*(C'\fR
23447 operator is strictly coincidental. This function works from the left;
23448 \&\f(CW\*(C`chop\*(C'\fR works from the right.
23449 .RS 4
23450 .Sp
23451 .Vb 2
23452 \& void sv_chop( SV * const sv, const char * const ptr)
23453 \& void Perl_sv_chop(pTHX_ SV * const sv, const char * const ptr)
23454 .Ve
23455 .RE
23456 .RS 4
23457 .RE
23458 .ie n .IP """sv_clear""" 4
23459 .el .IP \f(CWsv_clear\fR 4
23460 .IX Xref "sv_clear"
23461 .IX Item "sv_clear"
23462 Clear an SV: call any destructors, free up any memory used by the body,
23463 and free the body itself. The SV\*(Aqs head is \fInot\fR freed, although
23464 its type is set to all 1\*(Aqs so that it won\*(Aqt inadvertently be assumed
23465 to be live during global destruction etc.
23466 This function should only be called when \f(CW\*(C`REFCNT\*(C'\fR is zero. Most of the time
23467 you\*(Aqll want to call \f(CW\*(C`SvREFCNT_dec\*(C'\fR instead.
23468 .RS 4
23469 .Sp
23470 .Vb 2
23471 \& void sv_clear( SV * const orig_sv)
23472 \& void Perl_sv_clear(pTHX_ SV * const orig_sv)
23473 .Ve
23474 .RE
23475 .RS 4
23476 .RE
23477 .ie n .IP """sv_cmp""" 4
23478 .el .IP \f(CWsv_cmp\fR 4
23479 .IX Item "sv_cmp"
23480 .PD 0
23481 .ie n .IP """sv_cmp_flags""" 4
23482 .el .IP \f(CWsv_cmp_flags\fR 4
23483 .IX Xref "sv_cmp sv_cmp_flags"
23484 .IX Item "sv_cmp_flags"
23485 .PD
23486 These each compare the strings in two SVs, returning \-1, 0, or 1 indicating
23487 whether the string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or greater than the string
23488 in \f(CW\*(C`sv2\*(C'\fR. They are UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware, and will coerce their
23489 arguments to strings if necessary.
23490 .Sp
23491 \&\f(CW\*(C`sv_cmp\*(C'\fR always handles \*(Aqget\*(Aq magic.
23492 \&\f(CW\*(C`sv_cmp_flags\*(C'\fR only does so if \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`SV_GMAGIC\*(C'\fR.
23493 Otherwise, the two forms behave identically.
23494 .Sp
23495 See also \f(CW"sv_cmp_locale"\fR.
23496 .RS 4
23497 .Sp
23498 .Vb 6
23499 \& I32 sv_cmp ( SV * const sv1, SV * const sv2)
23500 \& I32 Perl_sv_cmp (pTHX_ SV * const sv1, SV * const sv2)
23501 \& I32 sv_cmp_flags( SV * const sv1, SV * const sv2,
23502 \& const U32 flags)
23503 \& I32 Perl_sv_cmp_flags(pTHX_ SV * const sv1, SV * const sv2,
23504 \& const U32 flags)
23505 .Ve
23506 .RE
23507 .RS 4
23508 .RE
23509 .ie n .IP """sv_cmp_locale""" 4
23510 .el .IP \f(CWsv_cmp_locale\fR 4
23511 .IX Item "sv_cmp_locale"
23512 .PD 0
23513 .ie n .IP """sv_cmp_locale_flags""" 4
23514 .el .IP \f(CWsv_cmp_locale_flags\fR 4
23515 .IX Xref "sv_cmp_locale sv_cmp_locale_flags"
23516 .IX Item "sv_cmp_locale_flags"
23517 .PD
23518 These each compare the strings in two SVs in a locale\-aware manner, returning
23519 \&\-1, 0, or 1 indicating whether the string in \f(CW\*(C`sv1\*(C'\fR is less than, equal to, or
23520 greater than the string in \f(CW\*(C`sv2\*(C'\fR.
23521 .Sp
23522 They are UTF\-8 and \f(CW\*(Aquse\ bytes\*(Aq\fR aware, and will coerce their args to
23523 strings if necessary.
23524 .Sp
23525 \&\f(CW\*(C`sv_cmp_locale\*(C'\fR always handles \*(Aqget\*(Aq magic.
23526 \&\f(CW\*(C`sv_cmp_locale_flags\*(C'\fR only does so if \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`SV_GMAGIC\*(C'\fR.
23527 Otherwise, the two forms behave identically.
23528 .Sp
23529 See also \f(CW"sv_cmp"\fR.
23530 .RS 4
23531 .Sp
23532 .Vb 10
23533 \& I32 sv_cmp_locale ( SV * const sv1,
23534 \& SV * const sv2)
23535 \& I32 Perl_sv_cmp_locale (pTHX_ SV * const sv1,
23536 \& SV * const sv2)
23537 \& I32 sv_cmp_locale_flags( SV * const sv1,
23538 \& SV * const sv2,
23539 \& const U32 flags)
23540 \& I32 Perl_sv_cmp_locale_flags(pTHX_ SV * const sv1,
23541 \& SV * const sv2,
23542 \& const U32 flags)
23543 .Ve
23544 .RE
23545 .RS 4
23546 .RE
23547 .ie n .IP """sv_collxfrm""" 4
23548 .el .IP \f(CWsv_collxfrm\fR 4
23549 .IX Item "sv_collxfrm"
23550 .PD 0
23551 .ie n .IP """sv_collxfrm_flags""" 4
23552 .el .IP \f(CWsv_collxfrm_flags\fR 4
23553 .IX Xref "sv_collxfrm sv_collxfrm_flags"
23554 .IX Item "sv_collxfrm_flags"
23555 .PD
23556 These each add Collate Transform magic to an SV if it doesn\*(Aqt already have it.
23557 .Sp
23558 Any scalar variable may carry \f(CW\*(C`PERL_MAGIC_collxfrm\*(C'\fR magic that contains the
23559 scalar data of the variable, but transformed to such a format that a normal
23560 memory comparison can be used to compare the data according to the locale
23561 settings.
23562 .Sp
23563 \&\f(CW\*(C`sv_collxfrm\*(C'\fR always handles \*(Aqget\*(Aq magic.
23564 \&\f(CW\*(C`sv_collxfrm_flags\*(C'\fR only does so if \f(CW\*(C`flags\*(C'\fR contains \f(CW\*(C`SV_GMAGIC\*(C'\fR.
23565 Otherwise, the two forms behave identically.
23566 .RS 4
23567 .Sp
23568 .Vb 10
23569 \& char * sv_collxfrm ( SV * const sv,
23570 \& STRLEN * const nxp)
23571 \& char * Perl_sv_collxfrm (pTHX_ SV * const sv,
23572 \& STRLEN * const nxp)
23573 \& char * sv_collxfrm_flags( SV * const sv,
23574 \& STRLEN * const nxp,
23575 \& I32 const flags)
23576 \& char * Perl_sv_collxfrm_flags(pTHX_ SV * const sv,
23577 \& STRLEN * const nxp,
23578 \& I32 const flags)
23579 .Ve
23580 .RE
23581 .RS 4
23582 .RE
23583 .ie n .IP """sv_copypv""" 4
23584 .el .IP \f(CWsv_copypv\fR 4
23585 .IX Item "sv_copypv"
23586 .PD 0
23587 .ie n .IP """sv_copypv_flags""" 4
23588 .el .IP \f(CWsv_copypv_flags\fR 4
23589 .IX Item "sv_copypv_flags"
23590 .ie n .IP """sv_copypv_nomg""" 4
23591 .el .IP \f(CWsv_copypv_nomg\fR 4
23592 .IX Xref "sv_copypv sv_copypv_flags sv_copypv_nomg"
23593 .IX Item "sv_copypv_nomg"
23594 .PD
23595 These copy a stringified representation of the source SV into the
23596 destination SV. They automatically perform coercion of numeric values into
23597 strings. Guaranteed to preserve the \f(CW\*(C`UTF8\*(C'\fR flag even from overloaded objects.
23598 Similar in nature to \f(CW\*(C`sv_2pv[_flags]\*(C'\fR but they operate directly on an SV
23599 instead of just the string. Mostly they use "\f(CW\*(C`sv_2pv_flags\*(C'\fR" to
23600 do the work, except when that would lose the UTF\-8\*(Aqness of the PV.
23601 .Sp
23602 The three forms differ only in whether or not they perform \*(Aqget magic\*(Aq on
23603 \&\f(CW\*(C`sv\*(C'\fR. \f(CW\*(C`sv_copypv_nomg\*(C'\fR skips \*(Aqget magic\*(Aq; \f(CW\*(C`sv_copypv\*(C'\fR performs it; and
23604 \&\f(CW\*(C`sv_copypv_flags\*(C'\fR either performs it (if the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit is set in
23605 \&\f(CW\*(C`flags\*(C'\fR) or doesn\*(Aqt (if that bit is cleared).
23606 .RS 4
23607 .Sp
23608 .Vb 7
23609 \& void sv_copypv ( SV * const dsv, SV * const ssv)
23610 \& void Perl_sv_copypv (pTHX_ SV * const dsv, SV * const ssv)
23611 \& void sv_copypv_flags( SV * const dsv, SV * const ssv,
23612 \& const I32 flags)
23613 \& void Perl_sv_copypv_flags(pTHX_ SV * const dsv, SV * const ssv,
23614 \& const I32 flags)
23615 \& void sv_copypv_nomg ( SV * const dsv, SV * const ssv)
23616 .Ve
23617 .RE
23618 .RS 4
23619 .RE
23620 .ie n .IP """sv_dec""" 4
23621 .el .IP \f(CWsv_dec\fR 4
23622 .IX Item "sv_dec"
23623 .PD 0
23624 .ie n .IP """sv_dec_nomg""" 4
23625 .el .IP \f(CWsv_dec_nomg\fR 4
23626 .IX Xref "sv_dec sv_dec_nomg"
23627 .IX Item "sv_dec_nomg"
23628 .PD
23629 These auto\-decrement the value in the SV, doing string to numeric conversion
23630 if necessary. They both handle operator overloading.
23631 .Sp
23632 They differ only in that:
23633 .Sp
23634 \&\f(CW\*(C`sv_dec\*(C'\fR handles \*(Aqget\*(Aq magic; \f(CW\*(C`sv_dec_nomg\*(C'\fR skips \*(Aqget\*(Aq magic.
23635 .RS 4
23636 .Sp
23637 .Vb 4
23638 \& void sv_dec ( SV * const sv)
23639 \& void Perl_sv_dec (pTHX_ SV * const sv)
23640 \& void sv_dec_nomg( SV * const sv)
23641 \& void Perl_sv_dec_nomg(pTHX_ SV * const sv)
23642 .Ve
23643 .RE
23644 .RS 4
23645 .RE
23646 .ie n .IP """sv_derived_from""" 4
23647 .el .IP \f(CWsv_derived_from\fR 4
23648 .IX Item "sv_derived_from"
23649 .PD 0
23650 .ie n .IP """sv_derived_from_hv""" 4
23651 .el .IP \f(CWsv_derived_from_hv\fR 4
23652 .IX Item "sv_derived_from_hv"
23653 .ie n .IP """sv_derived_from_pv""" 4
23654 .el .IP \f(CWsv_derived_from_pv\fR 4
23655 .IX Item "sv_derived_from_pv"
23656 .ie n .IP """sv_derived_from_pvn""" 4
23657 .el .IP \f(CWsv_derived_from_pvn\fR 4
23658 .IX Item "sv_derived_from_pvn"
23659 .ie n .IP """sv_derived_from_sv""" 4
23660 .el .IP \f(CWsv_derived_from_sv\fR 4
23661 .IX Xref "sv_derived_from sv_derived_from_hv sv_derived_from_pv sv_derived_from_pvn sv_derived_from_sv"
23662 .IX Item "sv_derived_from_sv"
23663 .PD
23664 These each return a boolean indicating whether \f(CW\*(C`sv\*(C'\fR is derived from the
23665 specified class \fIat the C level\fR. To check derivation at the Perl level, call
23666 \&\f(CWisa()\fR as a normal Perl method.
23667 .Sp
23668 In \f(CW\*(C`sv_derived_from_hv\*(C'\fR, the class name is \f(CWHvNAME(hv)\fR (which would
23669 presumably represent a stash). Its UTF8ness is \f(CWHvNAMEUTF8(hv)\fR.
23670 .Sp
23671 In \f(CW\*(C`sv_derived_from\*(C'\fR and \f(CW\*(C`sv_derived_from_pv\*(C'\fR, the class name is given by
23672 \&\f(CW\*(C`name\*(C'\fR, which is a NUL\-terminated C string. In \f(CW\*(C`sv_derived_from\*(C'\fR, the name
23673 is never considered to be encoded as UTF\-8.
23674 .Sp
23675 The remaining forms differ only in how the class name is specified;
23676 they all have a \f(CW\*(C`flags\*(C'\fR parameter. Currently, the only significant value for
23677 which is \f(CW\*(C`SVf_UTF8\*(C'\fR to indicate that the class name is encoded as such.
23678 .Sp
23679 In \f(CW\*(C`sv_derived_from_sv\*(C'\fR, the class name is extracted from \f(CW\*(C`namesv\*(C'\fR.
23680 This is the preferred form. The class name is considered to be in UTF\-8 if
23681 \&\f(CW\*(C`namesv\*(C'\fR is marked as such.
23682 .Sp
23683 In \f(CW\*(C`sv_derived_from_pvn\*(C'\fR, \f(CW\*(C`len\*(C'\fR gives the length of \f(CW\*(C`name\*(C'\fR, so the latter
23684 may contain embedded NUL characters.
23685 .RS 4
23686 .Sp
23687 .Vb 10
23688 \& bool sv_derived_from ( SV *sv,
23689 \& const char * const name)
23690 \& bool Perl_sv_derived_from (pTHX_ SV *sv,
23691 \& const char * const name)
23692 \& bool sv_derived_from_hv ( SV *sv, HV *hv)
23693 \& bool Perl_sv_derived_from_hv (pTHX_ SV *sv, HV *hv)
23694 \& bool sv_derived_from_pv ( SV *sv,
23695 \& const char * const name,
23696 \& U32 flags)
23697 \& bool Perl_sv_derived_from_pv (pTHX_ SV *sv,
23698 \& const char * const name,
23699 \& U32 flags)
23700 \& bool sv_derived_from_pvn( SV *sv,
23701 \& const char * const name,
23702 \& const STRLEN len, U32 flags)
23703 \& bool Perl_sv_derived_from_pvn(pTHX_ SV *sv,
23704 \& const char * const name,
23705 \& const STRLEN len, U32 flags)
23706 \& bool sv_derived_from_sv ( SV *sv, SV *namesv,
23707 \& U32 flags)
23708 \& bool Perl_sv_derived_from_sv (pTHX_ SV *sv, SV *namesv,
23709 \& U32 flags)
23710 .Ve
23711 .RE
23712 .RS 4
23713 .RE
23714 .ie n .IP """sv_does""" 4
23715 .el .IP \f(CWsv_does\fR 4
23716 .IX Xref "sv_does"
23717 .IX Item "sv_does"
23718 Like "sv_does_pv", but doesn\*(Aqt take a \f(CW\*(C`flags\*(C'\fR parameter.
23719 .RS 4
23720 .Sp
23721 .Vb 2
23722 \& bool sv_does( SV *sv, const char * const name)
23723 \& bool Perl_sv_does(pTHX_ SV *sv, const char * const name)
23724 .Ve
23725 .RE
23726 .RS 4
23727 .RE
23728 .ie n .IP """sv_does_pv""" 4
23729 .el .IP \f(CWsv_does_pv\fR 4
23730 .IX Xref "sv_does_pv"
23731 .IX Item "sv_does_pv"
23732 Like "sv_does_sv", but takes a nul\-terminated string instead of an SV.
23733 .RS 4
23734 .Sp
23735 .Vb 4
23736 \& bool sv_does_pv( SV *sv, const char * const name,
23737 \& U32 flags)
23738 \& bool Perl_sv_does_pv(pTHX_ SV *sv, const char * const name,
23739 \& U32 flags)
23740 .Ve
23741 .RE
23742 .RS 4
23743 .RE
23744 .ie n .IP """sv_does_pvn""" 4
23745 .el .IP \f(CWsv_does_pvn\fR 4
23746 .IX Xref "sv_does_pvn"
23747 .IX Item "sv_does_pvn"
23748 Like "sv_does_sv", but takes a string/length pair instead of an SV.
23749 .RS 4
23750 .Sp
23751 .Vb 4
23752 \& bool sv_does_pvn( SV *sv, const char * const name,
23753 \& const STRLEN len, U32 flags)
23754 \& bool Perl_sv_does_pvn(pTHX_ SV *sv, const char * const name,
23755 \& const STRLEN len, U32 flags)
23756 .Ve
23757 .RE
23758 .RS 4
23759 .RE
23760 .ie n .IP """sv_does_sv""" 4
23761 .el .IP \f(CWsv_does_sv\fR 4
23762 .IX Xref "sv_does_sv"
23763 .IX Item "sv_does_sv"
23764 Returns a boolean indicating whether the SV performs a specific, named role.
23765 The SV can be a Perl object or the name of a Perl class.
23766 .RS 4
23767 .Sp
23768 .Vb 2
23769 \& bool sv_does_sv( SV *sv, SV *namesv, U32 flags)
23770 \& bool Perl_sv_does_sv(pTHX_ SV *sv, SV *namesv, U32 flags)
23771 .Ve
23772 .RE
23773 .RS 4
23774 .RE
23775 .ie n .IP """sv_eq""" 4
23776 .el .IP \f(CWsv_eq\fR 4
23777 .IX Item "sv_eq"
23778 .PD 0
23779 .ie n .IP """sv_eq_flags""" 4
23780 .el .IP \f(CWsv_eq_flags\fR 4
23781 .IX Xref "sv_eq sv_eq_flags"
23782 .IX Item "sv_eq_flags"
23783 .PD
23784 These each return a boolean indicating whether or not the strings in the two
23785 SVs are equal. If \f(CW\*(Aquse\ bytes\*(Aq\fR is in effect, the comparison is
23786 byte\-by\-byte; otherwise character\-by\-character. Each will coerce its args to
23787 strings if necessary.
23788 .Sp
23789 They differ only in that \f(CW\*(C`sv_eq\*(C'\fR always processes get magic, while
23790 \&\f(CW\*(C`sv_eq_flags\*(C'\fR processes get magic only when the \f(CW\*(C`flags\*(C'\fR parameter has the
23791 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR bit set.
23792 .Sp
23793 These functions do not handle operator overloading. For versions that do,
23794 see instead \f(CW"sv_streq"\fR or \f(CW"sv_streq_flags"\fR.
23795 .RS 4
23796 .Sp
23797 .Vb 4
23798 \& I32 sv_eq ( SV *sv1, SV *sv2)
23799 \& I32 Perl_sv_eq (pTHX_ SV *sv1, SV *sv2)
23800 \& I32 sv_eq_flags( SV *sv1, SV *sv2, const U32 flags)
23801 \& I32 Perl_sv_eq_flags(pTHX_ SV *sv1, SV *sv2, const U32 flags)
23802 .Ve
23803 .RE
23804 .RS 4
23805 .RE
23806 .ie n .IP """sv_force_normal""" 4
23807 .el .IP \f(CWsv_force_normal\fR 4
23808 .IX Item "sv_force_normal"
23809 .PD 0
23810 .ie n .IP """sv_force_normal_flags""" 4
23811 .el .IP \f(CWsv_force_normal_flags\fR 4
23812 .IX Xref "sv_force_normal sv_force_normal_flags"
23813 .IX Item "sv_force_normal_flags"
23814 .PD
23815 Undo various types of fakery on an SV, where fakery means
23816 "more than" a string:
23817 .RS 4
23818 .IP "if the PV is a shared string" 4
23819 .IX Item "if the PV is a shared string"
23820 make a private copy
23821 .IP "if we\*(Aqre a ref" 4
23822 .IX Item "if we're a ref"
23823 stop refing. This is done by calling \f(CW"sv_unref_flags"\fR.
23824 In \f(CW\*(C`sv_force_normal_flags\*(C'\fR, the \f(CW\*(C`flags\*(C'\fR parameter gets passed to
23825 that function.
23826 .IP "if we\*(Aqre a glob" 4
23827 .IX Item "if we're a glob"
23828 downgrade to an \f(CW\*(C`xpvmg\*(C'\fR;
23829 .IP "if we\*(Aqre a copy\-on\-write scalar" 4
23830 .IX Item "if we're a copy-on-write scalar"
23831 this is the on\-write time when we do the copy, and is also used locally
23832 .IP "if this is a vstring" 4
23833 .IX Item "if this is a vstring"
23834 drop the vstring magic
23835 .ie n .IP "in ""sv_force_normal_flags"" if ""SV_COW_DROP_PV"" is set in ""flags""" 4
23836 .el .IP "in \f(CWsv_force_normal_flags\fR if \f(CWSV_COW_DROP_PV\fR is set in \f(CWflags\fR" 4
23837 .IX Item "in sv_force_normal_flags if SV_COW_DROP_PV is set in flags"
23838 a copy\-on\-write scalar drops its PV buffer (if any) and becomes \f(CW\*(C`SvPOK_off\*(C'\fR
23839 rather than making a copy. (Used where this scalar is about to be set to some
23840 other value.)
23841 .RE
23842 .RS 4
23843 .Sp
23844 Other than what was mentioned above, the two forms behave identically.
23845 This is because \f(CW\*(C`sv_force_normal\*(C'\fR merely calls \f(CW\*(C`sv_force_normal_flags\*(C'\fR with
23846 \&\f(CW\*(C`flags\*(C'\fR set to 0.
23847 .Sp
23848 .Vb 6
23849 \& void sv_force_normal ( SV *sv)
23850 \& void Perl_sv_force_normal (pTHX_ SV *sv)
23851 \& void sv_force_normal_flags( SV * const sv,
23852 \& const U32 flags)
23853 \& void Perl_sv_force_normal_flags(pTHX_ SV * const sv,
23854 \& const U32 flags)
23855 .Ve
23856 .RE
23857 .RS 4
23858 .RE
23859 .ie n .IP """sv_free""" 4
23860 .el .IP \f(CWsv_free\fR 4
23861 .IX Xref "sv_free"
23862 .IX Item "sv_free"
23863 Decrement an SV\*(Aqs reference count, and if it drops to zero, call
23864 \&\f(CW\*(C`sv_clear\*(C'\fR to invoke destructors and free up any memory used by
23865 the body; finally, deallocating the SV\*(Aqs head itself.
23866 Normally called via a wrapper macro \f(CW\*(C`SvREFCNT_dec\*(C'\fR.
23867 .RS 4
23868 .Sp
23869 .Vb 2
23870 \& void sv_free( SV * const sv)
23871 \& void Perl_sv_free(pTHX_ SV * const sv)
23872 .Ve
23873 .RE
23874 .RS 4
23875 .RE
23876 .ie n .IP """sv_get_backrefs""" 4
23877 .el .IP \f(CWsv_get_backrefs\fR 4
23878 .IX Xref "sv_get_backrefs"
23879 .IX Item "sv_get_backrefs"
23880 NOTE: \f(CW\*(C`sv_get_backrefs\*(C'\fR is \fBexperimental\fR and may change or be
23881 removed without notice.
23882 .Sp
23883 If \f(CW\*(C`sv\*(C'\fR is the target of a weak reference then it returns the back
23884 references structure associated with the sv; otherwise return \f(CW\*(C`NULL\*(C'\fR.
23885 .Sp
23886 When returning a non\-null result the type of the return is relevant. If it
23887 is an AV then the elements of the AV are the weak reference RVs which
23888 point at this item. If it is any other type then the item itself is the
23889 weak reference.
23890 .Sp
23891 See also \f(CWPerl_sv_add_backref()\fR, \f(CWPerl_sv_del_backref()\fR,
23892 \&\f(CWPerl_sv_kill_backrefs()\fR
23893 .RS 4
23894 .Sp
23895 .Vb 2
23896 \& SV * sv_get_backrefs(SV * const sv)
23897 \& SV * Perl_sv_get_backrefs(SV * const sv)
23898 .Ve
23899 .RE
23900 .RS 4
23901 .RE
23902 .ie n .IP """sv_gets""" 4
23903 .el .IP \f(CWsv_gets\fR 4
23904 .IX Xref "sv_gets"
23905 .IX Item "sv_gets"
23906 Get a line from the filehandle and store it into the SV, optionally
23907 appending to the currently\-stored string. If \f(CW\*(C`append\*(C'\fR is not 0, the
23908 line is appended to the SV instead of overwriting it. \f(CW\*(C`append\*(C'\fR should
23909 be set to the byte offset that the appended string should start at
23910 in the SV (typically, \f(CWSvCUR(sv)\fR is a suitable choice).
23911 .RS 4
23912 .Sp
23913 .Vb 4
23914 \& char * sv_gets( SV * const sv, PerlIO * const fp,
23915 \& SSize_t append)
23916 \& char * Perl_sv_gets(pTHX_ SV * const sv, PerlIO * const fp,
23917 \& SSize_t append)
23918 .Ve
23919 .RE
23920 .RS 4
23921 .RE
23922 .ie n .IP """sv_inc""" 4
23923 .el .IP \f(CWsv_inc\fR 4
23924 .IX Item "sv_inc"
23925 .PD 0
23926 .ie n .IP """sv_inc_nomg""" 4
23927 .el .IP \f(CWsv_inc_nomg\fR 4
23928 .IX Xref "sv_inc sv_inc_nomg"
23929 .IX Item "sv_inc_nomg"
23930 .PD
23931 These auto\-increment the value in the SV, doing string to numeric conversion
23932 if necessary. They both handle operator overloading.
23933 .Sp
23934 They differ only in that \f(CW\*(C`sv_inc\*(C'\fR performs \*(Aqget\*(Aq magic; \f(CW\*(C`sv_inc_nomg\*(C'\fR skips
23935 any magic.
23936 .RS 4
23937 .Sp
23938 .Vb 4
23939 \& void sv_inc ( SV * const sv)
23940 \& void Perl_sv_inc (pTHX_ SV * const sv)
23941 \& void sv_inc_nomg( SV * const sv)
23942 \& void Perl_sv_inc_nomg(pTHX_ SV * const sv)
23943 .Ve
23944 .RE
23945 .RS 4
23946 .RE
23947 .ie n .IP """sv_insert""" 4
23948 .el .IP \f(CWsv_insert\fR 4
23949 .IX Item "sv_insert"
23950 .PD 0
23951 .ie n .IP """sv_insert_flags""" 4
23952 .el .IP \f(CWsv_insert_flags\fR 4
23953 .IX Xref "sv_insert sv_insert_flags"
23954 .IX Item "sv_insert_flags"
23955 .PD
23956 These insert and/or replace a string at the specified offset/length within the
23957 SV. Similar to the Perl \f(CWsubstr()\fR function, with \f(CW\*(C`littlelen\*(C'\fR bytes starting
23958 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
23959 \&\f(CW\*(C`offset\*(C'\fR. They handle get magic.
23960 .Sp
23961 \&\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
23962 are passed to the \f(CW\*(C`SvPV_force_flags\*(C'\fR operation that is internally applied to
23963 \&\f(CW\*(C`bigstr\*(C'\fR.
23964 .RS 4
23965 .Sp
23966 .Vb 10
23967 \& void sv_insert ( SV * const bigstr,
23968 \& const STRLEN offset,
23969 \& const STRLEN len,
23970 \& const char * const little,
23971 \& const STRLEN littlelen)
23972 \& void Perl_sv_insert (pTHX_ SV * const bigstr,
23973 \& const STRLEN offset,
23974 \& const STRLEN len,
23975 \& const char * const little,
23976 \& const STRLEN littlelen)
23977 \& void sv_insert_flags( SV * const bigstr,
23978 \& const STRLEN offset,
23979 \& const STRLEN len,
23980 \& const char *little,
23981 \& const STRLEN littlelen,
23982 \& const U32 flags)
23983 \& void Perl_sv_insert_flags(pTHX_ SV * const bigstr,
23984 \& const STRLEN offset,
23985 \& const STRLEN len,
23986 \& const char *little,
23987 \& const STRLEN littlelen,
23988 \& const U32 flags)
23989 .Ve
23990 .RE
23991 .RS 4
23992 .RE
23993 .ie n .IP """sv_isa""" 4
23994 .el .IP \f(CWsv_isa\fR 4
23995 .IX Xref "sv_isa"
23996 .IX Item "sv_isa"
23997 Returns a boolean indicating whether the SV is blessed into the specified
23998 class.
23999 .Sp
24000 This does not check for subtypes or method overloading. Use \f(CW\*(C`sv_isa_sv\*(C'\fR to
24001 verify an inheritance relationship in the same way as the \f(CW\*(C`isa\*(C'\fR operator by
24002 respecting any \f(CWisa()\fR method overloading; or \f(CW\*(C`sv_derived_from_sv\*(C'\fR to test
24003 directly on the actual object type.
24004 .RS 4
24005 .Sp
24006 .Vb 2
24007 \& int sv_isa( SV *sv, const char * const name)
24008 \& int Perl_sv_isa(pTHX_ SV *sv, const char * const name)
24009 .Ve
24010 .RE
24011 .RS 4
24012 .RE
24013 .ie n .IP """sv_isa_sv""" 4
24014 .el .IP \f(CWsv_isa_sv\fR 4
24015 .IX Xref "sv_isa_sv"
24016 .IX Item "sv_isa_sv"
24017 Returns a boolean indicating whether the SV is an object reference and is
24018 derived from the specified class, respecting any \f(CWisa()\fR method overloading
24019 it may have. Returns false if \f(CW\*(C`sv\*(C'\fR is not a reference to an object, or is
24020 not derived from the specified class.
24021 .Sp
24022 This is the function used to implement the behaviour of the \f(CW\*(C`isa\*(C'\fR operator.
24023 .Sp
24024 Does not invoke magic on \f(CW\*(C`sv\*(C'\fR.
24025 .Sp
24026 Not to be confused with the older \f(CW\*(C`sv_isa\*(C'\fR function, which does not use an
24027 overloaded \f(CWisa()\fR method, nor will check subclassing.
24028 .RS 4
24029 .Sp
24030 .Vb 2
24031 \& bool sv_isa_sv( SV *sv, SV *namesv)
24032 \& bool Perl_sv_isa_sv(pTHX_ SV *sv, SV *namesv)
24033 .Ve
24034 .RE
24035 .RS 4
24036 .RE
24037 .ie n .IP """sv_isobject""" 4
24038 .el .IP \f(CWsv_isobject\fR 4
24039 .IX Xref "sv_isobject"
24040 .IX Item "sv_isobject"
24041 Returns a boolean indicating whether the SV is an RV pointing to a blessed
24042 object. If the SV is not an RV, or if the object is not blessed, then this
24043 will return false.
24044 .RS 4
24045 .Sp
24046 .Vb 2
24047 \& int sv_isobject( SV *sv)
24048 \& int Perl_sv_isobject(pTHX_ SV *sv)
24049 .Ve
24050 .RE
24051 .RS 4
24052 .RE
24053 .ie n .IP """sv_len""" 4
24054 .el .IP \f(CWsv_len\fR 4
24055 .IX Xref "sv_len"
24056 .IX Item "sv_len"
24057 Returns the length of the string in the SV. Handles magic and type
24058 coercion and sets the UTF8 flag appropriately. See also \f(CW"SvCUR"\fR, which
24059 gives raw access to the \f(CW\*(C`xpv_cur\*(C'\fR slot.
24060 .RS 4
24061 .Sp
24062 .Vb 2
24063 \& STRLEN sv_len( SV * const sv)
24064 \& STRLEN Perl_sv_len(pTHX_ SV * const sv)
24065 .Ve
24066 .RE
24067 .RS 4
24068 .RE
24069 .ie n .IP """sv_len_utf8""" 4
24070 .el .IP \f(CWsv_len_utf8\fR 4
24071 .IX Item "sv_len_utf8"
24072 .PD 0
24073 .ie n .IP """sv_len_utf8_nomg""" 4
24074 .el .IP \f(CWsv_len_utf8_nomg\fR 4
24075 .IX Xref "sv_len_utf8 sv_len_utf8_nomg"
24076 .IX Item "sv_len_utf8_nomg"
24077 .PD
24078 These return the number of characters in the string in an SV, counting wide
24079 UTF\-8 bytes as a single character. Both handle type coercion.
24080 They differ only in that \f(CW\*(C`sv_len_utf8\*(C'\fR performs \*(Aqget\*(Aq magic;
24081 \&\f(CW\*(C`sv_len_utf8_nomg\*(C'\fR skips any magic.
24082 .RS 4
24083 .Sp
24084 .Vb 4
24085 \& STRLEN sv_len_utf8 ( SV * const sv)
24086 \& STRLEN Perl_sv_len_utf8 (pTHX_ SV * const sv)
24087 \& STRLEN sv_len_utf8_nomg( SV * const sv)
24088 \& STRLEN Perl_sv_len_utf8_nomg(pTHX_ SV * const sv)
24089 .Ve
24090 .RE
24091 .RS 4
24092 .RE
24093 .ie n .IP """sv_magic""" 4
24094 .el .IP \f(CWsv_magic\fR 4
24095 .IX Xref "sv_magic"
24096 .IX Item "sv_magic"
24097 Adds magic to an SV. First upgrades \f(CW\*(C`sv\*(C'\fR to type \f(CW\*(C`SVt_PVMG\*(C'\fR if
24098 necessary, then adds a new magic item of type \f(CW\*(C`how\*(C'\fR to the head of the
24099 magic list.
24100 .Sp
24101 See \f(CW"sv_magicext"\fR (which \f(CW\*(C`sv_magic\*(C'\fR now calls) for a description of the
24102 handling of the \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`namlen\*(C'\fR arguments.
24103 .Sp
24104 You need to use \f(CW\*(C`sv_magicext\*(C'\fR to add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs and also
24105 to add more than one instance of the same \f(CW\*(C`how\*(C'\fR.
24106 .RS 4
24107 .Sp
24108 .Vb 6
24109 \& void sv_magic( SV * const sv, SV * const obj,
24110 \& const int how, const char * const name,
24111 \& const I32 namlen)
24112 \& void Perl_sv_magic(pTHX_ SV * const sv, SV * const obj,
24113 \& const int how, const char * const name,
24114 \& const I32 namlen)
24115 .Ve
24116 .RE
24117 .RS 4
24118 .RE
24119 .ie n .IP """sv_magicext""" 4
24120 .el .IP \f(CWsv_magicext\fR 4
24121 .IX Xref "sv_magicext"
24122 .IX Item "sv_magicext"
24123 Adds magic to an SV, upgrading it if necessary. Applies the
24124 supplied \f(CW\*(C`vtable\*(C'\fR and returns a pointer to the magic added.
24125 .Sp
24126 Note that \f(CW\*(C`sv_magicext\*(C'\fR will allow things that \f(CW\*(C`sv_magic\*(C'\fR will not.
24127 In particular, you can add magic to \f(CW\*(C`SvREADONLY\*(C'\fR SVs, and add more than
24128 one instance of the same \f(CW\*(C`how\*(C'\fR.
24129 .Sp
24130 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
24131 stored, if \f(CW\*(C`namlen\*(C'\fR is zero then \f(CW\*(C`name\*(C'\fR is stored as\-is and \- as another
24132 special case \- if \f(CW\*(C`(name && namlen == HEf_SVKEY)\*(C'\fR then \f(CW\*(C`name\*(C'\fR is assumed
24133 to contain an SV* and is stored as\-is with its \f(CW\*(C`REFCNT\*(C'\fR incremented.
24134 .Sp
24135 (This is now used as a subroutine by \f(CW\*(C`sv_magic\*(C'\fR.)
24136 .RS 4
24137 .Sp
24138 .Vb 10
24139 \& MAGIC * sv_magicext( SV * const sv, SV * const obj,
24140 \& const int how,
24141 \& const MGVTBL * const vtbl,
24142 \& const char * const name,
24143 \& const I32 namlen)
24144 \& MAGIC * Perl_sv_magicext(pTHX_ SV * const sv, SV * const obj,
24145 \& const int how,
24146 \& const MGVTBL * const vtbl,
24147 \& const char * const name,
24148 \& const I32 namlen)
24149 .Ve
24150 .RE
24151 .RS 4
24152 .RE
24153 .ie n .IP """sv_mortalcopy""" 4
24154 .el .IP \f(CWsv_mortalcopy\fR 4
24155 .IX Item "sv_mortalcopy"
24156 .PD 0
24157 .ie n .IP """sv_mortalcopy_flags""" 4
24158 .el .IP \f(CWsv_mortalcopy_flags\fR 4
24159 .IX Xref "sv_mortalcopy sv_mortalcopy_flags"
24160 .IX Item "sv_mortalcopy_flags"
24161 .PD
24162 These each create a new SV which is a copy of the original SV (using
24163 \&\f(CW"sv_setsv"\fR). The new SV is marked as mortal. It will be destroyed
24164 "soon", either by an
24165 explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as
24166 statement boundaries. See also \f(CW"sv_newmortal"\fR and \f(CW"sv_2mortal"\fR.
24167 .Sp
24168 The two forms are identical, except \f(CW\*(C`sv_mortalcopy_flags\*(C'\fR has an extra
24169 \&\f(CW\*(C`flags\*(C'\fR parameter, the contents of which are passed along to
24170 \&\f(CW"sv_setsv_flags"\fR.
24171 .RS 4
24172 .Sp
24173 .Vb 4
24174 \& SV * sv_mortalcopy ( SV * const oldsv)
24175 \& SV * Perl_sv_mortalcopy (pTHX_ SV * const oldsv)
24176 \& SV * sv_mortalcopy_flags( SV * const oldsv, U32 flags)
24177 \& SV * Perl_sv_mortalcopy_flags(pTHX_ SV * const oldsv, U32 flags)
24178 .Ve
24179 .RE
24180 .RS 4
24181 .RE
24182 .ie n .IP """sv_newmortal""" 4
24183 .el .IP \f(CWsv_newmortal\fR 4
24184 .IX Xref "sv_newmortal"
24185 .IX Item "sv_newmortal"
24186 Creates a new null SV which is mortal. The reference count of the SV is
24187 set to 1. It will be destroyed "soon", either by an explicit call to
24188 \&\f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as statement boundaries.
24189 See also \f(CW"sv_mortalcopy"\fR and \f(CW"sv_2mortal"\fR.
24190 .RS 4
24191 .Sp
24192 .Vb 2
24193 \& SV * sv_newmortal()
24194 \& SV * Perl_sv_newmortal(pTHX)
24195 .Ve
24196 .RE
24197 .RS 4
24198 .RE
24199 .ie n .IP """sv_nolocking""" 4
24200 .el .IP \f(CWsv_nolocking\fR 4
24201 .IX Xref "sv_nolocking"
24202 .IX Item "sv_nolocking"
24203 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`sv_nolocking\*(C'\fR
24204 from a future release of Perl. Do not use it for
24205 new code; remove it from existing code.
24206 .Sp
24207 Dummy routine which "locks" an SV when there is no locking module present.
24208 Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
24209 potentially warn under some level of strict\-ness.
24210 .Sp
24211 "Superseded" by \f(CWsv_nosharing()\fR.
24212 .RS 4
24213 .Sp
24214 .Vb 2
24215 \& void sv_nolocking( SV *sv)
24216 \& void Perl_sv_nolocking(pTHX_ SV *sv)
24217 .Ve
24218 .RE
24219 .RS 4
24220 .RE
24221 .ie n .IP """sv_nounlocking""" 4
24222 .el .IP \f(CWsv_nounlocking\fR 4
24223 .IX Xref "sv_nounlocking"
24224 .IX Item "sv_nounlocking"
24225 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`sv_nounlocking\*(C'\fR
24226 from a future release of Perl. Do not use it for
24227 new code; remove it from existing code.
24228 .Sp
24229 Dummy routine which "unlocks" an SV when there is no locking module present.
24230 Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
24231 potentially warn under some level of strict\-ness.
24232 .Sp
24233 "Superseded" by \f(CWsv_nosharing()\fR.
24234 .RS 4
24235 .Sp
24236 .Vb 2
24237 \& void sv_nounlocking( SV *sv)
24238 \& void Perl_sv_nounlocking(pTHX_ SV *sv)
24239 .Ve
24240 .RE
24241 .RS 4
24242 .RE
24243 .ie n .IP """sv_numeq""" 4
24244 .el .IP \f(CWsv_numeq\fR 4
24245 .IX Item "sv_numeq"
24246 .PD 0
24247 .ie n .IP """sv_numeq_flags""" 4
24248 .el .IP \f(CWsv_numeq_flags\fR 4
24249 .IX Xref "sv_numeq sv_numeq_flags"
24250 .IX Item "sv_numeq_flags"
24251 .PD
24252 These each return a boolean indicating whether the numbers in the two SV
24253 arguments are identical. Those arguments will be coerced to numbers if
24254 necessary. A \f(CW\*(C`NULL\*(C'\fR SV is treated as \f(CW\*(C`undef\*(C'\fR.
24255 .Sp
24256 In \f(CW\*(C`sv_numeq_flags\*(C'\fR, if \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, \*(Aqget\*(Aq magic is
24257 handled.
24258 .Sp
24259 And unless \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use
24260 \&\f(CW\*(C`==\*(C'\fR overloading will be made. If such overloading does not exist or the flag
24261 is set, then regular numerical comparison will be used instead.
24262 .Sp
24263 \&\f(CW\*(C`sv_numeq\*(C'\fR merely calls \f(CW\*(C`sv_numeq_flags\*(C'\fR with just the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set.
24264 This function basically behaves like the Perl code \f(CW\*(C`$sv1 == $sv2\*(C'\fR.
24265 .RS 4
24266 .Sp
24267 .Vb 5
24268 \& bool sv_numeq ( SV *sv1, SV *sv2)
24269 \& bool sv_numeq_flags( SV *sv1, SV *sv2,
24270 \& const U32 flags)
24271 \& bool Perl_sv_numeq_flags(pTHX_ SV *sv1, SV *sv2,
24272 \& const U32 flags)
24273 .Ve
24274 .RE
24275 .RS 4
24276 .RE
24277 .ie n .IP """sv_pos_b2u""" 4
24278 .el .IP \f(CWsv_pos_b2u\fR 4
24279 .IX Item "sv_pos_b2u"
24280 .PD 0
24281 .ie n .IP """sv_pos_b2u_flags""" 4
24282 .el .IP \f(CWsv_pos_b2u_flags\fR 4
24283 .IX Xref "sv_pos_b2u sv_pos_b2u_flags"
24284 .IX Item "sv_pos_b2u_flags"
24285 .PD
24286 These each count the number of UTF\-8 encoded characters in the PV of \f(CW\*(C`sv\*(C'\fR.
24287 The entire PV is not necessarily looked at, just the first so\-many bytes.
24288 The byte count is given by \f(CW*offsetp\fR in \f(CW\*(C`sv_pos_b2u\*(C'\fR, and by \f(CW\*(C`offset\*(C'\fR in
24289 \&\f(CW\*(C`sv_pos_b2u_flags\*(C'\fR.
24290 .Sp
24291 The caller must ensure that the PV contains at least as many bytes as the count
24292 passed in.
24293 .Sp
24294 \&\f(CW\*(C`sv_pos_b2u\*(C'\fR returns \f(CW\*(C`void\*(C'\fR, instead updating \f(CW*offsetp\fR to the character
24295 count.
24296 \&\f(CW\*(C`sv_pos_b2u_flags\*(C'\fR returns the character count.
24297 .Sp
24298 \&\f(CW\*(C`sv_pos_b2u_flags\*(C'\fR is preferred as \f(CW\*(C`offsetp\*(C'\fR is a \f(CW*I32\fR, which limits the
24299 size it can handle to 2Gb.
24300 .Sp
24301 Both handle type coercion.
24302 .Sp
24303 \&\f(CW\*(C`sv_pos_b2u\*(C'\fR always handles \*(Aqget\*(Aq magic.
24304 \&\f(CW\*(C`sv_pos_b2u_flags\*(C'\fR only handles \*(Aqget\*(Aq magic when \f(CW\*(C`flags\*(C'\fR contains
24305 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
24306 .Sp
24307 In fact, \f(CW\*(C`sv_pos_b2u_flags\*(C'\fR passes \f(CW\*(C`flags\*(C'\fR to \f(CW\*(C`SvPV_flags\*(C'\fR, and \f(CW\*(C`flags\*(C'\fR
24308 usually should be \f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR.
24309 \&\f(CW\*(C`sv_pos_b2u\*(C'\fR automatically causes \f(CW\*(C`SV_CONST_RETURN\*(C'\fR to be passed to
24310 \&\f(CW\*(C`SvPV_flags\*(C'\fR.
24311 .Sp
24312 Both functions use and update \f(CW\*(C`PERL_MAGIC_utf8\*(C'\fR.
24313 .RS 4
24314 .Sp
24315 .Vb 10
24316 \& void sv_pos_b2u ( SV * const sv,
24317 \& I32 * const offsetp)
24318 \& void Perl_sv_pos_b2u (pTHX_ SV * const sv,
24319 \& I32 * const offsetp)
24320 \& STRLEN sv_pos_b2u_flags( SV * const sv,
24321 \& STRLEN const offset,
24322 \& U32 flags)
24323 \& STRLEN Perl_sv_pos_b2u_flags(pTHX_ SV * const sv,
24324 \& STRLEN const offset,
24325 \& U32 flags)
24326 .Ve
24327 .RE
24328 .RS 4
24329 .RE
24330 .ie n .IP """sv_pos_u2b""" 4
24331 .el .IP \f(CWsv_pos_u2b\fR 4
24332 .IX Item "sv_pos_u2b"
24333 .PD 0
24334 .ie n .IP """sv_pos_u2b_flags""" 4
24335 .el .IP \f(CWsv_pos_u2b_flags\fR 4
24336 .IX Xref "sv_pos_u2b sv_pos_u2b_flags"
24337 .IX Item "sv_pos_u2b_flags"
24338 .PD
24339 These each find out how many bytes are occupied by the first so\-many
24340 UTF\-8\-encoded characters in the PV of \f(CW\*(C`sv\*(C'\fR. The character count is passed by
24341 \&\f(CW*offsetp\fR in \f(CW\*(C`sv_pos_u2b\*(C'\fR, and by \f(CW\*(C`uoffset\*(C'\fR in \f(CW\*(C`sv_pos_u2b_flags\*(C'\fR.
24342 .Sp
24343 Optionally, they also count how many bytes are in the next so\-many
24344 UTF\-8\-encoded characters. This option is chosen in both functions by passing a
24345 non\-NULL \f(CW\*(C`lenp\*(C'\fR to them, and setting \f(CW*lenp\fR to the desired character count.
24346 The functions update \f(CW*lenp\fR with the byte count.
24347 .Sp
24348 \&\f(CW\*(C`sv_pos_u2b\*(C'\fR returns \f(CW\*(C`void\*(C'\fR, instead updating \f(CW*offsetp\fR to the byte count.
24349 \&\f(CW\*(C`sv_pos_u2b_flags\*(C'\fR returns the byte count.
24350 .Sp
24351 \&\f(CW\*(C`sv_pos_u2b_flags\*(C'\fR is preferred as \f(CW\*(C`offsetp\*(C'\fR is a \f(CW*I32\fR, which limits the
24352 size it can handle to 2Gb.
24353 .Sp
24354 Both handle type coercion.
24355 .Sp
24356 \&\f(CW\*(C`sv_pos_u2b\*(C'\fR always handles \*(Aqget\*(Aq magic.
24357 \&\f(CW\*(C`sv_pos_u2b_flags\*(C'\fR only handles \*(Aqget\*(Aq magic when \f(CW\*(C`flags\*(C'\fR contains
24358 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
24359 .Sp
24360 In fact, \f(CW\*(C`sv_pos_u2b_flags\*(C'\fR passes \f(CW\*(C`flags\*(C'\fR to \f(CW\*(C`SvPV_flags\*(C'\fR, and \f(CW\*(C`flags\*(C'\fR
24361 usually should be \f(CW\*(C`SV_GMAGIC|SV_CONST_RETURN\*(C'\fR.
24362 \&\f(CW\*(C`sv_pos_u2b\*(C'\fR automatically causes \f(CW\*(C`SV_CONST_RETURN\*(C'\fR to be passed to
24363 \&\f(CW\*(C`SvPV_flags\*(C'\fR.
24364 .Sp
24365 Both functions use and update \f(CW\*(C`PERL_MAGIC_utf8\*(C'\fR.
24366 .RS 4
24367 .Sp
24368 .Vb 10
24369 \& void sv_pos_u2b ( SV * const sv,
24370 \& I32 * const offsetp,
24371 \& I32 * const lenp)
24372 \& void Perl_sv_pos_u2b (pTHX_ SV * const sv,
24373 \& I32 * const offsetp,
24374 \& I32 * const lenp)
24375 \& STRLEN sv_pos_u2b_flags( SV * const sv,
24376 \& STRLEN uoffset,
24377 \& STRLEN * const lenp,
24378 \& U32 flags)
24379 \& STRLEN Perl_sv_pos_u2b_flags(pTHX_ SV * const sv,
24380 \& STRLEN uoffset,
24381 \& STRLEN * const lenp,
24382 \& U32 flags)
24383 .Ve
24384 .RE
24385 .RS 4
24386 .RE
24387 .ie n .IP """sv_pvn_force_flags""" 4
24388 .el .IP \f(CWsv_pvn_force_flags\fR 4
24389 .IX Xref "sv_pvn_force_flags"
24390 .IX Item "sv_pvn_force_flags"
24391 Get a sensible string out of the SV somehow.
24392 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
24393 appropriate, else not. \f(CW\*(C`sv_pvn_force\*(C'\fR and \f(CW\*(C`sv_pvn_force_nomg\*(C'\fR are
24394 implemented in terms of this function.
24395 You normally want to use the various wrapper macros instead: see
24396 \&\f(CW"SvPV_force"\fR and \f(CW"SvPV_force_nomg"\fR.
24397 .RS 4
24398 .Sp
24399 .Vb 6
24400 \& char * sv_pvn_force_flags( SV * const sv,
24401 \& STRLEN * const lp,
24402 \& const U32 flags)
24403 \& char * Perl_sv_pvn_force_flags(pTHX_ SV * const sv,
24404 \& STRLEN * const lp,
24405 \& const U32 flags)
24406 .Ve
24407 .RE
24408 .RS 4
24409 .RE
24410 .ie n .IP """sv_ref""" 4
24411 .el .IP \f(CWsv_ref\fR 4
24412 .IX Xref "sv_ref"
24413 .IX Item "sv_ref"
24414 Returns a SV describing what the SV passed in is a reference to.
24415 .Sp
24416 dst can be a SV to be set to the description or NULL, in which case a
24417 mortal SV is returned.
24418 .Sp
24419 If ob is true and the SV is blessed, the description is the class
24420 name, otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
24421 .RS 4
24422 .Sp
24423 .Vb 4
24424 \& SV * sv_ref( SV *dst, const SV * const sv,
24425 \& const int ob)
24426 \& SV * Perl_sv_ref(pTHX_ SV *dst, const SV * const sv,
24427 \& const int ob)
24428 .Ve
24429 .RE
24430 .RS 4
24431 .RE
24432 .ie n .IP """sv_reftype""" 4
24433 .el .IP \f(CWsv_reftype\fR 4
24434 .IX Xref "sv_reftype"
24435 .IX Item "sv_reftype"
24436 Returns a string describing what the SV is a reference to.
24437 .Sp
24438 If ob is true and the SV is blessed, the string is the class name,
24439 otherwise it is the type of the SV, "SCALAR", "ARRAY" etc.
24440 .RS 4
24441 .Sp
24442 .Vb 4
24443 \& const char * sv_reftype( const SV * const sv,
24444 \& const int ob)
24445 \& const char * Perl_sv_reftype(pTHX_ const SV * const sv,
24446 \& const int ob)
24447 .Ve
24448 .RE
24449 .RS 4
24450 .RE
24451 .ie n .IP """sv_replace""" 4
24452 .el .IP \f(CWsv_replace\fR 4
24453 .IX Xref "sv_replace"
24454 .IX Item "sv_replace"
24455 Make the first argument a copy of the second, then delete the original.
24456 The target SV physically takes over ownership of the body of the source SV
24457 and inherits its flags; however, the target keeps any magic it owns,
24458 and any magic in the source is discarded.
24459 Note that this is a rather specialist SV copying operation; most of the
24460 time you\*(Aqll want to use \f(CW\*(C`sv_setsv\*(C'\fR or one of its many macro front\-ends.
24461 .RS 4
24462 .Sp
24463 .Vb 2
24464 \& void sv_replace( SV * const sv, SV * const nsv)
24465 \& void Perl_sv_replace(pTHX_ SV * const sv, SV * const nsv)
24466 .Ve
24467 .RE
24468 .RS 4
24469 .RE
24470 .ie n .IP """sv_report_used""" 4
24471 .el .IP \f(CWsv_report_used\fR 4
24472 .IX Xref "sv_report_used"
24473 .IX Item "sv_report_used"
24474 Dump the contents of all SVs not yet freed (debugging aid).
24475 .RS 4
24476 .Sp
24477 .Vb 2
24478 \& void sv_report_used()
24479 \& void Perl_sv_report_used(pTHX)
24480 .Ve
24481 .RE
24482 .RS 4
24483 .RE
24484 .ie n .IP """sv_reset""" 4
24485 .el .IP \f(CWsv_reset\fR 4
24486 .IX Xref "sv_reset"
24487 .IX Item "sv_reset"
24488 Underlying implementation for the \f(CW\*(C`reset\*(C'\fR Perl function.
24489 Note that the perl\-level function is vaguely deprecated.
24490 .RS 4
24491 .Sp
24492 .Vb 2
24493 \& void sv_reset( const char *s, HV * const stash)
24494 \& void Perl_sv_reset(pTHX_ const char *s, HV * const stash)
24495 .Ve
24496 .RE
24497 .RS 4
24498 .RE
24499 .ie n .IP """sv_rvunweaken""" 4
24500 .el .IP \f(CWsv_rvunweaken\fR 4
24501 .IX Xref "sv_rvunweaken"
24502 .IX Item "sv_rvunweaken"
24503 Unweaken a reference: Clear the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; remove
24504 the backreference to this RV from the array of backreferences
24505 associated with the target SV, increment the refcount of the target.
24506 Silently ignores \f(CW\*(C`undef\*(C'\fR and warns on non\-weak references.
24507 .RS 4
24508 .Sp
24509 .Vb 2
24510 \& SV * sv_rvunweaken( SV * const sv)
24511 \& SV * Perl_sv_rvunweaken(pTHX_ SV * const sv)
24512 .Ve
24513 .RE
24514 .RS 4
24515 .RE
24516 .ie n .IP """sv_rvweaken""" 4
24517 .el .IP \f(CWsv_rvweaken\fR 4
24518 .IX Xref "sv_rvweaken"
24519 .IX Item "sv_rvweaken"
24520 Weaken a reference: set the \f(CW\*(C`SvWEAKREF\*(C'\fR flag on this RV; give the
24521 referred\-to SV \f(CW\*(C`PERL_MAGIC_backref\*(C'\fR magic if it hasn\*(Aqt already; and
24522 push a back\-reference to this RV onto the array of backreferences
24523 associated with that magic. If the RV is magical, set magic will be
24524 called after the RV is cleared. Silently ignores \f(CW\*(C`undef\*(C'\fR and warns
24525 on already\-weak references.
24526 .RS 4
24527 .Sp
24528 .Vb 2
24529 \& SV * sv_rvweaken( SV * const sv)
24530 \& SV * Perl_sv_rvweaken(pTHX_ SV * const sv)
24531 .Ve
24532 .RE
24533 .RS 4
24534 .RE
24535 .ie n .IP """sv_set_bool""" 4
24536 .el .IP \f(CWsv_set_bool\fR 4
24537 .IX Xref "sv_set_bool"
24538 .IX Item "sv_set_bool"
24539 Equivalent to \f(CW\*(C`sv_setsv(sv, bool_val ? &Pl_sv_yes : &PL_sv_no)\*(C'\fR, but
24540 may be made more efficient in the future. Doesn\*(Aqt handle set magic.
24541 .Sp
24542 The perl equivalent is \f(CW\*(C`$sv = !!$expr;\*(C'\fR.
24543 .Sp
24544 Introduced in perl 5.35.11.
24545 .RS 4
24546 .Sp
24547 .Vb 2
24548 \& void sv_set_bool( SV *sv, const bool bool_val)
24549 \& void Perl_sv_set_bool(pTHX_ SV *sv, const bool bool_val)
24550 .Ve
24551 .RE
24552 .RS 4
24553 .RE
24554 .ie n .IP """sv_set_false""" 4
24555 .el .IP \f(CWsv_set_false\fR 4
24556 .IX Xref "sv_set_false"
24557 .IX Item "sv_set_false"
24558 Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_no)\*(C'\fR, but may be made more
24559 efficient in the future. Doesn\*(Aqt handle set magic.
24560 .Sp
24561 The perl equivalent is \f(CW\*(C`$sv = !1;\*(C'\fR.
24562 .Sp
24563 Introduced in perl 5.35.11.
24564 .RS 4
24565 .Sp
24566 .Vb 2
24567 \& void sv_set_false( SV *sv)
24568 \& void Perl_sv_set_false(pTHX_ SV *sv)
24569 .Ve
24570 .RE
24571 .RS 4
24572 .RE
24573 .ie n .IP """sv_set_true""" 4
24574 .el .IP \f(CWsv_set_true\fR 4
24575 .IX Xref "sv_set_true"
24576 .IX Item "sv_set_true"
24577 Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_yes)\*(C'\fR, but may be made more
24578 efficient in the future. Doesn\*(Aqt handle set magic.
24579 .Sp
24580 The perl equivalent is \f(CW\*(C`$sv = !0;\*(C'\fR.
24581 .Sp
24582 Introduced in perl 5.35.11.
24583 .RS 4
24584 .Sp
24585 .Vb 2
24586 \& void sv_set_true( SV *sv)
24587 \& void Perl_sv_set_true(pTHX_ SV *sv)
24588 .Ve
24589 .RE
24590 .RS 4
24591 .RE
24592 .ie n .IP """sv_set_undef""" 4
24593 .el .IP \f(CWsv_set_undef\fR 4
24594 .IX Xref "sv_set_undef"
24595 .IX Item "sv_set_undef"
24596 Equivalent to \f(CW\*(C`sv_setsv(sv, &PL_sv_undef)\*(C'\fR, but more efficient.
24597 Doesn\*(Aqt handle set magic.
24598 .Sp
24599 The perl equivalent is \f(CW\*(C`$sv = undef;\*(C'\fR. Note that it doesn\*(Aqt free any string
24600 buffer, unlike \f(CW\*(C`undef $sv\*(C'\fR.
24601 .Sp
24602 Introduced in perl 5.25.12.
24603 .RS 4
24604 .Sp
24605 .Vb 2
24606 \& void sv_set_undef( SV *sv)
24607 \& void Perl_sv_set_undef(pTHX_ SV *sv)
24608 .Ve
24609 .RE
24610 .RS 4
24611 .RE
24612 .ie n .IP """sv_setbool""" 4
24613 .el .IP \f(CWsv_setbool\fR 4
24614 .IX Item "sv_setbool"
24615 .PD 0
24616 .ie n .IP """sv_setbool_mg""" 4
24617 .el .IP \f(CWsv_setbool_mg\fR 4
24618 .IX Xref "sv_setbool sv_setbool_mg"
24619 .IX Item "sv_setbool_mg"
24620 .PD
24621 These set an SV to a true or false boolean value, upgrading first if necessary.
24622 .Sp
24623 They differ only in that \f(CW\*(C`sv_setbool_mg\*(C'\fR handles \*(Aqset\*(Aq magic; \f(CW\*(C`sv_setbool\*(C'\fR
24624 does not.
24625 .RS 4
24626 .Sp
24627 .Vb 2
24628 \& void sv_setbool (SV *sv, bool b)
24629 \& void sv_setbool_mg(SV *sv, bool b)
24630 .Ve
24631 .RE
24632 .RS 4
24633 .RE
24634 .ie n .IP """sv_setiv""" 4
24635 .el .IP \f(CWsv_setiv\fR 4
24636 .IX Item "sv_setiv"
24637 .PD 0
24638 .ie n .IP """sv_setiv_mg""" 4
24639 .el .IP \f(CWsv_setiv_mg\fR 4
24640 .IX Xref "sv_setiv sv_setiv_mg"
24641 .IX Item "sv_setiv_mg"
24642 .PD
24643 These copy an integer into the given SV, upgrading first if necessary.
24644 .Sp
24645 They differ only in that \f(CW\*(C`sv_setiv_mg\*(C'\fR handles \*(Aqset\*(Aq magic; \f(CW\*(C`sv_setiv\*(C'\fR does
24646 not.
24647 .RS 4
24648 .Sp
24649 .Vb 4
24650 \& void sv_setiv ( SV * const sv, const IV num)
24651 \& void Perl_sv_setiv (pTHX_ SV * const sv, const IV num)
24652 \& void sv_setiv_mg( SV * const sv, const IV i)
24653 \& void Perl_sv_setiv_mg(pTHX_ SV * const sv, const IV i)
24654 .Ve
24655 .RE
24656 .RS 4
24657 .RE
24658 .ie n .IP """sv_setnv""" 4
24659 .el .IP \f(CWsv_setnv\fR 4
24660 .IX Item "sv_setnv"
24661 .PD 0
24662 .ie n .IP """sv_setnv_mg""" 4
24663 .el .IP \f(CWsv_setnv_mg\fR 4
24664 .IX Xref "sv_setnv sv_setnv_mg"
24665 .IX Item "sv_setnv_mg"
24666 .PD
24667 These copy a double into the given SV, upgrading first if necessary.
24668 .Sp
24669 They differ only in that \f(CW\*(C`sv_setnv_mg\*(C'\fR handles \*(Aqset\*(Aq magic; \f(CW\*(C`sv_setnv\*(C'\fR does
24670 not.
24671 .RS 4
24672 .Sp
24673 .Vb 4
24674 \& void sv_setnv ( SV * const sv, const NV num)
24675 \& void Perl_sv_setnv (pTHX_ SV * const sv, const NV num)
24676 \& void sv_setnv_mg( SV * const sv, const NV num)
24677 \& void Perl_sv_setnv_mg(pTHX_ SV * const sv, const NV num)
24678 .Ve
24679 .RE
24680 .RS 4
24681 .RE
24682 .ie n .IP """sv_setpv""" 4
24683 .el .IP \f(CWsv_setpv\fR 4
24684 .IX Item "sv_setpv"
24685 .PD 0
24686 .ie n .IP """sv_setpv_mg""" 4
24687 .el .IP \f(CWsv_setpv_mg\fR 4
24688 .IX Item "sv_setpv_mg"
24689 .ie n .IP """sv_setpvn""" 4
24690 .el .IP \f(CWsv_setpvn\fR 4
24691 .IX Item "sv_setpvn"
24692 .ie n .IP """sv_setpvn_fresh""" 4
24693 .el .IP \f(CWsv_setpvn_fresh\fR 4
24694 .IX Item "sv_setpvn_fresh"
24695 .ie n .IP """sv_setpvn_mg""" 4
24696 .el .IP \f(CWsv_setpvn_mg\fR 4
24697 .IX Item "sv_setpvn_mg"
24698 .ie n .IP """sv_setpvs""" 4
24699 .el .IP \f(CWsv_setpvs\fR 4
24700 .IX Item "sv_setpvs"
24701 .ie n .IP """sv_setpvs_mg""" 4
24702 .el .IP \f(CWsv_setpvs_mg\fR 4
24703 .IX Xref "sv_setpv sv_setpv_mg sv_setpvn sv_setpvn_fresh sv_setpvn_mg sv_setpvs sv_setpvs_mg"
24704 .IX Item "sv_setpvs_mg"
24705 .PD
24706 These copy a string into the SV \f(CW\*(C`sv\*(C'\fR, making sure it is \f(CW"SvPOK_only"\fR.
24707 .Sp
24708 In the \f(CW\*(C`pvs\*(C'\fR forms, the string must be a C literal string, enclosed in double
24709 quotes.
24710 .Sp
24711 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
24712 \&\f(CW\*(C`len\*(C'\fR indicates the number of bytes to be copied, potentially including
24713 embedded \f(CW\*(C`NUL\*(C'\fR characters.
24714 .Sp
24715 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,
24716 it points to the first byte of the string, and the copy proceeds up through the
24717 first encountered \f(CW\*(C`NUL\*(C'\fR byte.
24718 .Sp
24719 In the forms that take a \f(CW\*(C`ptr\*(C'\fR argument, if it is NULL, the SV will become
24720 undefined.
24721 .Sp
24722 \&\fBThe UTF\-8 flag is not changed by these functions.\fR
24723 .Sp
24724 A terminating NUL byte is guaranteed in the result.
24725 .Sp
24726 The \f(CW\*(C`_mg\*(C'\fR forms handle \*(Aqset\*(Aq magic; the other forms skip all magic.
24727 .Sp
24728 \&\f(CW\*(C`sv_setpvn_fresh\*(C'\fR is a cut\-down alternative to \f(CW\*(C`sv_setpvn\*(C'\fR, intended ONLY
24729 to be used with a fresh sv that has been upgraded to a SVt_PV, SVt_PVIV,
24730 SVt_PVNV, or SVt_PVMG.
24731 .RS 4
24732 .Sp
24733 .Vb 10
24734 \& void sv_setpv ( SV * const sv,
24735 \& const char * const ptr)
24736 \& void Perl_sv_setpv (pTHX_ SV * const sv,
24737 \& const char * const ptr)
24738 \& void sv_setpv_mg ( SV * const sv,
24739 \& const char * const ptr)
24740 \& void Perl_sv_setpv_mg (pTHX_ SV * const sv,
24741 \& const char * const ptr)
24742 \& void sv_setpvn ( SV * const sv,
24743 \& const char * const ptr,
24744 \& const STRLEN len)
24745 \& void Perl_sv_setpvn (pTHX_ SV * const sv,
24746 \& const char * const ptr,
24747 \& const STRLEN len)
24748 \& void sv_setpvn_fresh( SV * const sv,
24749 \& const char * const ptr,
24750 \& const STRLEN len)
24751 \& void Perl_sv_setpvn_fresh(pTHX_ SV * const sv,
24752 \& const char * const ptr,
24753 \& const STRLEN len)
24754 \& void sv_setpvn_mg ( SV * const sv,
24755 \& const char * const ptr,
24756 \& const STRLEN len)
24757 \& void Perl_sv_setpvn_mg (pTHX_ SV * const sv,
24758 \& const char * const ptr,
24759 \& const STRLEN len)
24760 \& void sv_setpvs ( SV *const sv, "literal string")
24761 \& void sv_setpvs_mg ( SV *const sv, "literal string")
24762 .Ve
24763 .RE
24764 .RS 4
24765 .RE
24766 .ie n .IP """sv_setpv_bufsize""" 4
24767 .el .IP \f(CWsv_setpv_bufsize\fR 4
24768 .IX Xref "sv_setpv_bufsize"
24769 .IX Item "sv_setpv_bufsize"
24770 Sets the SV to be a string of \f(CW\*(C`cur\*(C'\fR bytes length, with at least
24771 \&\f(CW\*(C`len\*(C'\fR bytes available. Ensures that there is a null byte at \f(CW\*(C`SvEND\*(C'\fR.
24772 .Sp
24773 Returns a char * pointer to the SvPV buffer.
24774 .Sp
24775 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
24776 contents. This means that if \f(CW\*(C`cur\*(C'\fR is zero, the SV is immediately fully
24777 formed and ready to use, just like any other SV containing an empty string.
24778 .RS 4
24779 .Sp
24780 .Vb 6
24781 \& char * sv_setpv_bufsize( SV * const sv,
24782 \& const STRLEN cur,
24783 \& const STRLEN len)
24784 \& char * Perl_sv_setpv_bufsize(pTHX_ SV * const sv,
24785 \& const STRLEN cur,
24786 \& const STRLEN len)
24787 .Ve
24788 .RE
24789 .RS 4
24790 .RE
24791 .ie n .IP """sv_setpv_mg*""" 4
24792 .el .IP \f(CWsv_setpv_mg*\fR 4
24793 .IX Item "sv_setpv_mg*"
24794 Described under \f(CW"sv_setpv"\fR
24795 .ie n .IP """sv_setpvf""" 4
24796 .el .IP \f(CWsv_setpvf\fR 4
24797 .IX Item "sv_setpvf"
24798 .PD 0
24799 .ie n .IP """sv_setpvf_mg""" 4
24800 .el .IP \f(CWsv_setpvf_mg\fR 4
24801 .IX Item "sv_setpvf_mg"
24802 .ie n .IP """sv_setpvf_mg_nocontext""" 4
24803 .el .IP \f(CWsv_setpvf_mg_nocontext\fR 4
24804 .IX Item "sv_setpvf_mg_nocontext"
24805 .ie n .IP """sv_setpvf_nocontext""" 4
24806 .el .IP \f(CWsv_setpvf_nocontext\fR 4
24807 .IX Xref "sv_setpvf sv_setpvf_mg sv_setpvf_mg_nocontext sv_setpvf_nocontext"
24808 .IX Item "sv_setpvf_nocontext"
24809 .PD
24810 These work like \f(CW"sv_catpvf"\fR but copy the text into the SV instead of
24811 appending it.
24812 .Sp
24813 The differences between these are:
24814 .Sp
24815 \&\f(CW\*(C`sv_setpvf_mg\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR perform \*(Aqset\*(Aq magic; \f(CW\*(C`sv_setpvf\*(C'\fR
24816 and \f(CW\*(C`sv_setpvf_nocontext\*(C'\fR skip all magic.
24817 .Sp
24818 \&\f(CW\*(C`sv_setpvf_nocontext\*(C'\fR and \f(CW\*(C`sv_setpvf_mg_nocontext\*(C'\fR do not take a thread
24819 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so are used in situations where the caller
24820 doesn\*(Aqt already have the thread context.
24821 .Sp
24822 \&\fBThe UTF\-8 flag is not changed by these functions.\fR
24823 .RS 4
24824 .Sp
24825 .Vb 10
24826 \& void Perl_sv_setpvf (pTHX_ SV * const sv,
24827 \& const char * const pat,
24828 \& ...)
24829 \& void Perl_sv_setpvf_mg (pTHX_ SV * const sv,
24830 \& const char * const pat,
24831 \& ...)
24832 \& void sv_setpvf_mg_nocontext( SV * const sv,
24833 \& const char * const pat,
24834 \& ...)
24835 \& void Perl_sv_setpvf_mg_nocontext( SV * const sv,
24836 \& const char * const pat,
24837 \& ...)
24838 \& void sv_setpvf_nocontext ( SV * const sv,
24839 \& const char * const pat,
24840 \& ...)
24841 \& void Perl_sv_setpvf_nocontext ( SV * const sv,
24842 \& const char * const pat,
24843 \& ...)
24844 .Ve
24845 .RE
24846 .RS 4
24847 .RE
24848 .ie n .IP """sv_setpvn*""" 4
24849 .el .IP \f(CWsv_setpvn*\fR 4
24850 .IX Item "sv_setpvn*"
24851 .PD 0
24852 .ie n .IP """sv_setpvn_fresh*""" 4
24853 .el .IP \f(CWsv_setpvn_fresh*\fR 4
24854 .IX Item "sv_setpvn_fresh*"
24855 .ie n .IP """sv_setpvn_mg*""" 4
24856 .el .IP \f(CWsv_setpvn_mg*\fR 4
24857 .IX Item "sv_setpvn_mg*"
24858 .ie n .IP """sv_setpvs*""" 4
24859 .el .IP \f(CWsv_setpvs*\fR 4
24860 .IX Item "sv_setpvs*"
24861 .ie n .IP """sv_setpvs_mg*""" 4
24862 .el .IP \f(CWsv_setpvs_mg*\fR 4
24863 .IX Item "sv_setpvs_mg*"
24864 .PD
24865 Described under \f(CW"sv_setpv"\fR
24866 .ie n .IP """sv_setref_iv""" 4
24867 .el .IP \f(CWsv_setref_iv\fR 4
24868 .IX Xref "sv_setref_iv"
24869 .IX Item "sv_setref_iv"
24870 Copies an integer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
24871 argument will be upgraded to an RV. That RV will be modified to point to
24872 the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
24873 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
24874 will have a reference count of 1, and the RV will be returned.
24875 .RS 4
24876 .Sp
24877 .Vb 6
24878 \& SV * sv_setref_iv( SV * const rv,
24879 \& const char * const classname,
24880 \& const IV iv)
24881 \& SV * Perl_sv_setref_iv(pTHX_ SV * const rv,
24882 \& const char * const classname,
24883 \& const IV iv)
24884 .Ve
24885 .RE
24886 .RS 4
24887 .RE
24888 .ie n .IP """sv_setref_nv""" 4
24889 .el .IP \f(CWsv_setref_nv\fR 4
24890 .IX Xref "sv_setref_nv"
24891 .IX Item "sv_setref_nv"
24892 Copies a double into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
24893 argument will be upgraded to an RV. That RV will be modified to point to
24894 the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
24895 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
24896 will have a reference count of 1, and the RV will be returned.
24897 .RS 4
24898 .Sp
24899 .Vb 6
24900 \& SV * sv_setref_nv( SV * const rv,
24901 \& const char * const classname,
24902 \& const NV nv)
24903 \& SV * Perl_sv_setref_nv(pTHX_ SV * const rv,
24904 \& const char * const classname,
24905 \& const NV nv)
24906 .Ve
24907 .RE
24908 .RS 4
24909 .RE
24910 .ie n .IP """sv_setref_pv""" 4
24911 .el .IP \f(CWsv_setref_pv\fR 4
24912 .IX Xref "sv_setref_pv"
24913 .IX Item "sv_setref_pv"
24914 Copies a pointer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
24915 argument will be upgraded to an RV. That RV will be modified to point to
24916 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
24917 into the SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
24918 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
24919 will have a reference count of 1, and the RV will be returned.
24920 .Sp
24921 Do not use with other Perl types such as HV, AV, SV, CV, because those
24922 objects will become corrupted by the pointer copy process.
24923 .Sp
24924 Note that \f(CW\*(C`sv_setref_pvn\*(C'\fR copies the string while this copies the pointer.
24925 .RS 4
24926 .Sp
24927 .Vb 6
24928 \& SV * sv_setref_pv( SV * const rv,
24929 \& const char * const classname,
24930 \& void * const pv)
24931 \& SV * Perl_sv_setref_pv(pTHX_ SV * const rv,
24932 \& const char * const classname,
24933 \& void * const pv)
24934 .Ve
24935 .RE
24936 .RS 4
24937 .RE
24938 .ie n .IP """sv_setref_pvn""" 4
24939 .el .IP \f(CWsv_setref_pvn\fR 4
24940 .IX Xref "sv_setref_pvn"
24941 .IX Item "sv_setref_pvn"
24942 Copies a string into a new SV, optionally blessing the SV. The length of the
24943 string must be specified with \f(CW\*(C`n\*(C'\fR. The \f(CW\*(C`rv\*(C'\fR argument will be upgraded to
24944 an RV. That RV will be modified to point to the new SV. The \f(CW\*(C`classname\*(C'\fR
24945 argument indicates the package for the blessing. Set \f(CW\*(C`classname\*(C'\fR to
24946 \&\f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV will have a reference count
24947 of 1, and the RV will be returned.
24948 .Sp
24949 Note that \f(CW\*(C`sv_setref_pv\*(C'\fR copies the pointer while this copies the string.
24950 .RS 4
24951 .Sp
24952 .Vb 8
24953 \& SV * sv_setref_pvn( SV * const rv,
24954 \& const char * const classname,
24955 \& const char * const pv,
24956 \& const STRLEN n)
24957 \& SV * Perl_sv_setref_pvn(pTHX_ SV * const rv,
24958 \& const char * const classname,
24959 \& const char * const pv,
24960 \& const STRLEN n)
24961 .Ve
24962 .RE
24963 .RS 4
24964 .RE
24965 .ie n .IP """sv_setref_pvs""" 4
24966 .el .IP \f(CWsv_setref_pvs\fR 4
24967 .IX Xref "sv_setref_pvs"
24968 .IX Item "sv_setref_pvs"
24969 Like \f(CW\*(C`sv_setref_pvn\*(C'\fR, but takes a literal string instead of
24970 a string/length pair.
24971 .RS 4
24972 .Sp
24973 .Vb 2
24974 \& SV * sv_setref_pvs(SV *const rv, const char *const classname,
24975 \& "literal string")
24976 .Ve
24977 .RE
24978 .RS 4
24979 .RE
24980 .ie n .IP """sv_setref_uv""" 4
24981 .el .IP \f(CWsv_setref_uv\fR 4
24982 .IX Xref "sv_setref_uv"
24983 .IX Item "sv_setref_uv"
24984 Copies an unsigned integer into a new SV, optionally blessing the SV. The \f(CW\*(C`rv\*(C'\fR
24985 argument will be upgraded to an RV. That RV will be modified to point to
24986 the new SV. The \f(CW\*(C`classname\*(C'\fR argument indicates the package for the
24987 blessing. Set \f(CW\*(C`classname\*(C'\fR to \f(CW\*(C`NULL\*(C'\fR to avoid the blessing. The new SV
24988 will have a reference count of 1, and the RV will be returned.
24989 .RS 4
24990 .Sp
24991 .Vb 6
24992 \& SV * sv_setref_uv( SV * const rv,
24993 \& const char * const classname,
24994 \& const UV uv)
24995 \& SV * Perl_sv_setref_uv(pTHX_ SV * const rv,
24996 \& const char * const classname,
24997 \& const UV uv)
24998 .Ve
24999 .RE
25000 .RS 4
25001 .RE
25002 .ie n .IP """sv_setrv_inc""" 4
25003 .el .IP \f(CWsv_setrv_inc\fR 4
25004 .IX Item "sv_setrv_inc"
25005 .PD 0
25006 .ie n .IP """sv_setrv_inc_mg""" 4
25007 .el .IP \f(CWsv_setrv_inc_mg\fR 4
25008 .IX Xref "sv_setrv_inc sv_setrv_inc_mg"
25009 .IX Item "sv_setrv_inc_mg"
25010 .PD
25011 As \f(CW\*(C`sv_setrv_noinc\*(C'\fR but increments the reference count of \fIref\fR.
25012 .Sp
25013 \&\f(CW\*(C`sv_setrv_inc_mg\*(C'\fR will invoke \*(Aqset\*(Aq magic on the SV; \f(CW\*(C`sv_setrv_inc\*(C'\fR will
25014 not.
25015 .RS 4
25016 .Sp
25017 .Vb 4
25018 \& void sv_setrv_inc ( SV * const sv, SV * const ref)
25019 \& void Perl_sv_setrv_inc (pTHX_ SV * const sv, SV * const ref)
25020 \& void sv_setrv_inc_mg( SV * const sv, SV * const ref)
25021 \& void Perl_sv_setrv_inc_mg(pTHX_ SV * const sv, SV * const ref)
25022 .Ve
25023 .RE
25024 .RS 4
25025 .RE
25026 .ie n .IP """sv_setrv_noinc""" 4
25027 .el .IP \f(CWsv_setrv_noinc\fR 4
25028 .IX Item "sv_setrv_noinc"
25029 .PD 0
25030 .ie n .IP """sv_setrv_noinc_mg""" 4
25031 .el .IP \f(CWsv_setrv_noinc_mg\fR 4
25032 .IX Xref "sv_setrv_noinc sv_setrv_noinc_mg"
25033 .IX Item "sv_setrv_noinc_mg"
25034 .PD
25035 Copies an SV pointer into the given SV as an SV reference, upgrading it if
25036 necessary. After this, \f(CWSvRV(sv)\fR is equal to \fIref\fR. This does not adjust
25037 the reference count of \fIref\fR. The reference \fIref\fR must not be NULL.
25038 .Sp
25039 \&\f(CW\*(C`sv_setrv_noinc_mg\*(C'\fR will invoke \*(Aqset\*(Aq magic on the SV; \f(CW\*(C`sv_setrv_noinc\*(C'\fR will
25040 not.
25041 .RS 4
25042 .Sp
25043 .Vb 4
25044 \& void sv_setrv_noinc ( SV * const sv, SV * const ref)
25045 \& void Perl_sv_setrv_noinc (pTHX_ SV * const sv, SV * const ref)
25046 \& void sv_setrv_noinc_mg( SV * const sv, SV * const ref)
25047 \& void Perl_sv_setrv_noinc_mg(pTHX_ SV * const sv, SV * const ref)
25048 .Ve
25049 .RE
25050 .RS 4
25051 .RE
25052 .ie n .IP """sv_setsv""" 4
25053 .el .IP \f(CWsv_setsv\fR 4
25054 .IX Item "sv_setsv"
25055 .PD 0
25056 .ie n .IP """sv_setsv_flags""" 4
25057 .el .IP \f(CWsv_setsv_flags\fR 4
25058 .IX Item "sv_setsv_flags"
25059 .ie n .IP """sv_setsv_mg""" 4
25060 .el .IP \f(CWsv_setsv_mg\fR 4
25061 .IX Item "sv_setsv_mg"
25062 .ie n .IP """sv_setsv_nomg""" 4
25063 .el .IP \f(CWsv_setsv_nomg\fR 4
25064 .IX Xref "sv_setsv sv_setsv_flags sv_setsv_mg sv_setsv_nomg"
25065 .IX Item "sv_setsv_nomg"
25066 .PD
25067 These copy the contents of the source SV \f(CW\*(C`ssv\*(C'\fR into the destination SV \f(CW\*(C`dsv\*(C'\fR.
25068 \&\f(CW\*(C`ssv\*(C'\fR may be destroyed if it is mortal, so don\*(Aqt use these functions if
25069 the source SV needs to be reused.
25070 Loosely speaking, they perform a copy\-by\-value, obliterating any previous
25071 content of the destination.
25072 .Sp
25073 They differ only in that:
25074 .Sp
25075 \&\f(CW\*(C`sv_setsv\*(C'\fR calls \*(Aqget\*(Aq magic on \f(CW\*(C`ssv\*(C'\fR, but skips \*(Aqset\*(Aq magic on \f(CW\*(C`dsv\*(C'\fR.
25076 .Sp
25077 \&\f(CW\*(C`sv_setsv_mg\*(C'\fR calls both \*(Aqget\*(Aq magic on \f(CW\*(C`ssv\*(C'\fR and \*(Aqset\*(Aq magic on \f(CW\*(C`dsv\*(C'\fR.
25078 .Sp
25079 \&\f(CW\*(C`sv_setsv_nomg\*(C'\fR skips all magic.
25080 .Sp
25081 \&\f(CW\*(C`sv_setsv_flags\*(C'\fR has a \f(CW\*(C`flags\*(C'\fR parameter which you can use to specify any
25082 combination of magic handling, and also you can specify \f(CW\*(C`SV_NOSTEAL\*(C'\fR so that
25083 the buffers of temps will not be stolen.
25084 .Sp
25085 You probably want to instead use one of the assortment of wrappers, such as
25086 \&\f(CW"SvSetSV"\fR, \f(CW"SvSetSV_nosteal"\fR, \f(CW"SvSetMagicSV"\fR and
25087 \&\f(CW"SvSetMagicSV_nosteal"\fR.
25088 .Sp
25089 \&\f(CW\*(C`sv_setsv_flags\*(C'\fR is the primary function for copying scalars, and most other
25090 copy\-ish functions and macros use it underneath.
25091 .RS 4
25092 .Sp
25093 .Vb 9
25094 \& void sv_setsv ( SV *dsv, SV *ssv)
25095 \& void Perl_sv_setsv (pTHX_ SV *dsv, SV *ssv)
25096 \& void sv_setsv_flags( SV *dsv, SV *ssv,
25097 \& const I32 flags)
25098 \& void Perl_sv_setsv_flags(pTHX_ SV *dsv, SV *ssv,
25099 \& const I32 flags)
25100 \& void sv_setsv_mg ( SV * const dsv, SV * const ssv)
25101 \& void Perl_sv_setsv_mg (pTHX_ SV * const dsv, SV * const ssv)
25102 \& void sv_setsv_nomg ( SV *dsv, SV *ssv)
25103 .Ve
25104 .RE
25105 .RS 4
25106 .RE
25107 .ie n .IP """sv_setuv""" 4
25108 .el .IP \f(CWsv_setuv\fR 4
25109 .IX Item "sv_setuv"
25110 .PD 0
25111 .ie n .IP """sv_setuv_mg""" 4
25112 .el .IP \f(CWsv_setuv_mg\fR 4
25113 .IX Xref "sv_setuv sv_setuv_mg"
25114 .IX Item "sv_setuv_mg"
25115 .PD
25116 These copy an unsigned integer into the given SV, upgrading first if necessary.
25117 .Sp
25118 They differ only in that \f(CW\*(C`sv_setuv_mg\*(C'\fR handles \*(Aqset\*(Aq magic; \f(CW\*(C`sv_setuv\*(C'\fR does
25119 not.
25120 .RS 4
25121 .Sp
25122 .Vb 4
25123 \& void sv_setuv ( SV * const sv, const UV num)
25124 \& void Perl_sv_setuv (pTHX_ SV * const sv, const UV num)
25125 \& void sv_setuv_mg( SV * const sv, const UV u)
25126 \& void Perl_sv_setuv_mg(pTHX_ SV * const sv, const UV u)
25127 .Ve
25128 .RE
25129 .RS 4
25130 .RE
25131 .ie n .IP """sv_streq""" 4
25132 .el .IP \f(CWsv_streq\fR 4
25133 .IX Item "sv_streq"
25134 .PD 0
25135 .ie n .IP """sv_streq_flags""" 4
25136 .el .IP \f(CWsv_streq_flags\fR 4
25137 .IX Xref "sv_streq sv_streq_flags"
25138 .IX Item "sv_streq_flags"
25139 .PD
25140 These each return a boolean indicating whether the strings in the two SVs are
25141 identical.
25142 .Sp
25143 \&\f(CW\*(C`sv_streq_flags\*(C'\fR is the more general form, having a \f(CW\*(C`flags\*(C'\fR argument that
25144 affects its behavior in two ways. It coerces its args to strings if necessary,
25145 treating a \f(CW\*(C`NULL\*(C'\fR argument as \f(CW\*(C`undef\*(C'\fR. It correctly handles the UTF8 flag.
25146 .Sp
25147 If \f(CW\*(C`flags\*(C'\fR has the \f(CW\*(C`SV_GMAGIC\*(C'\fR bit set, \*(Aqget\*(Aq magic will be handled.
25148 .Sp
25149 If flags does not have the \f(CW\*(C`SV_SKIP_OVERLOAD\*(C'\fR bit set, an attempt to use
25150 \&\f(CW\*(C`eq\*(C'\fR overloading will be made. If such overloading does not exist or the
25151 flag is set, then regular string comparison will be used instead.
25152 .Sp
25153 \&\f(CW\*(C`sv_streq\*(C'\fR merely calls \f(CW\*(C`sv_streq_flags\*(C'\fR with \f(CW\*(C`flags\*(C'\fR set to just
25154 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR. This function basically behaves like the Perl code
25155 \&\f(CW\*(C`$sv1\ eq\ $sv2\*(C'\fR.
25156 .RS 4
25157 .Sp
25158 .Vb 5
25159 \& bool sv_streq ( SV *sv1, SV *sv2)
25160 \& bool sv_streq_flags( SV *sv1, SV *sv2,
25161 \& const U32 flags)
25162 \& bool Perl_sv_streq_flags(pTHX_ SV *sv1, SV *sv2,
25163 \& const U32 flags)
25164 .Ve
25165 .RE
25166 .RS 4
25167 .RE
25168 .ie n .IP """sv_unmagic""" 4
25169 .el .IP \f(CWsv_unmagic\fR 4
25170 .IX Xref "sv_unmagic"
25171 .IX Item "sv_unmagic"
25172 Removes all magic of type \f(CW\*(C`type\*(C'\fR from an SV.
25173 .RS 4
25174 .Sp
25175 .Vb 2
25176 \& int sv_unmagic( SV * const sv, const int type)
25177 \& int Perl_sv_unmagic(pTHX_ SV * const sv, const int type)
25178 .Ve
25179 .RE
25180 .RS 4
25181 .RE
25182 .ie n .IP """sv_unmagicext""" 4
25183 .el .IP \f(CWsv_unmagicext\fR 4
25184 .IX Xref "sv_unmagicext"
25185 .IX Item "sv_unmagicext"
25186 Removes all magic of type \f(CW\*(C`type\*(C'\fR with the specified \f(CW\*(C`vtbl\*(C'\fR from an SV.
25187 .RS 4
25188 .Sp
25189 .Vb 4
25190 \& int sv_unmagicext( SV * const sv, const int type,
25191 \& const MGVTBL *vtbl)
25192 \& int Perl_sv_unmagicext(pTHX_ SV * const sv, const int type,
25193 \& const MGVTBL *vtbl)
25194 .Ve
25195 .RE
25196 .RS 4
25197 .RE
25198 .ie n .IP """sv_unref""" 4
25199 .el .IP \f(CWsv_unref\fR 4
25200 .IX Item "sv_unref"
25201 .PD 0
25202 .ie n .IP """sv_unref_flags""" 4
25203 .el .IP \f(CWsv_unref_flags\fR 4
25204 .IX Xref "sv_unref sv_unref_flags"
25205 .IX Item "sv_unref_flags"
25206 .PD
25207 These each unset the RV status of the SV, and decrement the reference count of
25208 whatever was being referenced by the RV. This can almost be thought of
25209 as a reversal of \f(CW"newSVrv"\fR.
25210 .Sp
25211 \&\f(CW\*(C`sv_unref_flags\*(C'\fR has an extra parameter, \f(CW\*(C`flags\*(C'\fR, which can contain
25212 the \f(CW\*(C`SV_IMMEDIATE_UNREF\*(C'\fR bit to force the reference count to be decremented
25213 no matter what.
25214 .Sp
25215 When that bit isn\*(Aqt set, or with plain \f(CW\*(C`sv_unref\*(C'\fR always, the reference count
25216 will not be immediately decremented if the count is 1. Instead, it will be
25217 scheduled to be freed at a time of perl\*(Aqs choosing.
25218 .Sp
25219 Other than the ability to force immediate action, the two forms behave
25220 identically.
25221 .Sp
25222 See \f(CW"SvROK_off"\fR.
25223 .RS 4
25224 .Sp
25225 .Vb 4
25226 \& void sv_unref ( SV *sv)
25227 \& void Perl_sv_unref (pTHX_ SV *sv)
25228 \& void sv_unref_flags( SV * const ref, const U32 flags)
25229 \& void Perl_sv_unref_flags(pTHX_ SV * const ref, const U32 flags)
25230 .Ve
25231 .RE
25232 .RS 4
25233 .RE
25234 .ie n .IP """sv_upgrade""" 4
25235 .el .IP \f(CWsv_upgrade\fR 4
25236 .IX Xref "sv_upgrade"
25237 .IX Item "sv_upgrade"
25238 Upgrade an SV to a more complex form. Generally adds a new body type to the
25239 SV, then copies across as much information as possible from the old body.
25240 It croaks if the SV is already in a more complex form than requested. You
25241 generally want to use the \f(CW\*(C`SvUPGRADE\*(C'\fR macro wrapper, which checks the type
25242 before calling \f(CW\*(C`sv_upgrade\*(C'\fR, and hence does not croak. See also
25243 \&\f(CW"svtype"\fR.
25244 .RS 4
25245 .Sp
25246 .Vb 2
25247 \& void sv_upgrade( SV * const sv, svtype new_type)
25248 \& void Perl_sv_upgrade(pTHX_ SV * const sv, svtype new_type)
25249 .Ve
25250 .RE
25251 .RS 4
25252 .RE
25253 .ie n .IP """sv_usepvn""" 4
25254 .el .IP \f(CWsv_usepvn\fR 4
25255 .IX Item "sv_usepvn"
25256 .PD 0
25257 .ie n .IP """sv_usepvn_flags""" 4
25258 .el .IP \f(CWsv_usepvn_flags\fR 4
25259 .IX Item "sv_usepvn_flags"
25260 .ie n .IP """sv_usepvn_mg""" 4
25261 .el .IP \f(CWsv_usepvn_mg\fR 4
25262 .IX Xref "sv_usepvn sv_usepvn_flags sv_usepvn_mg"
25263 .IX Item "sv_usepvn_mg"
25264 .PD
25265 These tell an SV to use \f(CW\*(C`ptr\*(C'\fR for its string value. Normally SVs have
25266 their string stored inside the SV, but these tell the SV to use an
25267 external string instead.
25268 .Sp
25269 \&\f(CW\*(C`ptr\*(C'\fR should point to memory that was allocated
25270 by "\f(CW\*(C`Newx\*(C'\fR". It must be
25271 the start of a \f(CW\*(C`Newx\*(C'\fR\-ed block of memory, and not a pointer to the
25272 middle of it (beware of \f(CW\*(C`OOK\*(C'\fR and copy\-on\-write),
25273 and not be from a non\-\f(CW\*(C`Newx\*(C'\fR memory allocator like \f(CW\*(C`malloc\*(C'\fR. The
25274 string length, \f(CW\*(C`len\*(C'\fR, must be supplied. By default this function
25275 will "\f(CW\*(C`Renew\*(C'\fR" (i.e. realloc, move) the memory pointed to by \f(CW\*(C`ptr\*(C'\fR,
25276 so that the pointer should not be freed or used by the programmer after giving
25277 it to \f(CW\*(C`sv_usepvn\*(C'\fR, and neither should any pointers from "behind" that pointer
25278 (\fIe.g.\fR, \f(CW\*(C`ptr\*(C'\fR\ +\ 1) be used.
25279 .Sp
25280 In the \f(CW\*(C`sv_usepvn_flags\*(C'\fR form, if \f(CW\*(C`flags\ &\ SV_SMAGIC\*(C'\fR is true,
25281 \&\f(CW\*(C`SvSETMAGIC\*(C'\fR is called before returning.
25282 And if \f(CW\*(C`flags\ &\ SV_HAS_TRAILING_NUL\*(C'\fR is true, then \f(CW\*(C`ptr[len]\*(C'\fR must be
25283 \&\f(CW\*(C`NUL\*(C'\fR, and the realloc will be skipped (\fIi.e.\fR, the buffer is actually at
25284 least 1 byte longer than \f(CW\*(C`len\*(C'\fR, and already meets the requirements for storing
25285 in \f(CW\*(C`SvPVX\*(C'\fR).
25286 .Sp
25287 \&\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 \*(Aqset\*(Aq
25288 magic is skipped.
25289 .Sp
25290 \&\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,
25291 so \*(Aqset\*(Aq magic is performed.
25292 .RS 4
25293 .Sp
25294 .Vb 10
25295 \& void sv_usepvn ( SV *sv, char *ptr, STRLEN len)
25296 \& void Perl_sv_usepvn (pTHX_ SV *sv, char *ptr, STRLEN len)
25297 \& void sv_usepvn_flags( SV * const sv, char *ptr,
25298 \& const STRLEN len,
25299 \& const U32 flags)
25300 \& void Perl_sv_usepvn_flags(pTHX_ SV * const sv, char *ptr,
25301 \& const STRLEN len,
25302 \& const U32 flags)
25303 \& void sv_usepvn_mg ( SV *sv, char *ptr, STRLEN len)
25304 \& void Perl_sv_usepvn_mg (pTHX_ SV *sv, char *ptr, STRLEN len)
25305 .Ve
25306 .RE
25307 .RS 4
25308 .RE
25309 .ie n .IP """sv_utf8_decode""" 4
25310 .el .IP \f(CWsv_utf8_decode\fR 4
25311 .IX Xref "sv_utf8_decode"
25312 .IX Item "sv_utf8_decode"
25313 If the PV of the SV is an octet sequence in Perl\*(Aqs extended UTF\-8
25314 and contains a multiple\-byte character, the \f(CW\*(C`SvUTF8\*(C'\fR flag is turned on
25315 so that it looks like a character. If the PV contains only single\-byte
25316 characters, the \f(CW\*(C`SvUTF8\*(C'\fR flag stays off.
25317 Scans PV for validity and returns FALSE if the PV is invalid UTF\-8.
25318 .RS 4
25319 .Sp
25320 .Vb 2
25321 \& bool sv_utf8_decode( SV * const sv)
25322 \& bool Perl_sv_utf8_decode(pTHX_ SV * const sv)
25323 .Ve
25324 .RE
25325 .RS 4
25326 .RE
25327 .ie n .IP """sv_utf8_downgrade""" 4
25328 .el .IP \f(CWsv_utf8_downgrade\fR 4
25329 .IX Item "sv_utf8_downgrade"
25330 .PD 0
25331 .ie n .IP """sv_utf8_downgrade_flags""" 4
25332 .el .IP \f(CWsv_utf8_downgrade_flags\fR 4
25333 .IX Item "sv_utf8_downgrade_flags"
25334 .ie n .IP """sv_utf8_downgrade_nomg""" 4
25335 .el .IP \f(CWsv_utf8_downgrade_nomg\fR 4
25336 .IX Xref "sv_utf8_downgrade sv_utf8_downgrade_flags sv_utf8_downgrade_nomg"
25337 .IX Item "sv_utf8_downgrade_nomg"
25338 .PD
25339 These attempt to convert the PV of an SV from characters to bytes. If the PV
25340 contains a character that cannot fit in a byte, this conversion will fail; in
25341 this case, \f(CW\*(C`FALSE\*(C'\fR is returned if \f(CW\*(C`fail_ok\*(C'\fR is true; otherwise they croak.
25342 .Sp
25343 They are not a general purpose Unicode to byte encoding interface:
25344 use the \f(CW\*(C`Encode\*(C'\fR extension for that.
25345 .Sp
25346 They differ only in that:
25347 .Sp
25348 \&\f(CW\*(C`sv_utf8_downgrade\*(C'\fR processes \*(Aqget\*(Aq magic on \f(CW\*(C`sv\*(C'\fR.
25349 .Sp
25350 \&\f(CW\*(C`sv_utf8_downgrade_nomg\*(C'\fR does not.
25351 .Sp
25352 \&\f(CW\*(C`sv_utf8_downgrade_flags\*(C'\fR has an additional \f(CW\*(C`flags\*(C'\fR parameter in which you can specify
25353 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR to process \*(Aqget\*(Aq magic, or leave it cleared to not process \*(Aqget\*(Aq magic.
25354 .RS 4
25355 .Sp
25356 .Vb 12
25357 \& bool sv_utf8_downgrade ( SV * const sv,
25358 \& const bool fail_ok)
25359 \& bool Perl_sv_utf8_downgrade (pTHX_ SV * const sv,
25360 \& const bool fail_ok)
25361 \& bool sv_utf8_downgrade_flags( SV * const sv,
25362 \& const bool fail_ok,
25363 \& const U32 flags)
25364 \& bool Perl_sv_utf8_downgrade_flags(pTHX_ SV * const sv,
25365 \& const bool fail_ok,
25366 \& const U32 flags)
25367 \& bool sv_utf8_downgrade_nomg ( SV * const sv,
25368 \& const bool fail_ok)
25369 .Ve
25370 .RE
25371 .RS 4
25372 .RE
25373 .ie n .IP """sv_utf8_encode""" 4
25374 .el .IP \f(CWsv_utf8_encode\fR 4
25375 .IX Xref "sv_utf8_encode"
25376 .IX Item "sv_utf8_encode"
25377 Converts the PV of an SV to UTF\-8, but then turns the \f(CW\*(C`SvUTF8\*(C'\fR
25378 flag off so that it looks like octets again.
25379 .RS 4
25380 .Sp
25381 .Vb 2
25382 \& void sv_utf8_encode( SV * const sv)
25383 \& void Perl_sv_utf8_encode(pTHX_ SV * const sv)
25384 .Ve
25385 .RE
25386 .RS 4
25387 .RE
25388 .ie n .IP """sv_utf8_upgrade""" 4
25389 .el .IP \f(CWsv_utf8_upgrade\fR 4
25390 .IX Item "sv_utf8_upgrade"
25391 .PD 0
25392 .ie n .IP """sv_utf8_upgrade_flags""" 4
25393 .el .IP \f(CWsv_utf8_upgrade_flags\fR 4
25394 .IX Item "sv_utf8_upgrade_flags"
25395 .ie n .IP """sv_utf8_upgrade_flags_grow""" 4
25396 .el .IP \f(CWsv_utf8_upgrade_flags_grow\fR 4
25397 .IX Item "sv_utf8_upgrade_flags_grow"
25398 .ie n .IP """sv_utf8_upgrade_nomg""" 4
25399 .el .IP \f(CWsv_utf8_upgrade_nomg\fR 4
25400 .IX Xref "sv_utf8_upgrade sv_utf8_upgrade_flags sv_utf8_upgrade_flags_grow sv_utf8_upgrade_nomg"
25401 .IX Item "sv_utf8_upgrade_nomg"
25402 .PD
25403 These convert the PV of an SV to its UTF\-8\-encoded form.
25404 The SV is forced to string form if it is not already.
25405 They always set the \f(CW\*(C`SvUTF8\*(C'\fR flag to avoid future validity checks even if the
25406 whole string is the same in UTF\-8 as not.
25407 They return the number of bytes in the converted string
25408 .Sp
25409 The forms differ in just two ways. The main difference is whether or not they
25410 perform \*(Aqget magic\*(Aq on \f(CW\*(C`sv\*(C'\fR. \f(CW\*(C`sv_utf8_upgrade_nomg\*(C'\fR skips \*(Aqget magic\*(Aq;
25411 \&\f(CW\*(C`sv_utf8_upgrade\*(C'\fR performs it; and \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR and
25412 \&\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
25413 in \f(CW\*(C`flags\*(C'\fR) or don\*(Aqt (if that bit is cleared).
25414 .Sp
25415 The other difference is that \f(CW\*(C`sv_utf8_upgrade_flags_grow\*(C'\fR has an additional
25416 parameter, \f(CW\*(C`extra\*(C'\fR, which allows the caller to specify an amount of space to
25417 be reserved as spare beyond what is needed for the actual conversion. This is
25418 used when the caller knows it will soon be needing yet more space, and it is
25419 more efficient to request space from the system in a single call.
25420 This form is otherwise identical to \f(CW\*(C`sv_utf8_upgrade_flags\*(C'\fR.
25421 .Sp
25422 These are not a general purpose byte encoding to Unicode interface: use the
25423 Encode extension for that.
25424 .Sp
25425 The \f(CW\*(C`SV_FORCE_UTF8_UPGRADE\*(C'\fR flag is now ignored.
25426 .RS 4
25427 .Sp
25428 .Vb 11
25429 \& STRLEN sv_utf8_upgrade ( SV *sv)
25430 \& STRLEN Perl_sv_utf8_upgrade (pTHX_ SV *sv)
25431 \& STRLEN sv_utf8_upgrade_flags ( SV * const sv,
25432 \& const I32 flags)
25433 \& STRLEN sv_utf8_upgrade_flags_grow( SV * const sv,
25434 \& const I32 flags,
25435 \& STRLEN extra)
25436 \& STRLEN Perl_sv_utf8_upgrade_flags_grow(pTHX_ SV * const sv,
25437 \& const I32 flags,
25438 \& STRLEN extra)
25439 \& STRLEN sv_utf8_upgrade_nomg ( SV *sv)
25440 .Ve
25441 .RE
25442 .RS 4
25443 .RE
25444 .ie n .IP """sv_vcatpvf*""" 4
25445 .el .IP \f(CWsv_vcatpvf*\fR 4
25446 .IX Item "sv_vcatpvf*"
25447 .PD 0
25448 .ie n .IP """sv_vcatpvf_mg*""" 4
25449 .el .IP \f(CWsv_vcatpvf_mg*\fR 4
25450 .IX Item "sv_vcatpvf_mg*"
25451 .ie n .IP """sv_vcatpvfn*""" 4
25452 .el .IP \f(CWsv_vcatpvfn*\fR 4
25453 .IX Item "sv_vcatpvfn*"
25454 .ie n .IP """sv_vcatpvfn_flags*""" 4
25455 .el .IP \f(CWsv_vcatpvfn_flags*\fR 4
25456 .IX Item "sv_vcatpvfn_flags*"
25457 .PD
25458 Described under \f(CW"sv_catpvf"\fR
25459 .ie n .IP """sv_vsetpvf""" 4
25460 .el .IP \f(CWsv_vsetpvf\fR 4
25461 .IX Item "sv_vsetpvf"
25462 .PD 0
25463 .ie n .IP """sv_vsetpvf_mg""" 4
25464 .el .IP \f(CWsv_vsetpvf_mg\fR 4
25465 .IX Xref "sv_vsetpvf sv_vsetpvf_mg"
25466 .IX Item "sv_vsetpvf_mg"
25467 .PD
25468 These work like \f(CW"sv_vcatpvf"\fR but copy the text into the SV instead of
25469 appending it.
25470 .Sp
25471 They differ only in that \f(CW\*(C`sv_vsetpvf_mg\*(C'\fR performs \*(Aqset\*(Aq magic;
25472 \&\f(CW\*(C`sv_vsetpvf\*(C'\fR skips all magic.
25473 .Sp
25474 They are usually used via their frontends, \f(CW"sv_setpvf"\fR and
25475 \&\f(CW"sv_setpvf_mg"\fR.
25476 .Sp
25477 \&\fBThe UTF\-8 flag is not changed by these functions.\fR
25478 .RS 4
25479 .Sp
25480 .Vb 12
25481 \& void sv_vsetpvf ( SV * const sv,
25482 \& const char * const pat,
25483 \& va_list * const args)
25484 \& void Perl_sv_vsetpvf (pTHX_ SV * const sv,
25485 \& const char * const pat,
25486 \& va_list * const args)
25487 \& void sv_vsetpvf_mg( SV * const sv,
25488 \& const char * const pat,
25489 \& va_list * const args)
25490 \& void Perl_sv_vsetpvf_mg(pTHX_ SV * const sv,
25491 \& const char * const pat,
25492 \& va_list * const args)
25493 .Ve
25494 .RE
25495 .RS 4
25496 .RE
25497 .ie n .IP """sv_vsetpvfn""" 4
25498 .el .IP \f(CWsv_vsetpvfn\fR 4
25499 .IX Xref "sv_vsetpvfn"
25500 .IX Item "sv_vsetpvfn"
25501 Works like \f(CW\*(C`sv_vcatpvfn\*(C'\fR but copies the text into the SV instead of
25502 appending it.
25503 .Sp
25504 \&\fBThe UTF\-8 flag is not changed by this function.\fR
25505 .Sp
25506 Usually used via one of its frontends "\f(CW\*(C`sv_vsetpvf\*(C'\fR" and
25507 "\f(CW\*(C`sv_vsetpvf_mg\*(C'\fR".
25508 .RS 4
25509 .Sp
25510 .Vb 10
25511 \& void sv_vsetpvfn( SV * const sv,
25512 \& const char * const pat,
25513 \& const STRLEN patlen,
25514 \& va_list * const args,
25515 \& SV ** const svargs,
25516 \& const Size_t sv_count,
25517 \& bool * const maybe_tainted)
25518 \& void Perl_sv_vsetpvfn(pTHX_ SV * const sv,
25519 \& const char * const pat,
25520 \& const STRLEN patlen,
25521 \& va_list * const args,
25522 \& SV ** const svargs,
25523 \& const Size_t sv_count,
25524 \& bool * const maybe_tainted)
25525 .Ve
25526 .RE
25527 .RS 4
25528 .RE
25529 .ie n .IP """sv_2cv""" 4
25530 .el .IP \f(CWsv_2cv\fR 4
25531 .IX Xref "sv_2cv"
25532 .IX Item "sv_2cv"
25533 Using various gambits, try to get a CV from an SV; in addition, try if
25534 possible to set \f(CW*st\fR and \f(CW*gvp\fR to the stash and GV associated with it.
25535 The flags in \f(CW\*(C`lref\*(C'\fR are passed to \f(CW\*(C`gv_fetchsv\*(C'\fR.
25536 .RS 4
25537 .Sp
25538 .Vb 4
25539 \& CV * sv_2cv( SV *sv, HV ** const st, GV ** const gvp,
25540 \& const I32 lref)
25541 \& CV * Perl_sv_2cv(pTHX_ SV *sv, HV ** const st, GV ** const gvp,
25542 \& const I32 lref)
25543 .Ve
25544 .RE
25545 .RS 4
25546 .RE
25547 .ie n .IP """sv_2io""" 4
25548 .el .IP \f(CWsv_2io\fR 4
25549 .IX Xref "sv_2io"
25550 .IX Item "sv_2io"
25551 Using various gambits, try to get an IO from an SV: the IO slot if its a
25552 GV; or the recursive result if we\*(Aqre an RV; or the IO slot of the symbol
25553 named after the PV if we\*(Aqre a string.
25554 .Sp
25555 \&\*(AqGet\*(Aq magic is ignored on the \f(CW\*(C`sv\*(C'\fR passed in, but will be called on
25556 \&\f(CWSvRV(sv)\fR if \f(CW\*(C`sv\*(C'\fR is an RV.
25557 .RS 4
25558 .Sp
25559 .Vb 2
25560 \& IO * sv_2io( SV * const sv)
25561 \& IO * Perl_sv_2io(pTHX_ SV * const sv)
25562 .Ve
25563 .RE
25564 .RS 4
25565 .RE
25566 .ie n .IP """sv_2iv_flags""" 4
25567 .el .IP \f(CWsv_2iv_flags\fR 4
25568 .IX Xref "sv_2iv_flags"
25569 .IX Item "sv_2iv_flags"
25570 Return the integer value of an SV, doing any necessary string
25571 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.
25572 Normally used via the \f(CWSvIV(sv)\fR and \f(CWSvIVx(sv)\fR macros.
25573 .RS 4
25574 .Sp
25575 .Vb 2
25576 \& IV sv_2iv_flags( SV * const sv, const I32 flags)
25577 \& IV Perl_sv_2iv_flags(pTHX_ SV * const sv, const I32 flags)
25578 .Ve
25579 .RE
25580 .RS 4
25581 .RE
25582 .ie n .IP """sv_2mortal""" 4
25583 .el .IP \f(CWsv_2mortal\fR 4
25584 .IX Xref "sv_2mortal"
25585 .IX Item "sv_2mortal"
25586 Marks an existing SV as mortal. The SV will be destroyed "soon", either
25587 by an explicit call to \f(CW\*(C`FREETMPS\*(C'\fR, or by an implicit call at places such as
25588 statement boundaries. \f(CWSvTEMP()\fR is turned on which means that the SV\*(Aqs
25589 string buffer can be "stolen" if this SV is copied. See also
25590 \&\f(CW"sv_newmortal"\fR and \f(CW"sv_mortalcopy"\fR.
25591 .RS 4
25592 .Sp
25593 .Vb 2
25594 \& SV * sv_2mortal( SV * const sv)
25595 \& SV * Perl_sv_2mortal(pTHX_ SV * const sv)
25596 .Ve
25597 .RE
25598 .RS 4
25599 .RE
25600 .ie n .IP """sv_2nv_flags""" 4
25601 .el .IP \f(CWsv_2nv_flags\fR 4
25602 .IX Xref "sv_2nv_flags"
25603 .IX Item "sv_2nv_flags"
25604 Return the num value of an SV, doing any necessary string or integer
25605 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.
25606 Normally used via the \f(CWSvNV(sv)\fR and \f(CWSvNVx(sv)\fR macros.
25607 .RS 4
25608 .Sp
25609 .Vb 2
25610 \& NV sv_2nv_flags( SV * const sv, const I32 flags)
25611 \& NV Perl_sv_2nv_flags(pTHX_ SV * const sv, const I32 flags)
25612 .Ve
25613 .RE
25614 .RS 4
25615 .RE
25616 .ie n .IP """sv_2pv""" 4
25617 .el .IP \f(CWsv_2pv\fR 4
25618 .IX Item "sv_2pv"
25619 .PD 0
25620 .ie n .IP """sv_2pv_flags""" 4
25621 .el .IP \f(CWsv_2pv_flags\fR 4
25622 .IX Xref "sv_2pv sv_2pv_flags"
25623 .IX Item "sv_2pv_flags"
25624 .PD
25625 These implement the various forms of the "\f(CW\*(C`SvPV\*(C'\fR" in perlapi macros.
25626 The macros are the preferred interface.
25627 .Sp
25628 These return a pointer to the string value of an SV (coercing it to a string if
25629 necessary), and set \f(CW*lp\fR to its length in bytes.
25630 .Sp
25631 The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes \*(Aqget\*(Aq magic; and
25632 \&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes \*(Aqget\*(Aq magic if and only if \f(CW\*(C`flags\*(C'\fR contains
25633 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
25634 .RS 4
25635 .Sp
25636 .Vb 6
25637 \& char * sv_2pv ( SV *sv, STRLEN *lp)
25638 \& char * Perl_sv_2pv (pTHX_ SV *sv, STRLEN *lp)
25639 \& char * sv_2pv_flags( SV * const sv, STRLEN * const lp,
25640 \& const U32 flags)
25641 \& char * Perl_sv_2pv_flags(pTHX_ SV * const sv, STRLEN * const lp,
25642 \& const U32 flags)
25643 .Ve
25644 .RE
25645 .RS 4
25646 .RE
25647 .ie n .IP """sv_2pvbyte""" 4
25648 .el .IP \f(CWsv_2pvbyte\fR 4
25649 .IX Item "sv_2pvbyte"
25650 .PD 0
25651 .ie n .IP """sv_2pvbyte_flags""" 4
25652 .el .IP \f(CWsv_2pvbyte_flags\fR 4
25653 .IX Xref "sv_2pvbyte sv_2pvbyte_flags"
25654 .IX Item "sv_2pvbyte_flags"
25655 .PD
25656 These implement the various forms of the "\f(CW\*(C`SvPVbyte\*(C'\fR" in perlapi macros.
25657 The macros are the preferred interface.
25658 .Sp
25659 These return a pointer to the byte\-encoded representation of the SV, and set
25660 \&\f(CW*lp\fR to its length. If the SV is marked as being encoded as UTF\-8, it will
25661 be downgraded, if possible, to a byte string. If the SV cannot be downgraded,
25662 they croak.
25663 .Sp
25664 The forms differ in that plain \f(CW\*(C`sv_2pvbyte\*(C'\fR always processes \*(Aqget\*(Aq magic; and
25665 \&\f(CW\*(C`sv_2pvbyte_flags\*(C'\fR processes \*(Aqget\*(Aq magic if and only if \f(CW\*(C`flags\*(C'\fR contains
25666 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
25667 .RS 4
25668 .Sp
25669 .Vb 6
25670 \& char * sv_2pvbyte ( SV *sv, STRLEN * const lp)
25671 \& char * Perl_sv_2pvbyte (pTHX_ SV *sv, STRLEN * const lp)
25672 \& char * sv_2pvbyte_flags( SV *sv, STRLEN * const lp,
25673 \& const U32 flags)
25674 \& char * Perl_sv_2pvbyte_flags(pTHX_ SV *sv, STRLEN * const lp,
25675 \& const U32 flags)
25676 .Ve
25677 .RE
25678 .RS 4
25679 .RE
25680 .ie n .IP """sv_2pvutf8""" 4
25681 .el .IP \f(CWsv_2pvutf8\fR 4
25682 .IX Item "sv_2pvutf8"
25683 .PD 0
25684 .ie n .IP """sv_2pvutf8_flags""" 4
25685 .el .IP \f(CWsv_2pvutf8_flags\fR 4
25686 .IX Xref "sv_2pvutf8 sv_2pvutf8_flags"
25687 .IX Item "sv_2pvutf8_flags"
25688 .PD
25689 These implement the various forms of the "\f(CW\*(C`SvPVutf8\*(C'\fR" in perlapi macros.
25690 The macros are the preferred interface.
25691 .Sp
25692 These return a pointer to the UTF\-8\-encoded representation of the SV, and set
25693 \&\f(CW*lp\fR to its length in bytes. They may cause the SV to be upgraded to UTF\-8
25694 as a side\-effect.
25695 .Sp
25696 The forms differ in that plain \f(CW\*(C`sv_2pvutf8\*(C'\fR always processes \*(Aqget\*(Aq magic; and
25697 \&\f(CW\*(C`sv_2pvutf8_flags\*(C'\fR processes \*(Aqget\*(Aq magic if and only if \f(CW\*(C`flags\*(C'\fR contains
25698 \&\f(CW\*(C`SV_GMAGIC\*(C'\fR.
25699 .RS 4
25700 .Sp
25701 .Vb 6
25702 \& char * sv_2pvutf8 ( SV *sv, STRLEN * const lp)
25703 \& char * Perl_sv_2pvutf8 (pTHX_ SV *sv, STRLEN * const lp)
25704 \& char * sv_2pvutf8_flags( SV *sv, STRLEN * const lp,
25705 \& const U32 flags)
25706 \& char * Perl_sv_2pvutf8_flags(pTHX_ SV *sv, STRLEN * const lp,
25707 \& const U32 flags)
25708 .Ve
25709 .RE
25710 .RS 4
25711 .RE
25712 .ie n .IP """sv_2uv_flags""" 4
25713 .el .IP \f(CWsv_2uv_flags\fR 4
25714 .IX Xref "sv_2uv_flags"
25715 .IX Item "sv_2uv_flags"
25716 Return the unsigned integer value of an SV, doing any necessary string
25717 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.
25718 Normally used via the \f(CWSvUV(sv)\fR and \f(CWSvUVx(sv)\fR macros.
25719 .RS 4
25720 .Sp
25721 .Vb 2
25722 \& UV sv_2uv_flags( SV * const sv, const I32 flags)
25723 \& UV Perl_sv_2uv_flags(pTHX_ SV * const sv, const I32 flags)
25724 .Ve
25725 .RE
25726 .RS 4
25727 .RE
25728 .ie n .IP """SvAMAGIC""" 4
25729 .el .IP \f(CWSvAMAGIC\fR 4
25730 .IX Xref "SvAMAGIC"
25731 .IX Item "SvAMAGIC"
25732 Returns a boolean as to whether \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled or
25733 not.
25734 .RS 4
25735 .Sp
25736 .Vb 1
25737 \& bool SvAMAGIC(SV * sv)
25738 .Ve
25739 .RE
25740 .RS 4
25741 .RE
25742 .ie n .IP """SvAMAGIC_off""" 4
25743 .el .IP \f(CWSvAMAGIC_off\fR 4
25744 .IX Xref "SvAMAGIC_off"
25745 .IX Item "SvAMAGIC_off"
25746 Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) disabled.
25747 .RS 4
25748 .Sp
25749 .Vb 2
25750 \& void SvAMAGIC_off(SV *sv)
25751 \& void Perl_SvAMAGIC_off(SV *sv)
25752 .Ve
25753 .RE
25754 .RS 4
25755 .RE
25756 .ie n .IP """SvAMAGIC_on""" 4
25757 .el .IP \f(CWSvAMAGIC_on\fR 4
25758 .IX Xref "SvAMAGIC_on"
25759 .IX Item "SvAMAGIC_on"
25760 Indicate that \f(CW\*(C`sv\*(C'\fR has overloading (active magic) enabled.
25761 .RS 4
25762 .Sp
25763 .Vb 2
25764 \& void SvAMAGIC_on(SV *sv)
25765 \& void Perl_SvAMAGIC_on(SV *sv)
25766 .Ve
25767 .RE
25768 .RS 4
25769 .RE
25770 .ie n .IP """SvBoolFlagsOK""" 4
25771 .el .IP \f(CWSvBoolFlagsOK\fR 4
25772 .IX Xref "SvBoolFlagsOK"
25773 .IX Item "SvBoolFlagsOK"
25774 Returns a bool indicating whether the SV has the right flags set such
25775 that it is safe to call \f(CWBOOL_INTERNALS_sv_isbool()\fR or
25776 \&\f(CWBOOL_INTERNALS_sv_isbool_true()\fR or
25777 \&\f(CWBOOL_INTERNALS_sv_isbool_false()\fR. Currently equivalent to
25778 \&\f(CWSvIandPOK(sv)\fR or \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR. Serialization may want to
25779 unroll this check. If so you are strongly recommended to add code like
25780 \&\f(CW\*(C`assert(SvBoolFlagsOK(sv));\*(C'\fR \fBbefore\fR calling using any of the
25781 BOOL_INTERNALS macros.
25782 .RS 4
25783 .Sp
25784 .Vb 1
25785 \& U32 SvBoolFlagsOK(SV* sv)
25786 .Ve
25787 .RE
25788 .RS 4
25789 .RE
25790 .ie n .IP """SvCUR""" 4
25791 .el .IP \f(CWSvCUR\fR 4
25792 .IX Xref "SvCUR"
25793 .IX Item "SvCUR"
25794 Returns the length, in bytes, of the PV inside the SV.
25795 Note that this may not match Perl\*(Aqs \f(CW\*(C`length\*(C'\fR; for that, use
25796 \&\f(CWsv_len_utf8(sv)\fR. See \f(CW"SvLEN"\fR also.
25797 .RS 4
25798 .Sp
25799 .Vb 1
25800 \& STRLEN SvCUR(SV* sv)
25801 .Ve
25802 .RE
25803 .RS 4
25804 .RE
25805 .ie n .IP """SvCUR_set""" 4
25806 .el .IP \f(CWSvCUR_set\fR 4
25807 .IX Xref "SvCUR_set"
25808 .IX Item "SvCUR_set"
25809 Sets the current length, in bytes, of the C string which is in the SV.
25810 See \f(CW"SvCUR"\fR and \f(CW\*(C`SvIV_set\*(C'\fR>.
25811 .RS 4
25812 .Sp
25813 .Vb 1
25814 \& void SvCUR_set(SV* sv, STRLEN len)
25815 .Ve
25816 .RE
25817 .RS 4
25818 .RE
25819 .ie n .IP """SvEND""" 4
25820 .el .IP \f(CWSvEND\fR 4
25821 .IX Xref "SvEND"
25822 .IX Item "SvEND"
25823 Returns a pointer to the spot just after the last character in
25824 the string which is in the SV, where there is usually a trailing
25825 \&\f(CW\*(C`NUL\*(C'\fR character (even though Perl scalars do not strictly require it).
25826 See \f(CW"SvCUR"\fR. Access the character as \f(CW\*(C`*(SvEND(sv))\*(C'\fR.
25827 .Sp
25828 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
25829 unallocated memory.
25830 .RS 4
25831 .Sp
25832 .Vb 1
25833 \& char* SvEND(SV* sv)
25834 .Ve
25835 .RE
25836 .RS 4
25837 .RE
25838 .ie n .IP """SvGAMAGIC""" 4
25839 .el .IP \f(CWSvGAMAGIC\fR 4
25840 .IX Xref "SvGAMAGIC"
25841 .IX Item "SvGAMAGIC"
25842 Returns true if the SV has get magic or
25843 overloading. If either is true then
25844 the scalar is active data, and has the potential to return a new value every
25845 time it is accessed. Hence you must be careful to
25846 only read it once per user logical operation and work
25847 with that returned value. If neither is true then
25848 the scalar\*(Aqs value cannot change unless written to.
25849 .RS 4
25850 .Sp
25851 .Vb 1
25852 \& U32 SvGAMAGIC(SV* sv)
25853 .Ve
25854 .RE
25855 .RS 4
25856 .RE
25857 .ie n .IP """SvGETMAGIC""" 4
25858 .el .IP \f(CWSvGETMAGIC\fR 4
25859 .IX Xref "SvGETMAGIC"
25860 .IX Item "SvGETMAGIC"
25861 Invokes \f(CW"mg_get"\fR on an SV if it has \*(Aqget\*(Aq magic. For example, this
25862 will call \f(CW\*(C`FETCH\*(C'\fR on a tied variable. As of 5.37.1, this function is
25863 guaranteed to evaluate its argument exactly once.
25864 .RS 4
25865 .Sp
25866 .Vb 2
25867 \& void SvGETMAGIC( SV *sv)
25868 \& void Perl_SvGETMAGIC(pTHX_ SV *sv)
25869 .Ve
25870 .RE
25871 .RS 4
25872 .RE
25873 .ie n .IP """SvGROW""" 4
25874 .el .IP \f(CWSvGROW\fR 4
25875 .IX Xref "SvGROW"
25876 .IX Item "SvGROW"
25877 Expands the character buffer in the SV so that it has room for the
25878 indicated number of bytes (remember to reserve space for an extra trailing
25879 \&\f(CW\*(C`NUL\*(C'\fR character). Calls \f(CW\*(C`sv_grow\*(C'\fR to perform the expansion if necessary.
25880 Returns a pointer to the character
25881 buffer. SV must be of type >= \f(CW\*(C`SVt_PV\*(C'\fR. One
25882 alternative is to call \f(CW\*(C`sv_grow\*(C'\fR if you are not sure of the type of SV.
25883 .Sp
25884 You might mistakenly think that \f(CW\*(C`len\*(C'\fR is the number of bytes to add to the
25885 existing size, but instead it is the total size \f(CW\*(C`sv\*(C'\fR should be.
25886 .RS 4
25887 .Sp
25888 .Vb 1
25889 \& char * SvGROW(SV* sv, STRLEN len)
25890 .Ve
25891 .RE
25892 .RS 4
25893 .RE
25894 .ie n .IP """SvIandPOK""" 4
25895 .el .IP \f(CWSvIandPOK\fR 4
25896 .IX Xref "SvIandPOK"
25897 .IX Item "SvIandPOK"
25898 Returns a bool indicating whether the SV is both \f(CWSvPOK()\fR and
25899 \&\f(CWSvIOK()\fR at the same time. Equivalent to \f(CW\*(C`SvIOK(sv) && SvPOK(sv)\*(C'\fR but
25900 more efficient.
25901 .RS 4
25902 .Sp
25903 .Vb 1
25904 \& U32 SvIandPOK(SV* sv)
25905 .Ve
25906 .RE
25907 .RS 4
25908 .RE
25909 .ie n .IP """SvIandPOK_off""" 4
25910 .el .IP \f(CWSvIandPOK_off\fR 4
25911 .IX Xref "SvIandPOK_off"
25912 .IX Item "SvIandPOK_off"
25913 Unsets the PV and IV status of an SV in one operation. Equivalent to
25914 \&\f(CW\*(C`SvIOK_off(sv); SvPK_off(v);\*(C'\fR but more efficient.
25915 .RS 4
25916 .Sp
25917 .Vb 1
25918 \& void SvIandPOK_off(SV* sv)
25919 .Ve
25920 .RE
25921 .RS 4
25922 .RE
25923 .ie n .IP """SvIandPOK_on""" 4
25924 .el .IP \f(CWSvIandPOK_on\fR 4
25925 .IX Xref "SvIandPOK_on"
25926 .IX Item "SvIandPOK_on"
25927 Tells an SV that is a string and a number in one operation. Equivalent
25928 to \f(CW\*(C`SvIOK_on(sv); SvPOK_on(sv);\*(C'\fR but more efficient.
25929 .RS 4
25930 .Sp
25931 .Vb 1
25932 \& void SvIandPOK_on(SV* sv)
25933 .Ve
25934 .RE
25935 .RS 4
25936 .RE
25937 .ie n .IP """SvIOK""" 4
25938 .el .IP \f(CWSvIOK\fR 4
25939 .IX Xref "SvIOK"
25940 .IX Item "SvIOK"
25941 Returns a U32 value indicating whether the SV contains an integer.
25942 .RS 4
25943 .Sp
25944 .Vb 1
25945 \& U32 SvIOK(SV* sv)
25946 .Ve
25947 .RE
25948 .RS 4
25949 .RE
25950 .ie n .IP """SvIOK_notUV""" 4
25951 .el .IP \f(CWSvIOK_notUV\fR 4
25952 .IX Xref "SvIOK_notUV"
25953 .IX Item "SvIOK_notUV"
25954 Returns a boolean indicating whether the SV contains a signed integer.
25955 .RS 4
25956 .Sp
25957 .Vb 1
25958 \& bool SvIOK_notUV(SV* sv)
25959 .Ve
25960 .RE
25961 .RS 4
25962 .RE
25963 .ie n .IP """SvIOK_off""" 4
25964 .el .IP \f(CWSvIOK_off\fR 4
25965 .IX Xref "SvIOK_off"
25966 .IX Item "SvIOK_off"
25967 Unsets the IV status of an SV.
25968 .RS 4
25969 .Sp
25970 .Vb 1
25971 \& void SvIOK_off(SV* sv)
25972 .Ve
25973 .RE
25974 .RS 4
25975 .RE
25976 .ie n .IP """SvIOK_on""" 4
25977 .el .IP \f(CWSvIOK_on\fR 4
25978 .IX Xref "SvIOK_on"
25979 .IX Item "SvIOK_on"
25980 Tells an SV that it is an integer.
25981 .RS 4
25982 .Sp
25983 .Vb 1
25984 \& void SvIOK_on(SV* sv)
25985 .Ve
25986 .RE
25987 .RS 4
25988 .RE
25989 .ie n .IP """SvIOK_only""" 4
25990 .el .IP \f(CWSvIOK_only\fR 4
25991 .IX Xref "SvIOK_only"
25992 .IX Item "SvIOK_only"
25993 Tells an SV that it is an integer and disables all other \f(CW\*(C`OK\*(C'\fR bits.
25994 .RS 4
25995 .Sp
25996 .Vb 1
25997 \& void SvIOK_only(SV* sv)
25998 .Ve
25999 .RE
26000 .RS 4
26001 .RE
26002 .ie n .IP """SvIOK_only_UV""" 4
26003 .el .IP \f(CWSvIOK_only_UV\fR 4
26004 .IX Xref "SvIOK_only_UV"
26005 .IX Item "SvIOK_only_UV"
26006 Tells an SV that it is an unsigned integer and disables all other \f(CW\*(C`OK\*(C'\fR bits.
26007 .RS 4
26008 .Sp
26009 .Vb 1
26010 \& void SvIOK_only_UV(SV* sv)
26011 .Ve
26012 .RE
26013 .RS 4
26014 .RE
26015 .ie n .IP """SvIOK_UV""" 4
26016 .el .IP \f(CWSvIOK_UV\fR 4
26017 .IX Xref "SvIOK_UV"
26018 .IX Item "SvIOK_UV"
26019 Returns a boolean indicating whether the SV contains an integer that must be
26020 interpreted as unsigned. A non\-negative integer whose value is within the
26021 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.
26022 .RS 4
26023 .Sp
26024 .Vb 1
26025 \& bool SvIOK_UV(SV* sv)
26026 .Ve
26027 .RE
26028 .RS 4
26029 .RE
26030 .ie n .IP """SvIOKp""" 4
26031 .el .IP \f(CWSvIOKp\fR 4
26032 .IX Xref "SvIOKp"
26033 .IX Item "SvIOKp"
26034 Returns a U32 value indicating whether the SV contains an integer. Checks
26035 the \fBprivate\fR setting. Use \f(CW\*(C`SvIOK\*(C'\fR instead.
26036 .RS 4
26037 .Sp
26038 .Vb 1
26039 \& U32 SvIOKp(SV* sv)
26040 .Ve
26041 .RE
26042 .RS 4
26043 .RE
26044 .ie n .IP """SvIsBOOL""" 4
26045 .el .IP \f(CWSvIsBOOL\fR 4
26046 .IX Xref "SvIsBOOL"
26047 .IX Item "SvIsBOOL"
26048 Returns true if the SV is one of the special boolean constants (PL_sv_yes or
26049 PL_sv_no), or is a regular SV whose last assignment stored a copy of one.
26050 .RS 4
26051 .Sp
26052 .Vb 1
26053 \& bool SvIsBOOL(SV* sv)
26054 .Ve
26055 .RE
26056 .RS 4
26057 .RE
26058 .ie n .IP """SvIsCOW""" 4
26059 .el .IP \f(CWSvIsCOW\fR 4
26060 .IX Xref "SvIsCOW"
26061 .IX Item "SvIsCOW"
26062 Returns a U32 value indicating whether the SV is Copy\-On\-Write (either shared
26063 hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
26064 COW).
26065 .RS 4
26066 .Sp
26067 .Vb 1
26068 \& U32 SvIsCOW(SV* sv)
26069 .Ve
26070 .RE
26071 .RS 4
26072 .RE
26073 .ie n .IP """SvIsCOW_shared_hash""" 4
26074 .el .IP \f(CWSvIsCOW_shared_hash\fR 4
26075 .IX Xref "SvIsCOW_shared_hash"
26076 .IX Item "SvIsCOW_shared_hash"
26077 Returns a boolean indicating whether the SV is Copy\-On\-Write shared hash key
26078 scalar.
26079 .RS 4
26080 .Sp
26081 .Vb 1
26082 \& bool SvIsCOW_shared_hash(SV* sv)
26083 .Ve
26084 .RE
26085 .RS 4
26086 .RE
26087 .ie n .IP """SvIV""" 4
26088 .el .IP \f(CWSvIV\fR 4
26089 .IX Item "SvIV"
26090 .PD 0
26091 .ie n .IP """SvIV_nomg""" 4
26092 .el .IP \f(CWSvIV_nomg\fR 4
26093 .IX Item "SvIV_nomg"
26094 .ie n .IP """SvIVx""" 4
26095 .el .IP \f(CWSvIVx\fR 4
26096 .IX Xref "SvIV SvIV_nomg SvIVx"
26097 .IX Item "SvIVx"
26098 .PD
26099 These each coerce the given SV to IV and return it. The returned value in many
26100 circumstances will get stored in \f(CW\*(C`sv\*(C'\fR\*(Aqs IV slot, but not in all cases. (Use
26101 \&\f(CW"sv_setiv"\fR to make sure it does).
26102 .Sp
26103 As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
26104 .Sp
26105 \&\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
26106 guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
26107 .Sp
26108 \&\f(CW\*(C`SvIV_nomg\*(C'\fR is the same as \f(CW\*(C`SvIV\*(C'\fR, but does not perform \*(Aqget\*(Aq magic.
26109 .RS 4
26110 .Sp
26111 .Vb 5
26112 \& IV SvIV ( SV *sv)
26113 \& IV Perl_SvIV (pTHX_ SV *sv)
26114 \& IV SvIV_nomg( SV *sv)
26115 \& IV Perl_SvIV_nomg(pTHX_ SV *sv)
26116 \& IV SvIVx ( SV *sv)
26117 .Ve
26118 .RE
26119 .RS 4
26120 .RE
26121 .ie n .IP """SvIV_set""" 4
26122 .el .IP \f(CWSvIV_set\fR 4
26123 .IX Xref "SvIV_set"
26124 .IX Item "SvIV_set"
26125 Set the value of the IV pointer in sv to val. It is possible to perform
26126 the same function of this macro with an lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR.
26127 With future Perls, however, it will be more efficient to use
26128 \&\f(CW\*(C`SvIV_set\*(C'\fR instead of the lvalue assignment to \f(CW\*(C`SvIVX\*(C'\fR.
26129 .RS 4
26130 .Sp
26131 .Vb 1
26132 \& void SvIV_set(SV* sv, IV val)
26133 .Ve
26134 .RE
26135 .RS 4
26136 .RE
26137 .ie n .IP """SvIVX""" 4
26138 .el .IP \f(CWSvIVX\fR 4
26139 .IX Xref "SvIVX"
26140 .IX Item "SvIVX"
26141 Returns the raw value in the SV\*(Aqs IV slot, without checks or conversions.
26142 Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true. See also \f(CW"SvIV"\fR.
26143 .RS 4
26144 .Sp
26145 .Vb 1
26146 \& IV SvIVX(SV* sv)
26147 .Ve
26148 .RE
26149 .RS 4
26150 .RE
26151 .ie n .IP """SvIVx*""" 4
26152 .el .IP \f(CWSvIVx*\fR 4
26153 .IX Item "SvIVx*"
26154 Described under \f(CW"SvIV"\fR
26155 .ie n .IP """SvLEN""" 4
26156 .el .IP \f(CWSvLEN\fR 4
26157 .IX Xref "SvLEN"
26158 .IX Item "SvLEN"
26159 Returns the size of the string buffer in the SV, not including any part
26160 attributable to \f(CW\*(C`SvOOK\*(C'\fR. See \f(CW"SvCUR"\fR.
26161 .RS 4
26162 .Sp
26163 .Vb 1
26164 \& STRLEN SvLEN(SV* sv)
26165 .Ve
26166 .RE
26167 .RS 4
26168 .RE
26169 .ie n .IP """SvLEN_set""" 4
26170 .el .IP \f(CWSvLEN_set\fR 4
26171 .IX Xref "SvLEN_set"
26172 .IX Item "SvLEN_set"
26173 Set the size of the string buffer for the SV. See \f(CW"SvLEN"\fR.
26174 .RS 4
26175 .Sp
26176 .Vb 1
26177 \& void SvLEN_set(SV* sv, STRLEN len)
26178 .Ve
26179 .RE
26180 .RS 4
26181 .RE
26182 .ie n .IP """SvLOCK""" 4
26183 .el .IP \f(CWSvLOCK\fR 4
26184 .IX Xref "SvLOCK"
26185 .IX Item "SvLOCK"
26186 Arranges for a mutual exclusion lock to be obtained on \f(CW\*(C`sv\*(C'\fR if a suitable module
26187 has been loaded.
26188 .RS 4
26189 .Sp
26190 .Vb 1
26191 \& void SvLOCK(SV* sv)
26192 .Ve
26193 .RE
26194 .RS 4
26195 .RE
26196 .ie n .IP """SvMAGIC_set""" 4
26197 .el .IP \f(CWSvMAGIC_set\fR 4
26198 .IX Xref "SvMAGIC_set"
26199 .IX Item "SvMAGIC_set"
26200 Set the value of the MAGIC pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
26201 .RS 4
26202 .Sp
26203 .Vb 1
26204 \& void SvMAGIC_set(SV* sv, MAGIC* val)
26205 .Ve
26206 .RE
26207 .RS 4
26208 .RE
26209 .ie n .IP """SvNIOK""" 4
26210 .el .IP \f(CWSvNIOK\fR 4
26211 .IX Xref "SvNIOK"
26212 .IX Item "SvNIOK"
26213 Returns a U32 value indicating whether the SV contains a number, integer or
26214 double.
26215 .RS 4
26216 .Sp
26217 .Vb 1
26218 \& U32 SvNIOK(SV* sv)
26219 .Ve
26220 .RE
26221 .RS 4
26222 .RE
26223 .ie n .IP """SvNIOK_off""" 4
26224 .el .IP \f(CWSvNIOK_off\fR 4
26225 .IX Xref "SvNIOK_off"
26226 .IX Item "SvNIOK_off"
26227 Unsets the NV/IV status of an SV.
26228 .RS 4
26229 .Sp
26230 .Vb 1
26231 \& void SvNIOK_off(SV* sv)
26232 .Ve
26233 .RE
26234 .RS 4
26235 .RE
26236 .ie n .IP """SvNIOKp""" 4
26237 .el .IP \f(CWSvNIOKp\fR 4
26238 .IX Xref "SvNIOKp"
26239 .IX Item "SvNIOKp"
26240 Returns a U32 value indicating whether the SV contains a number, integer or
26241 double. Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvNIOK\*(C'\fR instead.
26242 .RS 4
26243 .Sp
26244 .Vb 1
26245 \& U32 SvNIOKp(SV* sv)
26246 .Ve
26247 .RE
26248 .RS 4
26249 .RE
26250 .ie n .IP """SvNOK""" 4
26251 .el .IP \f(CWSvNOK\fR 4
26252 .IX Xref "SvNOK"
26253 .IX Item "SvNOK"
26254 Returns a U32 value indicating whether the SV contains a double.
26255 .RS 4
26256 .Sp
26257 .Vb 1
26258 \& U32 SvNOK(SV* sv)
26259 .Ve
26260 .RE
26261 .RS 4
26262 .RE
26263 .ie n .IP """SvNOK_off""" 4
26264 .el .IP \f(CWSvNOK_off\fR 4
26265 .IX Xref "SvNOK_off"
26266 .IX Item "SvNOK_off"
26267 Unsets the NV status of an SV.
26268 .RS 4
26269 .Sp
26270 .Vb 1
26271 \& void SvNOK_off(SV* sv)
26272 .Ve
26273 .RE
26274 .RS 4
26275 .RE
26276 .ie n .IP """SvNOK_on""" 4
26277 .el .IP \f(CWSvNOK_on\fR 4
26278 .IX Xref "SvNOK_on"
26279 .IX Item "SvNOK_on"
26280 Tells an SV that it is a double.
26281 .RS 4
26282 .Sp
26283 .Vb 1
26284 \& void SvNOK_on(SV* sv)
26285 .Ve
26286 .RE
26287 .RS 4
26288 .RE
26289 .ie n .IP """SvNOK_only""" 4
26290 .el .IP \f(CWSvNOK_only\fR 4
26291 .IX Xref "SvNOK_only"
26292 .IX Item "SvNOK_only"
26293 Tells an SV that it is a double and disables all other OK bits.
26294 .RS 4
26295 .Sp
26296 .Vb 1
26297 \& void SvNOK_only(SV* sv)
26298 .Ve
26299 .RE
26300 .RS 4
26301 .RE
26302 .ie n .IP """SvNOKp""" 4
26303 .el .IP \f(CWSvNOKp\fR 4
26304 .IX Xref "SvNOKp"
26305 .IX Item "SvNOKp"
26306 Returns a U32 value indicating whether the SV contains a double. Checks the
26307 \&\fBprivate\fR setting. Use \f(CW\*(C`SvNOK\*(C'\fR instead.
26308 .RS 4
26309 .Sp
26310 .Vb 1
26311 \& U32 SvNOKp(SV* sv)
26312 .Ve
26313 .RE
26314 .RS 4
26315 .RE
26316 .ie n .IP """SvNV""" 4
26317 .el .IP \f(CWSvNV\fR 4
26318 .IX Item "SvNV"
26319 .PD 0
26320 .ie n .IP """SvNV_nomg""" 4
26321 .el .IP \f(CWSvNV_nomg\fR 4
26322 .IX Item "SvNV_nomg"
26323 .ie n .IP """SvNVx""" 4
26324 .el .IP \f(CWSvNVx\fR 4
26325 .IX Xref "SvNV SvNV_nomg SvNVx"
26326 .IX Item "SvNVx"
26327 .PD
26328 These each coerce the given SV to NV and return it. The returned value in many
26329 circumstances will get stored in \f(CW\*(C`sv\*(C'\fR\*(Aqs NV slot, but not in all cases. (Use
26330 \&\f(CW"sv_setnv"\fR to make sure it does).
26331 .Sp
26332 As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
26333 .Sp
26334 \&\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
26335 guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
26336 .Sp
26337 \&\f(CW\*(C`SvNV_nomg\*(C'\fR is the same as \f(CW\*(C`SvNV\*(C'\fR, but does not perform \*(Aqget\*(Aq magic.
26338 .RS 4
26339 .Sp
26340 .Vb 5
26341 \& NV SvNV ( SV *sv)
26342 \& NV Perl_SvNV (pTHX_ SV *sv)
26343 \& NV SvNV_nomg( SV *sv)
26344 \& NV Perl_SvNV_nomg(pTHX_ SV *sv)
26345 \& NV SvNVx ( SV *sv)
26346 .Ve
26347 .RE
26348 .RS 4
26349 .RE
26350 .ie n .IP """SvNV_set""" 4
26351 .el .IP \f(CWSvNV_set\fR 4
26352 .IX Xref "SvNV_set"
26353 .IX Item "SvNV_set"
26354 Set the value of the NV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
26355 .RS 4
26356 .Sp
26357 .Vb 1
26358 \& void SvNV_set(SV* sv, NV val)
26359 .Ve
26360 .RE
26361 .RS 4
26362 .RE
26363 .ie n .IP """SvNVX""" 4
26364 .el .IP \f(CWSvNVX\fR 4
26365 .IX Xref "SvNVX"
26366 .IX Item "SvNVX"
26367 Returns the raw value in the SV\*(Aqs NV slot, without checks or conversions.
26368 Only use when you are sure \f(CW\*(C`SvNOK\*(C'\fR is true. See also \f(CW"SvNV"\fR.
26369 .RS 4
26370 .Sp
26371 .Vb 1
26372 \& NV SvNVX(SV* sv)
26373 .Ve
26374 .RE
26375 .RS 4
26376 .RE
26377 .ie n .IP """SvNVx*""" 4
26378 .el .IP \f(CWSvNVx*\fR 4
26379 .IX Item "SvNVx*"
26380 Described under \f(CW"SvNV"\fR
26381 .ie n .IP """SvOK""" 4
26382 .el .IP \f(CWSvOK\fR 4
26383 .IX Xref "SvOK"
26384 .IX Item "SvOK"
26385 Returns a U32 value indicating whether the value is defined. This is
26386 only meaningful for scalars.
26387 .RS 4
26388 .Sp
26389 .Vb 1
26390 \& U32 SvOK(SV* sv)
26391 .Ve
26392 .RE
26393 .RS 4
26394 .RE
26395 .ie n .IP """SvOOK""" 4
26396 .el .IP \f(CWSvOOK\fR 4
26397 .IX Xref "SvOOK"
26398 .IX Item "SvOOK"
26399 Returns a U32 indicating whether the pointer to the string buffer is offset.
26400 This hack is used internally to speed up removal of characters from the
26401 beginning of a \f(CW"SvPV"\fR. When \f(CW\*(C`SvOOK\*(C'\fR is true, then the start of the
26402 allocated string buffer is actually \f(CWSvOOK_offset()\fR bytes before \f(CW\*(C`SvPVX\*(C'\fR.
26403 This offset used to be stored in \f(CW\*(C`SvIVX\*(C'\fR, but is now stored within the spare
26404 part of the buffer.
26405 .RS 4
26406 .Sp
26407 .Vb 1
26408 \& U32 SvOOK(SV* sv)
26409 .Ve
26410 .RE
26411 .RS 4
26412 .RE
26413 .ie n .IP """SvOOK_off""" 4
26414 .el .IP \f(CWSvOOK_off\fR 4
26415 .IX Xref "SvOOK_off"
26416 .IX Item "SvOOK_off"
26417 Remove any string offset.
26418 .RS 4
26419 .Sp
26420 .Vb 1
26421 \& void SvOOK_off(SV * sv)
26422 .Ve
26423 .RE
26424 .RS 4
26425 .RE
26426 .ie n .IP """SvOOK_offset""" 4
26427 .el .IP \f(CWSvOOK_offset\fR 4
26428 .IX Xref "SvOOK_offset"
26429 .IX Item "SvOOK_offset"
26430 Reads into \f(CW\*(C`len\*(C'\fR the offset from \f(CW\*(C`SvPVX\*(C'\fR back to the true start of the
26431 allocated buffer, which will be non\-zero if \f(CW\*(C`sv_chop\*(C'\fR has been used to
26432 efficiently remove characters from start of the buffer. Implemented as a
26433 macro, which takes the address of \f(CW\*(C`len\*(C'\fR, which must be of type \f(CW\*(C`STRLEN\*(C'\fR.
26434 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.
26435 .RS 4
26436 .Sp
26437 .Vb 1
26438 \& void SvOOK_offset(SV*sv, STRLEN len)
26439 .Ve
26440 .RE
26441 .RS 4
26442 .RE
26443 .ie n .IP """SvPOK""" 4
26444 .el .IP \f(CWSvPOK\fR 4
26445 .IX Xref "SvPOK"
26446 .IX Item "SvPOK"
26447 Returns a U32 value indicating whether the SV contains a character
26448 string.
26449 .RS 4
26450 .Sp
26451 .Vb 1
26452 \& U32 SvPOK(SV* sv)
26453 .Ve
26454 .RE
26455 .RS 4
26456 .RE
26457 .ie n .IP """SvPOK_off""" 4
26458 .el .IP \f(CWSvPOK_off\fR 4
26459 .IX Xref "SvPOK_off"
26460 .IX Item "SvPOK_off"
26461 Unsets the PV status of an SV.
26462 .RS 4
26463 .Sp
26464 .Vb 1
26465 \& void SvPOK_off(SV* sv)
26466 .Ve
26467 .RE
26468 .RS 4
26469 .RE
26470 .ie n .IP """SvPOK_on""" 4
26471 .el .IP \f(CWSvPOK_on\fR 4
26472 .IX Xref "SvPOK_on"
26473 .IX Item "SvPOK_on"
26474 Tells an SV that it is a string.
26475 .RS 4
26476 .Sp
26477 .Vb 1
26478 \& void SvPOK_on(SV* sv)
26479 .Ve
26480 .RE
26481 .RS 4
26482 .RE
26483 .ie n .IP """SvPOK_only""" 4
26484 .el .IP \f(CWSvPOK_only\fR 4
26485 .IX Xref "SvPOK_only"
26486 .IX Item "SvPOK_only"
26487 Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits.
26488 Will also turn off the UTF\-8 status.
26489 .RS 4
26490 .Sp
26491 .Vb 1
26492 \& void SvPOK_only(SV* sv)
26493 .Ve
26494 .RE
26495 .RS 4
26496 .RE
26497 .ie n .IP """SvPOK_only_UTF8""" 4
26498 .el .IP \f(CWSvPOK_only_UTF8\fR 4
26499 .IX Xref "SvPOK_only_UTF8"
26500 .IX Item "SvPOK_only_UTF8"
26501 Tells an SV that it is a string and disables all other \f(CW\*(C`OK\*(C'\fR bits,
26502 and leaves the UTF\-8 status as it was.
26503 .RS 4
26504 .Sp
26505 .Vb 1
26506 \& void SvPOK_only_UTF8(SV* sv)
26507 .Ve
26508 .RE
26509 .RS 4
26510 .RE
26511 .ie n .IP """SvPOKp""" 4
26512 .el .IP \f(CWSvPOKp\fR 4
26513 .IX Xref "SvPOKp"
26514 .IX Item "SvPOKp"
26515 Returns a U32 value indicating whether the SV contains a character string.
26516 Checks the \fBprivate\fR setting. Use \f(CW\*(C`SvPOK\*(C'\fR instead.
26517 .RS 4
26518 .Sp
26519 .Vb 1
26520 \& U32 SvPOKp(SV* sv)
26521 .Ve
26522 .RE
26523 .RS 4
26524 .RE
26525 .ie n .IP """SvPV""" 4
26526 .el .IP \f(CWSvPV\fR 4
26527 .IX Item "SvPV"
26528 .PD 0
26529 .ie n .IP """SvPV_const""" 4
26530 .el .IP \f(CWSvPV_const\fR 4
26531 .IX Item "SvPV_const"
26532 .ie n .IP """SvPV_flags""" 4
26533 .el .IP \f(CWSvPV_flags\fR 4
26534 .IX Item "SvPV_flags"
26535 .ie n .IP """SvPV_flags_const""" 4
26536 .el .IP \f(CWSvPV_flags_const\fR 4
26537 .IX Item "SvPV_flags_const"
26538 .ie n .IP """SvPV_flags_mutable""" 4
26539 .el .IP \f(CWSvPV_flags_mutable\fR 4
26540 .IX Item "SvPV_flags_mutable"
26541 .ie n .IP """SvPV_mutable""" 4
26542 .el .IP \f(CWSvPV_mutable\fR 4
26543 .IX Item "SvPV_mutable"
26544 .ie n .IP """SvPV_nolen""" 4
26545 .el .IP \f(CWSvPV_nolen\fR 4
26546 .IX Item "SvPV_nolen"
26547 .ie n .IP """SvPV_nolen_const""" 4
26548 .el .IP \f(CWSvPV_nolen_const\fR 4
26549 .IX Item "SvPV_nolen_const"
26550 .ie n .IP """SvPV_nomg""" 4
26551 .el .IP \f(CWSvPV_nomg\fR 4
26552 .IX Item "SvPV_nomg"
26553 .ie n .IP """SvPV_nomg_const""" 4
26554 .el .IP \f(CWSvPV_nomg_const\fR 4
26555 .IX Item "SvPV_nomg_const"
26556 .ie n .IP """SvPV_nomg_const_nolen""" 4
26557 .el .IP \f(CWSvPV_nomg_const_nolen\fR 4
26558 .IX Item "SvPV_nomg_const_nolen"
26559 .ie n .IP """SvPV_nomg_nolen""" 4
26560 .el .IP \f(CWSvPV_nomg_nolen\fR 4
26561 .IX Item "SvPV_nomg_nolen"
26562 .ie n .IP """SvPVbyte""" 4
26563 .el .IP \f(CWSvPVbyte\fR 4
26564 .IX Item "SvPVbyte"
26565 .ie n .IP """SvPVbyte_nolen""" 4
26566 .el .IP \f(CWSvPVbyte_nolen\fR 4
26567 .IX Item "SvPVbyte_nolen"
26568 .ie n .IP """SvPVbyte_nomg""" 4
26569 .el .IP \f(CWSvPVbyte_nomg\fR 4
26570 .IX Item "SvPVbyte_nomg"
26571 .ie n .IP """SvPVbyte_or_null""" 4
26572 .el .IP \f(CWSvPVbyte_or_null\fR 4
26573 .IX Item "SvPVbyte_or_null"
26574 .ie n .IP """SvPVbyte_or_null_nomg""" 4
26575 .el .IP \f(CWSvPVbyte_or_null_nomg\fR 4
26576 .IX Item "SvPVbyte_or_null_nomg"
26577 .ie n .IP """SvPVbytex""" 4
26578 .el .IP \f(CWSvPVbytex\fR 4
26579 .IX Item "SvPVbytex"
26580 .ie n .IP """SvPVbytex_nolen""" 4
26581 .el .IP \f(CWSvPVbytex_nolen\fR 4
26582 .IX Item "SvPVbytex_nolen"
26583 .ie n .IP """SvPVutf8""" 4
26584 .el .IP \f(CWSvPVutf8\fR 4
26585 .IX Item "SvPVutf8"
26586 .ie n .IP """SvPVutf8_nolen""" 4
26587 .el .IP \f(CWSvPVutf8_nolen\fR 4
26588 .IX Item "SvPVutf8_nolen"
26589 .ie n .IP """SvPVutf8_nomg""" 4
26590 .el .IP \f(CWSvPVutf8_nomg\fR 4
26591 .IX Item "SvPVutf8_nomg"
26592 .ie n .IP """SvPVutf8_or_null""" 4
26593 .el .IP \f(CWSvPVutf8_or_null\fR 4
26594 .IX Item "SvPVutf8_or_null"
26595 .ie n .IP """SvPVutf8_or_null_nomg""" 4
26596 .el .IP \f(CWSvPVutf8_or_null_nomg\fR 4
26597 .IX Item "SvPVutf8_or_null_nomg"
26598 .ie n .IP """SvPVutf8x""" 4
26599 .el .IP \f(CWSvPVutf8x\fR 4
26600 .IX Item "SvPVutf8x"
26601 .ie n .IP """SvPVx""" 4
26602 .el .IP \f(CWSvPVx\fR 4
26603 .IX Item "SvPVx"
26604 .ie n .IP """SvPVx_const""" 4
26605 .el .IP \f(CWSvPVx_const\fR 4
26606 .IX Item "SvPVx_const"
26607 .ie n .IP """SvPVx_nolen""" 4
26608 .el .IP \f(CWSvPVx_nolen\fR 4
26609 .IX Item "SvPVx_nolen"
26610 .ie n .IP """SvPVx_nolen_const""" 4
26611 .el .IP \f(CWSvPVx_nolen_const\fR 4
26612 .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"
26613 .IX Item "SvPVx_nolen_const"
26614 .PD
26615 These each return a pointer to the string in \f(CW\*(C`sv\*(C'\fR, or a stringified form of
26616 \&\f(CW\*(C`sv\*(C'\fR if it does not contain a string. The SV may cache the stringified
26617 version becoming \f(CW\*(C`SvPOK\*(C'\fR.
26618 .Sp
26619 This is a very basic and common operation, so there are lots of slightly
26620 different versions of it.
26621 .Sp
26622 Note that there is no guarantee that the return value of \f(CWSvPV(sv)\fR, for
26623 example, is equal to \f(CWSvPVX(sv)\fR, or that \f(CWSvPVX(sv)\fR contains valid data, or
26624 that successive calls to \f(CWSvPV(sv)\fR (or another of these forms) will return
26625 the same pointer value each time. This is due to the way that things like
26626 overloading and Copy\-On\-Write are handled. In these cases, the return value
26627 may point to a temporary buffer or similar. If you absolutely need the
26628 \&\f(CW\*(C`SvPVX\*(C'\fR field to be valid (for example, if you intend to write to it), then
26629 see \f(CW"SvPV_force"\fR.
26630 .Sp
26631 The differences between the forms are:
26632 .Sp
26633 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
26634 \&\f(CW\*(C`SvPV_nolen\*(C'\fR) can expose the SV\*(Aqs internal string buffer. If
26635 that buffer consists entirely of bytes 0\-255 and includes any bytes above
26636 127, then you \fBMUST\fR consult \f(CW\*(C`SvUTF8\*(C'\fR to determine the actual code points
26637 the string is meant to contain. Generally speaking, it is probably safer to
26638 prefer \f(CW\*(C`SvPVbyte\*(C'\fR, \f(CW\*(C`SvPVutf8\*(C'\fR, and the like. See
26639 "How do I pass a Perl string to a C library?" in perlguts for more details.
26640 .Sp
26641 The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter
26642 to specify to process \*(Aqget\*(Aq magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip
26643 \&\*(Aqget\*(Aq magic (by clearing it). The other forms process \*(Aqget\*(Aq magic, except for
26644 the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip \*(Aqget\*(Aq magic.
26645 .Sp
26646 The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte
26647 length of the resultant string (these are macros, so don\*(Aqt use \f(CW&len\fR).
26648 .Sp
26649 The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don\*(Aqt have a \f(CW\*(C`len\*(C'\fR
26650 parameter. They should be used only when it is known that the PV is a C
26651 string, terminated by a NUL byte, and without intermediate NUL characters; or
26652 when you don\*(Aqt care about its length.
26653 .Sp
26654 The forms with \f(CW\*(C`const\*(C'\fR in their names return \f(CW\*(C`const\ char\ *\*(C'\fR so that the
26655 compiler will hopefully complain if you were to try to modify the contents of
26656 the string (unless you cast away const yourself).
26657 .Sp
26658 The other forms return a mutable pointer so that the string is modifiable by
26659 the caller; this is emphasized for the ones with \f(CW\*(C`mutable\*(C'\fR in their names.
26660 .Sp
26661 As of 5.38, all forms are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR exactly once. For
26662 earlier Perls, use a form whose name ends with \f(CW\*(C`x\*(C'\fR for single evaluation.
26663 .Sp
26664 \&\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
26665 UTF\-8. Similarly, the other forms with \f(CW\*(C`utf8\*(C'\fR in their names correspond to
26666 their respective forms without.
26667 .Sp
26668 \&\f(CW\*(C`SvPVutf8_or_null\*(C'\fR and \f(CW\*(C`SvPVutf8_or_null_nomg\*(C'\fR don\*(Aqt have corresponding
26669 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
26670 undef, they return \f(CW\*(C`NULL\*(C'\fR.
26671 .Sp
26672 \&\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
26673 currently encoded as UTF\-8. If \f(CW\*(C`sv\*(C'\fR cannot be downgraded from UTF\-8, it
26674 croaks. Similarly, the other forms with \f(CW\*(C`byte\*(C'\fR in their names correspond to
26675 their respective forms without.
26676 .Sp
26677 \&\f(CW\*(C`SvPVbyte_or_null\*(C'\fR doesn\*(Aqt have a corresponding non\-\f(CW\*(C`byte\*(C'\fR form. Instead it
26678 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.
26679 .RS 4
26680 .Sp
26681 .Vb 10
26682 \& char* SvPV (SV* sv, STRLEN len)
26683 \& const char* SvPV_const (SV* sv, STRLEN len)
26684 \& char* SvPV_flags (SV* sv, STRLEN len, U32 flags)
26685 \& const char* SvPV_flags_const (SV* sv, STRLEN len, U32 flags)
26686 \& char* SvPV_flags_mutable (SV* sv, STRLEN len, U32 flags)
26687 \& char* SvPV_mutable (SV* sv, STRLEN len)
26688 \& char* SvPV_nolen (SV* sv)
26689 \& const char* SvPV_nolen_const (SV* sv)
26690 \& char* SvPV_nomg (SV* sv, STRLEN len)
26691 \& const char* SvPV_nomg_const (SV* sv, STRLEN len)
26692 \& const char* SvPV_nomg_const_nolen(SV* sv)
26693 \& char* SvPV_nomg_nolen (SV* sv)
26694 \& char* SvPVbyte (SV* sv, STRLEN len)
26695 \& char* SvPVbyte_nolen (SV* sv)
26696 \& char* SvPVbyte_nomg (SV* sv, STRLEN len)
26697 \& char* SvPVbyte_or_null (SV* sv, STRLEN len)
26698 \& char* SvPVbyte_or_null_nomg(SV* sv, STRLEN len)
26699 \& char* SvPVbytex (SV* sv, STRLEN len)
26700 \& char* SvPVbytex_nolen (SV* sv)
26701 \& char* SvPVutf8 (SV* sv, STRLEN len)
26702 \& char* SvPVutf8_nolen (SV* sv)
26703 \& char* SvPVutf8_nomg (SV* sv, STRLEN len)
26704 \& char* SvPVutf8_or_null (SV* sv, STRLEN len)
26705 \& char* SvPVutf8_or_null_nomg(SV* sv, STRLEN len)
26706 \& char* SvPVutf8x (SV* sv, STRLEN len)
26707 \& char* SvPVx (SV* sv, STRLEN len)
26708 \& const char* SvPVx_const (SV* sv, STRLEN len)
26709 \& char* SvPVx_nolen (SV* sv)
26710 \& const char* SvPVx_nolen_const (SV* sv)
26711 .Ve
26712 .RE
26713 .RS 4
26714 .RE
26715 .ie n .IP """SvPV_force""" 4
26716 .el .IP \f(CWSvPV_force\fR 4
26717 .IX Item "SvPV_force"
26718 .PD 0
26719 .ie n .IP """SvPV_force_flags""" 4
26720 .el .IP \f(CWSvPV_force_flags\fR 4
26721 .IX Item "SvPV_force_flags"
26722 .ie n .IP """SvPV_force_flags_mutable""" 4
26723 .el .IP \f(CWSvPV_force_flags_mutable\fR 4
26724 .IX Item "SvPV_force_flags_mutable"
26725 .ie n .IP """SvPV_force_flags_nolen""" 4
26726 .el .IP \f(CWSvPV_force_flags_nolen\fR 4
26727 .IX Item "SvPV_force_flags_nolen"
26728 .ie n .IP """SvPV_force_mutable""" 4
26729 .el .IP \f(CWSvPV_force_mutable\fR 4
26730 .IX Item "SvPV_force_mutable"
26731 .ie n .IP """SvPV_force_nolen""" 4
26732 .el .IP \f(CWSvPV_force_nolen\fR 4
26733 .IX Item "SvPV_force_nolen"
26734 .ie n .IP """SvPV_force_nomg""" 4
26735 .el .IP \f(CWSvPV_force_nomg\fR 4
26736 .IX Item "SvPV_force_nomg"
26737 .ie n .IP """SvPV_force_nomg_nolen""" 4
26738 .el .IP \f(CWSvPV_force_nomg_nolen\fR 4
26739 .IX Item "SvPV_force_nomg_nolen"
26740 .ie n .IP """SvPVbyte_force""" 4
26741 .el .IP \f(CWSvPVbyte_force\fR 4
26742 .IX Item "SvPVbyte_force"
26743 .ie n .IP """SvPVbytex_force""" 4
26744 .el .IP \f(CWSvPVbytex_force\fR 4
26745 .IX Item "SvPVbytex_force"
26746 .ie n .IP """SvPVutf8_force""" 4
26747 .el .IP \f(CWSvPVutf8_force\fR 4
26748 .IX Item "SvPVutf8_force"
26749 .ie n .IP """SvPVutf8x_force""" 4
26750 .el .IP \f(CWSvPVutf8x_force\fR 4
26751 .IX Item "SvPVutf8x_force"
26752 .ie n .IP """SvPVx_force""" 4
26753 .el .IP \f(CWSvPVx_force\fR 4
26754 .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"
26755 .IX Item "SvPVx_force"
26756 .PD
26757 These are like \f(CW"SvPV"\fR, returning the string in the SV, but will force the
26758 SV into containing a string (\f(CW"SvPOK"\fR), and only a string
26759 (\f(CW"SvPOK_only"\fR), by hook or by crook. You need to use one of these
26760 \&\f(CW\*(C`force\*(C'\fR routines if you are going to update the \f(CW"SvPVX"\fR directly.
26761 .Sp
26762 Note that coercing an arbitrary scalar into a plain PV will potentially
26763 strip useful data from it. For example if the SV was \f(CW\*(C`SvROK\*(C'\fR, then the
26764 referent will have its reference count decremented, and the SV itself may
26765 be converted to an \f(CW\*(C`SvPOK\*(C'\fR scalar with a string buffer containing a value
26766 such as \f(CW"ARRAY(0x1234)"\fR.
26767 .Sp
26768 The differences between the forms are:
26769 .Sp
26770 The forms with \f(CW\*(C`flags\*(C'\fR in their names allow you to use the \f(CW\*(C`flags\*(C'\fR parameter
26771 to specify to perform \*(Aqget\*(Aq magic (by setting the \f(CW\*(C`SV_GMAGIC\*(C'\fR flag) or to skip
26772 \&\*(Aqget\*(Aq magic (by clearing it). The other forms do perform \*(Aqget\*(Aq magic, except
26773 for the ones with \f(CW\*(C`nomg\*(C'\fR in their names, which skip \*(Aqget\*(Aq magic.
26774 .Sp
26775 The forms that take a \f(CW\*(C`len\*(C'\fR parameter will set that variable to the byte
26776 length of the resultant string (these are macros, so don\*(Aqt use \f(CW&len\fR).
26777 .Sp
26778 The forms with \f(CW\*(C`nolen\*(C'\fR in their names indicate they don\*(Aqt have a \f(CW\*(C`len\*(C'\fR
26779 parameter. They should be used only when it is known that the PV is a C
26780 string, terminated by a NUL byte, and without intermediate NUL characters; or
26781 when you don\*(Aqt care about its length.
26782 .Sp
26783 The forms with \f(CW\*(C`mutable\*(C'\fR in their names are effectively the same as those without,
26784 but the name emphasizes that the string is modifiable by the caller, which it is
26785 in all the forms.
26786 .Sp
26787 \&\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
26788 not already UTF\-8.
26789 .Sp
26790 \&\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
26791 only once; use the more efficient \f(CW\*(C`SvPVutf8_force\*(C'\fR otherwise.
26792 .Sp
26793 \&\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
26794 representation first if currently encoded as UTF\-8. If the SV cannot be
26795 downgraded from UTF\-8, this croaks.
26796 .Sp
26797 \&\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
26798 only once; use the more efficient \f(CW\*(C`SvPVbyte_force\*(C'\fR otherwise.
26799 .RS 4
26800 .Sp
26801 .Vb 10
26802 \& char* SvPV_force (SV* sv, STRLEN len)
26803 \& char* SvPV_force_flags (SV * sv, STRLEN len, U32 flags)
26804 \& char* SvPV_force_flags_mutable(SV * sv, STRLEN len, U32 flags)
26805 \& char* SvPV_force_flags_nolen (SV * sv, U32 flags)
26806 \& char* SvPV_force_mutable (SV * sv, STRLEN len)
26807 \& char* SvPV_force_nolen (SV* sv)
26808 \& char* SvPV_force_nomg (SV* sv, STRLEN len)
26809 \& char* SvPV_force_nomg_nolen (SV * sv)
26810 \& char* SvPVbyte_force (SV * sv, STRLEN len)
26811 \& char* SvPVbytex_force (SV * sv, STRLEN len)
26812 \& char* SvPVutf8_force (SV * sv, STRLEN len)
26813 \& char* SvPVutf8x_force (SV * sv, STRLEN len)
26814 \& char* SvPVx_force (SV* sv, STRLEN len)
26815 .Ve
26816 .RE
26817 .RS 4
26818 .RE
26819 .ie n .IP """SvPV_free""" 4
26820 .el .IP \f(CWSvPV_free\fR 4
26821 .IX Xref "SvPV_free"
26822 .IX Item "SvPV_free"
26823 Frees the PV buffer in \f(CW\*(C`sv\*(C'\fR, leaving things in a precarious state, so should
26824 only be used as part of a larger operation
26825 .RS 4
26826 .Sp
26827 .Vb 1
26828 \& void SvPV_free(SV * sv)
26829 .Ve
26830 .RE
26831 .RS 4
26832 .RE
26833 .ie n .IP """SvPV_mutable*""" 4
26834 .el .IP \f(CWSvPV_mutable*\fR 4
26835 .IX Item "SvPV_mutable*"
26836 .PD 0
26837 .ie n .IP """SvPV_nolen*""" 4
26838 .el .IP \f(CWSvPV_nolen*\fR 4
26839 .IX Item "SvPV_nolen*"
26840 .ie n .IP """SvPV_nolen_const*""" 4
26841 .el .IP \f(CWSvPV_nolen_const*\fR 4
26842 .IX Item "SvPV_nolen_const*"
26843 .ie n .IP """SvPV_nomg*""" 4
26844 .el .IP \f(CWSvPV_nomg*\fR 4
26845 .IX Item "SvPV_nomg*"
26846 .ie n .IP """SvPV_nomg_const*""" 4
26847 .el .IP \f(CWSvPV_nomg_const*\fR 4
26848 .IX Item "SvPV_nomg_const*"
26849 .ie n .IP """SvPV_nomg_const_nolen*""" 4
26850 .el .IP \f(CWSvPV_nomg_const_nolen*\fR 4
26851 .IX Item "SvPV_nomg_const_nolen*"
26852 .ie n .IP """SvPV_nomg_nolen*""" 4
26853 .el .IP \f(CWSvPV_nomg_nolen*\fR 4
26854 .IX Item "SvPV_nomg_nolen*"
26855 .PD
26856 Described under \f(CW"SvPV"\fR
26857 .ie n .IP """SvPV_renew""" 4
26858 .el .IP \f(CWSvPV_renew\fR 4
26859 .IX Xref "SvPV_renew"
26860 .IX Item "SvPV_renew"
26861 Low level micro optimization of \f(CW"SvGROW"\fR. It is generally better to use
26862 \&\f(CW\*(C`SvGROW\*(C'\fR instead. This is because \f(CW\*(C`SvPV_renew\*(C'\fR ignores potential issues that
26863 \&\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
26864 things like COW. Using \f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR or
26865 \&\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR before calling this should clean it up, but
26866 why not just use \f(CW\*(C`SvGROW\*(C'\fR if you\*(Aqre not sure about the provenance?
26867 .RS 4
26868 .Sp
26869 .Vb 1
26870 \& void SvPV_renew(SV* sv, STRLEN len)
26871 .Ve
26872 .RE
26873 .RS 4
26874 .RE
26875 .ie n .IP """SvPV_set""" 4
26876 .el .IP \f(CWSvPV_set\fR 4
26877 .IX Xref "SvPV_set"
26878 .IX Item "SvPV_set"
26879 This is probably not what you want to use, you probably wanted
26880 "sv_usepvn_flags" or "sv_setpvn" or "sv_setpvs".
26881 .Sp
26882 Set the value of the PV pointer in \f(CW\*(C`sv\*(C'\fR to the Perl allocated
26883 \&\f(CW\*(C`NUL\*(C'\fR\-terminated string \f(CW\*(C`val\*(C'\fR. See also \f(CW"SvIV_set"\fR.
26884 .Sp
26885 Remember to free the previous PV buffer. There are many things to check.
26886 Beware that the existing pointer may be involved in copy\-on\-write or other
26887 mischief, so do \f(CWSvOOK_off(sv)\fR and use \f(CW\*(C`sv_force_normal\*(C'\fR or
26888 \&\f(CW\*(C`SvPV_force\*(C'\fR (or check the \f(CW\*(C`SvIsCOW\*(C'\fR flag) first to make sure this
26889 modification is safe. Then finally, if it is not a COW, call
26890 \&\f(CW"SvPV_free"\fR to free the previous PV buffer.
26891 .RS 4
26892 .Sp
26893 .Vb 1
26894 \& void SvPV_set(SV* sv, char* val)
26895 .Ve
26896 .RE
26897 .RS 4
26898 .RE
26899 .ie n .IP """SvPV_shrink_to_cur""" 4
26900 .el .IP \f(CWSvPV_shrink_to_cur\fR 4
26901 .IX Xref "SvPV_shrink_to_cur"
26902 .IX Item "SvPV_shrink_to_cur"
26903 Trim any trailing unused memory in the PV of \f(CW\*(C`sv\*(C'\fR, which needs to have a real
26904 \&\f(CW\*(C`PV\*(C'\fR that is unencumbered by things like COW. Think first before using this
26905 functionality. Is the space saving really worth giving up COW? Will the
26906 needed size of \f(CW\*(C`sv\*(C'\fR stay the same?
26907 .Sp
26908 If the answers are both yes, then use "\f(CW\*(C`SV_CHECK_THINKFIRST\*(C'\fR" or
26909 "\f(CW\*(C`SV_CHECK_THINKFIRST_COW_DROP\*(C'\fR" before calling this.
26910 .RS 4
26911 .Sp
26912 .Vb 1
26913 \& void SvPV_shrink_to_cur(SV* sv)
26914 .Ve
26915 .RE
26916 .RS 4
26917 .RE
26918 .ie n .IP """SvPVbyte*""" 4
26919 .el .IP \f(CWSvPVbyte*\fR 4
26920 .IX Item "SvPVbyte*"
26921 Described under \f(CW"SvPV"\fR
26922 .ie n .IP """SvPVbyte_force*""" 4
26923 .el .IP \f(CWSvPVbyte_force*\fR 4
26924 .IX Item "SvPVbyte_force*"
26925 Described under \f(CW"SvPV_force"\fR
26926 .ie n .IP """SvPVbyte_nolen*""" 4
26927 .el .IP \f(CWSvPVbyte_nolen*\fR 4
26928 .IX Item "SvPVbyte_nolen*"
26929 .PD 0
26930 .ie n .IP """SvPVbyte_nomg*""" 4
26931 .el .IP \f(CWSvPVbyte_nomg*\fR 4
26932 .IX Item "SvPVbyte_nomg*"
26933 .ie n .IP """SvPVbyte_or_null*""" 4
26934 .el .IP \f(CWSvPVbyte_or_null*\fR 4
26935 .IX Item "SvPVbyte_or_null*"
26936 .ie n .IP """SvPVbyte_or_null_nomg*""" 4
26937 .el .IP \f(CWSvPVbyte_or_null_nomg*\fR 4
26938 .IX Item "SvPVbyte_or_null_nomg*"
26939 .ie n .IP """SvPVbytex*""" 4
26940 .el .IP \f(CWSvPVbytex*\fR 4
26941 .IX Item "SvPVbytex*"
26942 .PD
26943 Described under \f(CW"SvPV"\fR
26944 .ie n .IP """SvPVbytex_force*""" 4
26945 .el .IP \f(CWSvPVbytex_force*\fR 4
26946 .IX Item "SvPVbytex_force*"
26947 Described under \f(CW"SvPV_force"\fR
26948 .ie n .IP """SvPVbytex_nolen*""" 4
26949 .el .IP \f(CWSvPVbytex_nolen*\fR 4
26950 .IX Item "SvPVbytex_nolen*"
26951 Described under \f(CW"SvPV"\fR
26952 .ie n .IP """SvPVCLEAR""" 4
26953 .el .IP \f(CWSvPVCLEAR\fR 4
26954 .IX Xref "SvPVCLEAR"
26955 .IX Item "SvPVCLEAR"
26956 Ensures that sv is a SVt_PV and that its SvCUR is 0, and that it is
26957 properly null terminated. Equivalent to sv_setpvs(""), but more efficient.
26958 .RS 4
26959 .Sp
26960 .Vb 1
26961 \& char * SvPVCLEAR(SV* sv)
26962 .Ve
26963 .RE
26964 .RS 4
26965 .RE
26966 .ie n .IP """SvPVCLEAR_FRESH""" 4
26967 .el .IP \f(CWSvPVCLEAR_FRESH\fR 4
26968 .IX Xref "SvPVCLEAR_FRESH"
26969 .IX Item "SvPVCLEAR_FRESH"
26970 Like SvPVCLEAR, but optimized for newly\-minted SVt_PV/PVIV/PVNV/PVMG
26971 that already have a PV buffer allocated, but no SvTHINKFIRST.
26972 .RS 4
26973 .Sp
26974 .Vb 1
26975 \& char * SvPVCLEAR_FRESH(SV* sv)
26976 .Ve
26977 .RE
26978 .RS 4
26979 .RE
26980 .ie n .IP """SvPVutf8*""" 4
26981 .el .IP \f(CWSvPVutf8*\fR 4
26982 .IX Item "SvPVutf8*"
26983 Described under \f(CW"SvPV"\fR
26984 .ie n .IP """SvPVutf8_force*""" 4
26985 .el .IP \f(CWSvPVutf8_force*\fR 4
26986 .IX Item "SvPVutf8_force*"
26987 Described under \f(CW"SvPV_force"\fR
26988 .ie n .IP """SvPVutf8_nolen*""" 4
26989 .el .IP \f(CWSvPVutf8_nolen*\fR 4
26990 .IX Item "SvPVutf8_nolen*"
26991 .PD 0
26992 .ie n .IP """SvPVutf8_nomg*""" 4
26993 .el .IP \f(CWSvPVutf8_nomg*\fR 4
26994 .IX Item "SvPVutf8_nomg*"
26995 .ie n .IP """SvPVutf8_or_null*""" 4
26996 .el .IP \f(CWSvPVutf8_or_null*\fR 4
26997 .IX Item "SvPVutf8_or_null*"
26998 .ie n .IP """SvPVutf8_or_null_nomg*""" 4
26999 .el .IP \f(CWSvPVutf8_or_null_nomg*\fR 4
27000 .IX Item "SvPVutf8_or_null_nomg*"
27001 .ie n .IP """SvPVutf8x*""" 4
27002 .el .IP \f(CWSvPVutf8x*\fR 4
27003 .IX Item "SvPVutf8x*"
27004 .PD
27005 Described under \f(CW"SvPV"\fR
27006 .ie n .IP """SvPVutf8x_force*""" 4
27007 .el .IP \f(CWSvPVutf8x_force*\fR 4
27008 .IX Item "SvPVutf8x_force*"
27009 Described under \f(CW"SvPV_force"\fR
27010 .ie n .IP """SvPVX""" 4
27011 .el .IP \f(CWSvPVX\fR 4
27012 .IX Item "SvPVX"
27013 .PD 0
27014 .ie n .IP """SvPVX_const""" 4
27015 .el .IP \f(CWSvPVX_const\fR 4
27016 .IX Item "SvPVX_const"
27017 .ie n .IP """SvPVX_mutable""" 4
27018 .el .IP \f(CWSvPVX_mutable\fR 4
27019 .IX Item "SvPVX_mutable"
27020 .ie n .IP """SvPVXx""" 4
27021 .el .IP \f(CWSvPVXx\fR 4
27022 .IX Xref "SvPVX SvPVX_const SvPVX_mutable SvPVXx"
27023 .IX Item "SvPVXx"
27024 .PD
27025 These return a pointer to the physical string in the SV. The SV must contain a
27026 string. Prior to 5.9.3 it is not safe to execute these unless the SV\*(Aqs
27027 type >= \f(CW\*(C`SVt_PV\*(C'\fR.
27028 .Sp
27029 These are also used to store the name of an autoloaded subroutine in an XS
27030 AUTOLOAD routine. See "Autoloading with XSUBs" in perlguts.
27031 .Sp
27032 \&\f(CW\*(C`SvPVXx\*(C'\fR is identical to \f(CW\*(C`SvPVX\*(C'\fR.
27033 .Sp
27034 \&\f(CW\*(C`SvPVX_mutable\*(C'\fR is merely a synonym for \f(CW\*(C`SvPVX\*(C'\fR, but its name emphasizes that
27035 the string is modifiable by the caller.
27036 .Sp
27037 \&\f(CW\*(C`SvPVX_const\*(C'\fR differs in that the return value has been cast so that the
27038 compiler will complain if you were to try to modify the contents of the string,
27039 (unless you cast away const yourself).
27040 .RS 4
27041 .Sp
27042 .Vb 4
27043 \& char* SvPVX (SV* sv)
27044 \& const char* SvPVX_const (SV* sv)
27045 \& char* SvPVX_mutable(SV* sv)
27046 \& char* SvPVXx (SV* sv)
27047 .Ve
27048 .RE
27049 .RS 4
27050 .RE
27051 .ie n .IP """SvPVx*""" 4
27052 .el .IP \f(CWSvPVx*\fR 4
27053 .IX Item "SvPVx*"
27054 .PD 0
27055 .ie n .IP """SvPVx_const*""" 4
27056 .el .IP \f(CWSvPVx_const*\fR 4
27057 .IX Item "SvPVx_const*"
27058 .PD
27059 Described under \f(CW"SvPV"\fR
27060 .ie n .IP """SvPVx_force*""" 4
27061 .el .IP \f(CWSvPVx_force*\fR 4
27062 .IX Item "SvPVx_force*"
27063 Described under \f(CW"SvPV_force"\fR
27064 .ie n .IP """SvPVx_nolen*""" 4
27065 .el .IP \f(CWSvPVx_nolen*\fR 4
27066 .IX Item "SvPVx_nolen*"
27067 .PD 0
27068 .ie n .IP """SvPVx_nolen_const*""" 4
27069 .el .IP \f(CWSvPVx_nolen_const*\fR 4
27070 .IX Item "SvPVx_nolen_const*"
27071 .PD
27072 Described under \f(CW"SvPV"\fR
27073 .ie n .IP """SvPVXtrue""" 4
27074 .el .IP \f(CWSvPVXtrue\fR 4
27075 .IX Xref "SvPVXtrue"
27076 .IX Item "SvPVXtrue"
27077 Returns a boolean as to whether or not \f(CW\*(C`sv\*(C'\fR contains a PV that is considered
27078 TRUE. FALSE is returned if \f(CW\*(C`sv\*(C'\fR doesn\*(Aqt contain a PV, or if the PV it does
27079 contain is zero length, or consists of just the single character \*(Aq0\*(Aq. Every
27080 other PV value is considered TRUE.
27081 .Sp
27082 As of Perl v5.37.1, \f(CW\*(C`sv\*(C'\fR is evaluated exactly once; in earlier releases, it
27083 could be evaluated more than once.
27084 .RS 4
27085 .Sp
27086 .Vb 2
27087 \& bool SvPVXtrue( SV *sv)
27088 \& bool Perl_SvPVXtrue(pTHX_ SV *sv)
27089 .Ve
27090 .RE
27091 .RS 4
27092 .RE
27093 .ie n .IP """SvPVXx*""" 4
27094 .el .IP \f(CWSvPVXx*\fR 4
27095 .IX Item "SvPVXx*"
27096 Described under \f(CW"SvPVX"\fR
27097 .ie n .IP """SvREADONLY""" 4
27098 .el .IP \f(CWSvREADONLY\fR 4
27099 .IX Xref "SvREADONLY"
27100 .IX Item "SvREADONLY"
27101 Returns true if the argument is readonly, otherwise returns false.
27102 Exposed to perl code via \fBInternals::SvREADONLY()\fR.
27103 .RS 4
27104 .Sp
27105 .Vb 1
27106 \& U32 SvREADONLY(SV* sv)
27107 .Ve
27108 .RE
27109 .RS 4
27110 .RE
27111 .ie n .IP """SvREADONLY_off""" 4
27112 .el .IP \f(CWSvREADONLY_off\fR 4
27113 .IX Xref "SvREADONLY_off"
27114 .IX Item "SvREADONLY_off"
27115 Mark an object as not\-readonly. Exactly what this mean depends on the
27116 object type. Exposed to perl code via \fBInternals::SvREADONLY()\fR.
27117 .RS 4
27118 .Sp
27119 .Vb 1
27120 \& U32 SvREADONLY_off(SV* sv)
27121 .Ve
27122 .RE
27123 .RS 4
27124 .RE
27125 .ie n .IP """SvREADONLY_on""" 4
27126 .el .IP \f(CWSvREADONLY_on\fR 4
27127 .IX Xref "SvREADONLY_on"
27128 .IX Item "SvREADONLY_on"
27129 Mark an object as readonly. Exactly what this means depends on the object
27130 type. Exposed to perl code via \fBInternals::SvREADONLY()\fR.
27131 .RS 4
27132 .Sp
27133 .Vb 1
27134 \& U32 SvREADONLY_on(SV* sv)
27135 .Ve
27136 .RE
27137 .RS 4
27138 .RE
27139 .ie n .IP """SvREFCNT""" 4
27140 .el .IP \f(CWSvREFCNT\fR 4
27141 .IX Xref "SvREFCNT"
27142 .IX Item "SvREFCNT"
27143 Returns the value of the object\*(Aqs reference count. Exposed
27144 to perl code via \fBInternals::SvREFCNT()\fR.
27145 .RS 4
27146 .Sp
27147 .Vb 1
27148 \& U32 SvREFCNT(SV* sv)
27149 .Ve
27150 .RE
27151 .RS 4
27152 .RE
27153 .ie n .IP """SvREFCNT_dec""" 4
27154 .el .IP \f(CWSvREFCNT_dec\fR 4
27155 .IX Item "SvREFCNT_dec"
27156 .PD 0
27157 .ie n .IP """SvREFCNT_dec_set_NULL""" 4
27158 .el .IP \f(CWSvREFCNT_dec_set_NULL\fR 4
27159 .IX Item "SvREFCNT_dec_set_NULL"
27160 .ie n .IP """SvREFCNT_dec_ret_NULL""" 4
27161 .el .IP \f(CWSvREFCNT_dec_ret_NULL\fR 4
27162 .IX Item "SvREFCNT_dec_ret_NULL"
27163 .ie n .IP """SvREFCNT_dec_NN""" 4
27164 .el .IP \f(CWSvREFCNT_dec_NN\fR 4
27165 .IX Xref "SvREFCNT_dec SvREFCNT_dec_NN SvREFCNT_dec_ret_NULL SvREFCNT_dec_set_NULL"
27166 .IX Item "SvREFCNT_dec_NN"
27167 .PD
27168 These decrement the reference count of the given SV.
27169 .Sp
27170 \&\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.
27171 .Sp
27172 The function \f(CWSvREFCNT_dec_ret_NULL()\fR is identical to the
27173 \&\f(CWSvREFCNT_dec()\fR except it returns a NULL \f(CW\*(C`SV *\*(C'\fR. It is used by
27174 \&\f(CWSvREFCNT_dec_set_NULL()\fR which is a macro which will, when passed a
27175 non\-NULL argument, decrement the reference count of its argument and
27176 then set it to NULL. You can replace code of the following form:
27177 .Sp
27178 .Vb 4
27179 \& if (sv) {
27180 \& SvREFCNT_dec_NN(sv);
27181 \& sv = NULL;
27182 \& }
27183 .Ve
27184 .Sp
27185 with
27186 .Sp
27187 .Vb 1
27188 \& SvREFCNT_dec_set_NULL(sv);
27189 .Ve
27190 .RS 4
27191 .Sp
27192 .Vb 7
27193 \& void SvREFCNT_dec ( SV *sv)
27194 \& void Perl_SvREFCNT_dec (pTHX_ SV *sv)
27195 \& void SvREFCNT_dec_set_NULL( SV *sv)
27196 \& SV * SvREFCNT_dec_ret_NULL( SV *sv)
27197 \& SV * Perl_SvREFCNT_dec_ret_NULL(pTHX_ SV *sv)
27198 \& void SvREFCNT_dec_NN ( SV *sv)
27199 \& void Perl_SvREFCNT_dec_NN (pTHX_ SV *sv)
27200 .Ve
27201 .RE
27202 .RS 4
27203 .RE
27204 .ie n .IP """SvREFCNT_inc""" 4
27205 .el .IP \f(CWSvREFCNT_inc\fR 4
27206 .IX Item "SvREFCNT_inc"
27207 .PD 0
27208 .ie n .IP """SvREFCNT_inc_NN""" 4
27209 .el .IP \f(CWSvREFCNT_inc_NN\fR 4
27210 .IX Item "SvREFCNT_inc_NN"
27211 .ie n .IP """SvREFCNT_inc_simple""" 4
27212 .el .IP \f(CWSvREFCNT_inc_simple\fR 4
27213 .IX Item "SvREFCNT_inc_simple"
27214 .ie n .IP """SvREFCNT_inc_simple_NN""" 4
27215 .el .IP \f(CWSvREFCNT_inc_simple_NN\fR 4
27216 .IX Item "SvREFCNT_inc_simple_NN"
27217 .ie n .IP """SvREFCNT_inc_simple_void""" 4
27218 .el .IP \f(CWSvREFCNT_inc_simple_void\fR 4
27219 .IX Item "SvREFCNT_inc_simple_void"
27220 .ie n .IP """SvREFCNT_inc_simple_void_NN""" 4
27221 .el .IP \f(CWSvREFCNT_inc_simple_void_NN\fR 4
27222 .IX Item "SvREFCNT_inc_simple_void_NN"
27223 .ie n .IP """SvREFCNT_inc_void""" 4
27224 .el .IP \f(CWSvREFCNT_inc_void\fR 4
27225 .IX Item "SvREFCNT_inc_void"
27226 .ie n .IP """SvREFCNT_inc_void_NN""" 4
27227 .el .IP \f(CWSvREFCNT_inc_void_NN\fR 4
27228 .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"
27229 .IX Item "SvREFCNT_inc_void_NN"
27230 .PD
27231 These all increment the reference count of the given SV.
27232 The ones without \f(CW\*(C`void\*(C'\fR in their names return the SV.
27233 .Sp
27234 \&\f(CW\*(C`SvREFCNT_inc\*(C'\fR is the base operation; the rest are optimizations if various
27235 input constraints are known to be true; hence, all can be replaced with
27236 \&\f(CW\*(C`SvREFCNT_inc\*(C'\fR.
27237 .Sp
27238 \&\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
27239 don\*(Aqt have to check the NULLness, it\*(Aqs faster and smaller.
27240 .Sp
27241 \&\f(CW\*(C`SvREFCNT_inc_void\*(C'\fR can only be used if you don\*(Aqt need the
27242 return value. The macro doesn\*(Aqt need to return a meaningful value.
27243 .Sp
27244 \&\f(CW\*(C`SvREFCNT_inc_void_NN\*(C'\fR can only be used if you both don\*(Aqt need the return
27245 value, and you know that \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. The macro doesn\*(Aqt need to
27246 return a meaningful value, or check for NULLness, so it\*(Aqs smaller and faster.
27247 .Sp
27248 \&\f(CW\*(C`SvREFCNT_inc_simple\*(C'\fR can only be used with expressions without side
27249 effects. Since we don\*(Aqt have to store a temporary value, it\*(Aqs faster.
27250 .Sp
27251 \&\f(CW\*(C`SvREFCNT_inc_simple_NN\*(C'\fR can only be used with expressions without side
27252 effects and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR. Since we don\*(Aqt have to store a
27253 temporary value, nor check for NULLness, it\*(Aqs faster and smaller.
27254 .Sp
27255 \&\f(CW\*(C`SvREFCNT_inc_simple_void\*(C'\fR can only be used with expressions without side
27256 effects and you don\*(Aqt need the return value.
27257 .Sp
27258 \&\f(CW\*(C`SvREFCNT_inc_simple_void_NN\*(C'\fR can only be used with expressions without side
27259 effects, you don\*(Aqt need the return value, and you know \f(CW\*(C`sv\*(C'\fR is not \f(CW\*(C`NULL\*(C'\fR.
27260 .RS 4
27261 .Sp
27262 .Vb 11
27263 \& SV * SvREFCNT_inc (SV *sv)
27264 \& SV * Perl_SvREFCNT_inc (SV *sv)
27265 \& SV * SvREFCNT_inc_NN (SV *sv)
27266 \& SV * Perl_SvREFCNT_inc_NN (SV *sv)
27267 \& SV * SvREFCNT_inc_simple (SV *sv)
27268 \& SV * SvREFCNT_inc_simple_NN (SV *sv)
27269 \& void SvREFCNT_inc_simple_void (SV *sv)
27270 \& void SvREFCNT_inc_simple_void_NN(SV *sv)
27271 \& void SvREFCNT_inc_void (SV *sv)
27272 \& void Perl_SvREFCNT_inc_void (SV *sv)
27273 \& void SvREFCNT_inc_void_NN (SV *sv)
27274 .Ve
27275 .RE
27276 .RS 4
27277 .RE
27278 .ie n .IP """SvROK""" 4
27279 .el .IP \f(CWSvROK\fR 4
27280 .IX Xref "SvROK"
27281 .IX Item "SvROK"
27282 Tests if the SV is an RV.
27283 .RS 4
27284 .Sp
27285 .Vb 1
27286 \& U32 SvROK(SV* sv)
27287 .Ve
27288 .RE
27289 .RS 4
27290 .RE
27291 .ie n .IP """SvROK_off""" 4
27292 .el .IP \f(CWSvROK_off\fR 4
27293 .IX Xref "SvROK_off"
27294 .IX Item "SvROK_off"
27295 Unsets the RV status of an SV.
27296 .RS 4
27297 .Sp
27298 .Vb 1
27299 \& void SvROK_off(SV* sv)
27300 .Ve
27301 .RE
27302 .RS 4
27303 .RE
27304 .ie n .IP """SvROK_on""" 4
27305 .el .IP \f(CWSvROK_on\fR 4
27306 .IX Xref "SvROK_on"
27307 .IX Item "SvROK_on"
27308 Tells an SV that it is an RV.
27309 .RS 4
27310 .Sp
27311 .Vb 1
27312 \& void SvROK_on(SV* sv)
27313 .Ve
27314 .RE
27315 .RS 4
27316 .RE
27317 .ie n .IP """SvRV""" 4
27318 .el .IP \f(CWSvRV\fR 4
27319 .IX Xref "SvRV"
27320 .IX Item "SvRV"
27321 Dereferences an RV to return the SV.
27322 .RS 4
27323 .Sp
27324 .Vb 1
27325 \& SV* SvRV(SV* sv)
27326 .Ve
27327 .RE
27328 .RS 4
27329 .RE
27330 .ie n .IP """SvRV_set""" 4
27331 .el .IP \f(CWSvRV_set\fR 4
27332 .IX Xref "SvRV_set"
27333 .IX Item "SvRV_set"
27334 Set the value of the RV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
27335 .RS 4
27336 .Sp
27337 .Vb 1
27338 \& void SvRV_set(SV* sv, SV* val)
27339 .Ve
27340 .RE
27341 .RS 4
27342 .RE
27343 .ie n .IP """SvSETMAGIC""" 4
27344 .el .IP \f(CWSvSETMAGIC\fR 4
27345 .IX Xref "SvSETMAGIC"
27346 .IX Item "SvSETMAGIC"
27347 Invokes \f(CW"mg_set"\fR on an SV if it has \*(Aqset\*(Aq magic. This is necessary
27348 after modifying a scalar, in case it is a magical variable like \f(CW$|\fR
27349 or a tied variable (it calls \f(CW\*(C`STORE\*(C'\fR). This macro evaluates its
27350 argument more than once.
27351 .RS 4
27352 .Sp
27353 .Vb 1
27354 \& void SvSETMAGIC(SV* sv)
27355 .Ve
27356 .RE
27357 .RS 4
27358 .RE
27359 .ie n .IP """SvSetMagicSV""" 4
27360 .el .IP \f(CWSvSetMagicSV\fR 4
27361 .IX Item "SvSetMagicSV"
27362 .PD 0
27363 .ie n .IP """SvSetMagicSV_nosteal""" 4
27364 .el .IP \f(CWSvSetMagicSV_nosteal\fR 4
27365 .IX Item "SvSetMagicSV_nosteal"
27366 .ie n .IP """SvSetSV""" 4
27367 .el .IP \f(CWSvSetSV\fR 4
27368 .IX Item "SvSetSV"
27369 .ie n .IP """SvSetSV_nosteal""" 4
27370 .el .IP \f(CWSvSetSV_nosteal\fR 4
27371 .IX Xref "SvSetMagicSV SvSetMagicSV_nosteal SvSetSV SvSetSV_nosteal"
27372 .IX Item "SvSetSV_nosteal"
27373 .PD
27374 if \f(CW\*(C`dsv\*(C'\fR is the same as \f(CW\*(C`ssv\*(C'\fR, these do nothing. Otherwise they all call
27375 some form of \f(CW"sv_setsv"\fR. They may evaluate their arguments more than
27376 once.
27377 .Sp
27378 The only differences are:
27379 .Sp
27380 \&\f(CW\*(C`SvSetMagicSV\*(C'\fR and \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR perform any required \*(Aqset\*(Aq magic
27381 afterwards on the destination SV; \f(CW\*(C`SvSetSV\*(C'\fR and \f(CW\*(C`SvSetSV_nosteal\*(C'\fR do not.
27382 .Sp
27383 \&\f(CW\*(C`SvSetSV_nosteal\*(C'\fR \f(CW\*(C`SvSetMagicSV_nosteal\*(C'\fR call a non\-destructive version of
27384 \&\f(CW\*(C`sv_setsv\*(C'\fR.
27385 .RS 4
27386 .Sp
27387 .Vb 4
27388 \& void SvSetMagicSV (SV* dsv, SV* ssv)
27389 \& void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
27390 \& void SvSetSV (SV* dsv, SV* ssv)
27391 \& void SvSetSV_nosteal (SV* dsv, SV* ssv)
27392 .Ve
27393 .RE
27394 .RS 4
27395 .RE
27396 .ie n .IP """SvSHARE""" 4
27397 .el .IP \f(CWSvSHARE\fR 4
27398 .IX Xref "SvSHARE"
27399 .IX Item "SvSHARE"
27400 Arranges for \f(CW\*(C`sv\*(C'\fR to be shared between threads if a suitable module
27401 has been loaded.
27402 .RS 4
27403 .Sp
27404 .Vb 1
27405 \& void SvSHARE(SV* sv)
27406 .Ve
27407 .RE
27408 .RS 4
27409 .RE
27410 .ie n .IP """SvSHARED_HASH""" 4
27411 .el .IP \f(CWSvSHARED_HASH\fR 4
27412 .IX Xref "SvSHARED_HASH"
27413 .IX Item "SvSHARED_HASH"
27414 Returns the hash for \f(CW\*(C`sv\*(C'\fR created by \f(CW"newSVpvn_share"\fR.
27415 .RS 4
27416 .Sp
27417 .Vb 1
27418 \& struct hek* SvSHARED_HASH(SV * sv)
27419 .Ve
27420 .RE
27421 .RS 4
27422 .RE
27423 .ie n .IP """SvSTASH""" 4
27424 .el .IP \f(CWSvSTASH\fR 4
27425 .IX Xref "SvSTASH"
27426 .IX Item "SvSTASH"
27427 Returns the stash of the SV.
27428 .RS 4
27429 .Sp
27430 .Vb 1
27431 \& HV* SvSTASH(SV* sv)
27432 .Ve
27433 .RE
27434 .RS 4
27435 .RE
27436 .ie n .IP """SvSTASH_set""" 4
27437 .el .IP \f(CWSvSTASH_set\fR 4
27438 .IX Xref "SvSTASH_set"
27439 .IX Item "SvSTASH_set"
27440 Set the value of the STASH pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
27441 .RS 4
27442 .Sp
27443 .Vb 1
27444 \& void SvSTASH_set(SV* sv, HV* val)
27445 .Ve
27446 .RE
27447 .RS 4
27448 .RE
27449 .ie n .IP """SvTRUE""" 4
27450 .el .IP \f(CWSvTRUE\fR 4
27451 .IX Item "SvTRUE"
27452 .PD 0
27453 .ie n .IP """SvTRUE_NN""" 4
27454 .el .IP \f(CWSvTRUE_NN\fR 4
27455 .IX Item "SvTRUE_NN"
27456 .ie n .IP """SvTRUE_nomg""" 4
27457 .el .IP \f(CWSvTRUE_nomg\fR 4
27458 .IX Item "SvTRUE_nomg"
27459 .ie n .IP """SvTRUE_nomg_NN""" 4
27460 .el .IP \f(CWSvTRUE_nomg_NN\fR 4
27461 .IX Item "SvTRUE_nomg_NN"
27462 .ie n .IP """SvTRUEx""" 4
27463 .el .IP \f(CWSvTRUEx\fR 4
27464 .IX Xref "SvTRUE SvTRUE_NN SvTRUE_nomg SvTRUE_nomg_NN SvTRUEx"
27465 .IX Item "SvTRUEx"
27466 .PD
27467 These return a boolean indicating whether Perl would evaluate the SV as true or
27468 false. See \f(CW"SvOK"\fR for a defined/undefined test.
27469 .Sp
27470 As of Perl 5.32, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once. Prior to that
27471 release, only \f(CW\*(C`SvTRUEx\*(C'\fR guaranteed single evaluation; now \f(CW\*(C`SvTRUEx\*(C'\fR is
27472 identical to \f(CW\*(C`SvTRUE\*(C'\fR.
27473 .Sp
27474 \&\f(CW\*(C`SvTRUE_nomg\*(C'\fR and \f(CW\*(C`TRUE_nomg_NN\*(C'\fR do not perform \*(Aqget\*(Aq magic; the others do
27475 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
27476 the private flags).
27477 .Sp
27478 \&\f(CW\*(C`SvTRUE_NN\*(C'\fR is like \f(CW"SvTRUE"\fR, but \f(CW\*(C`sv\*(C'\fR is assumed to be
27479 non\-null (NN). If there is a possibility that it is NULL, use plain
27480 \&\f(CW\*(C`SvTRUE\*(C'\fR.
27481 .Sp
27482 \&\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
27483 non\-null (NN). If there is a possibility that it is NULL, use plain
27484 \&\f(CW\*(C`SvTRUE_nomg\*(C'\fR.
27485 .RS 4
27486 .Sp
27487 .Vb 8
27488 \& bool SvTRUE ( SV *sv)
27489 \& bool Perl_SvTRUE (pTHX_ SV *sv)
27490 \& bool SvTRUE_NN ( SV *sv)
27491 \& bool Perl_SvTRUE_NN (pTHX_ SV *sv)
27492 \& bool SvTRUE_nomg ( SV *sv)
27493 \& bool Perl_SvTRUE_nomg (pTHX_ SV *sv)
27494 \& bool SvTRUE_nomg_NN( SV *sv)
27495 \& bool SvTRUEx ( SV *sv)
27496 .Ve
27497 .RE
27498 .RS 4
27499 .RE
27500 .ie n .IP """SvTYPE""" 4
27501 .el .IP \f(CWSvTYPE\fR 4
27502 .IX Xref "SvTYPE"
27503 .IX Item "SvTYPE"
27504 Returns the type of the SV. See \f(CW"svtype"\fR.
27505 .RS 4
27506 .Sp
27507 .Vb 1
27508 \& svtype SvTYPE(SV* sv)
27509 .Ve
27510 .RE
27511 .RS 4
27512 .RE
27513 .ie n .IP """SvUNLOCK""" 4
27514 .el .IP \f(CWSvUNLOCK\fR 4
27515 .IX Xref "SvUNLOCK"
27516 .IX Item "SvUNLOCK"
27517 Releases a mutual exclusion lock on \f(CW\*(C`sv\*(C'\fR if a suitable module
27518 has been loaded.
27519 .RS 4
27520 .Sp
27521 .Vb 1
27522 \& void SvUNLOCK(SV* sv)
27523 .Ve
27524 .RE
27525 .RS 4
27526 .RE
27527 .ie n .IP """SvUOK""" 4
27528 .el .IP \f(CWSvUOK\fR 4
27529 .IX Xref "SvUOK"
27530 .IX Item "SvUOK"
27531 Returns a boolean indicating whether the SV contains an integer that must be
27532 interpreted as unsigned. A non\-negative integer whose value is within the
27533 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.
27534 .RS 4
27535 .Sp
27536 .Vb 1
27537 \& bool SvUOK(SV* sv)
27538 .Ve
27539 .RE
27540 .RS 4
27541 .RE
27542 .ie n .IP """SvUPGRADE""" 4
27543 .el .IP \f(CWSvUPGRADE\fR 4
27544 .IX Xref "SvUPGRADE"
27545 .IX Item "SvUPGRADE"
27546 Used to upgrade an SV to a more complex form. Uses \f(CW\*(C`sv_upgrade\*(C'\fR to
27547 perform the upgrade if necessary. See \f(CW"svtype"\fR.
27548 .RS 4
27549 .Sp
27550 .Vb 1
27551 \& void SvUPGRADE(SV* sv, svtype type)
27552 .Ve
27553 .RE
27554 .RS 4
27555 .RE
27556 .ie n .IP """SvUTF8""" 4
27557 .el .IP \f(CWSvUTF8\fR 4
27558 .IX Xref "SvUTF8"
27559 .IX Item "SvUTF8"
27560 Returns a U32 value indicating the UTF\-8 status of an SV. If things are set\-up
27561 properly, this indicates whether or not the SV contains UTF\-8 encoded data.
27562 You should use this \fIafter\fR a call to \f(CW"SvPV"\fR or one of its variants, in
27563 case any call to string overloading updates the internal flag.
27564 .Sp
27565 If you want to take into account the bytes pragma, use \f(CW"DO_UTF8"\fR
27566 instead.
27567 .RS 4
27568 .Sp
27569 .Vb 1
27570 \& U32 SvUTF8(SV* sv)
27571 .Ve
27572 .RE
27573 .RS 4
27574 .RE
27575 .ie n .IP """SvUTF8_off""" 4
27576 .el .IP \f(CWSvUTF8_off\fR 4
27577 .IX Xref "SvUTF8_off"
27578 .IX Item "SvUTF8_off"
27579 Unsets the UTF\-8 status of an SV (the data is not changed, just the flag).
27580 Do not use frivolously.
27581 .RS 4
27582 .Sp
27583 .Vb 1
27584 \& void SvUTF8_off(SV *sv)
27585 .Ve
27586 .RE
27587 .RS 4
27588 .RE
27589 .ie n .IP """SvUTF8_on""" 4
27590 .el .IP \f(CWSvUTF8_on\fR 4
27591 .IX Xref "SvUTF8_on"
27592 .IX Item "SvUTF8_on"
27593 Turn on the UTF\-8 status of an SV (the data is not changed, just the flag).
27594 Do not use frivolously.
27595 .RS 4
27596 .Sp
27597 .Vb 1
27598 \& void SvUTF8_on(SV *sv)
27599 .Ve
27600 .RE
27601 .RS 4
27602 .RE
27603 .ie n .IP """SvUV""" 4
27604 .el .IP \f(CWSvUV\fR 4
27605 .IX Item "SvUV"
27606 .PD 0
27607 .ie n .IP """SvUV_nomg""" 4
27608 .el .IP \f(CWSvUV_nomg\fR 4
27609 .IX Item "SvUV_nomg"
27610 .ie n .IP """SvUVx""" 4
27611 .el .IP \f(CWSvUVx\fR 4
27612 .IX Xref "SvUV SvUV_nomg SvUVx"
27613 .IX Item "SvUVx"
27614 .PD
27615 These each coerce the given SV to UV and return it. The returned value in many
27616 circumstances will get stored in \f(CW\*(C`sv\*(C'\fR\*(Aqs UV slot, but not in all cases. (Use
27617 \&\f(CW"sv_setuv"\fR to make sure it does).
27618 .Sp
27619 As of 5.37.1, all are guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
27620 .Sp
27621 \&\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
27622 guaranteed to evaluate \f(CW\*(C`sv\*(C'\fR only once.
27623 .RS 4
27624 .Sp
27625 .Vb 5
27626 \& UV SvUV ( SV *sv)
27627 \& UV Perl_SvUV (pTHX_ SV *sv)
27628 \& UV SvUV_nomg( SV *sv)
27629 \& UV Perl_SvUV_nomg(pTHX_ SV *sv)
27630 \& UV SvUVx ( SV *sv)
27631 .Ve
27632 .RE
27633 .RS 4
27634 .RE
27635 .ie n .IP """SvUV_set""" 4
27636 .el .IP \f(CWSvUV_set\fR 4
27637 .IX Xref "SvUV_set"
27638 .IX Item "SvUV_set"
27639 Set the value of the UV pointer in \f(CW\*(C`sv\*(C'\fR to val. See \f(CW"SvIV_set"\fR.
27640 .RS 4
27641 .Sp
27642 .Vb 1
27643 \& void SvUV_set(SV* sv, UV val)
27644 .Ve
27645 .RE
27646 .RS 4
27647 .RE
27648 .ie n .IP """SvUVX""" 4
27649 .el .IP \f(CWSvUVX\fR 4
27650 .IX Xref "SvUVX"
27651 .IX Item "SvUVX"
27652 Returns the raw value in the SV\*(Aqs UV slot, without checks or conversions.
27653 Only use when you are sure \f(CW\*(C`SvIOK\*(C'\fR is true. See also \f(CW"SvUV"\fR.
27654 .RS 4
27655 .Sp
27656 .Vb 1
27657 \& UV SvUVX(SV* sv)
27658 .Ve
27659 .RE
27660 .RS 4
27661 .RE
27662 .ie n .IP """SvUVx*""" 4
27663 .el .IP \f(CWSvUVx*\fR 4
27664 .IX Item "SvUVx*"
27665 Described under \f(CW"SvUV"\fR
27666 .ie n .IP """SvUVXx""" 4
27667 .el .IP \f(CWSvUVXx\fR 4
27668 .IX Xref "SvUVXx"
27669 .IX Item "SvUVXx"
27670 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`SvUVXx\*(C'\fR
27671 from a future release of Perl. Do not use it for
27672 new code; remove it from existing code.
27673 .Sp
27674 This is an unnecessary synonym for "SvUVX"
27675 .RS 4
27676 .Sp
27677 .Vb 1
27678 \& UV SvUVXx(SV* sv)
27679 .Ve
27680 .RE
27681 .RS 4
27682 .RE
27683 .ie n .IP """SvVOK""" 4
27684 .el .IP \f(CWSvVOK\fR 4
27685 .IX Xref "SvVOK"
27686 .IX Item "SvVOK"
27687 Returns a boolean indicating whether the SV contains a v\-string.
27688 .RS 4
27689 .Sp
27690 .Vb 1
27691 \& bool SvVOK(SV* sv)
27692 .Ve
27693 .RE
27694 .RS 4
27695 .RE
27696 .ie n .IP """SvVSTRING_mg""" 4
27697 .el .IP \f(CWSvVSTRING_mg\fR 4
27698 .IX Xref "SvVSTRING_mg"
27699 .IX Item "SvVSTRING_mg"
27700 Returns the vstring magic, or NULL if none
27701 .RS 4
27702 .Sp
27703 .Vb 1
27704 \& MAGIC* SvVSTRING_mg(SV * sv)
27705 .Ve
27706 .RE
27707 .RS 4
27708 .RE
27709 .ie n .IP """uiv_2buf""" 4
27710 .el .IP \f(CWuiv_2buf\fR 4
27711 .IX Xref "uiv_2buf"
27712 .IX Item "uiv_2buf"
27713 This function converts an IV or UV to its string representation.
27714 .Sp
27715 It is used internally by \fBsv_2pv_flags()\fR and \fBdo_print()\fR.
27716 .RS 4
27717 .Sp
27718 .Vb 4
27719 \& char * uiv_2buf(char * const buf, const IV iv, UV uv,
27720 \& const int is_uv, char ** const peob)
27721 \& char * Perl_uiv_2buf(char * const buf, const IV iv, UV uv,
27722 \& const int is_uv, char ** const peob)
27723 .Ve
27724 .RE
27725 .RS 4
27726 .RE
27727 .ie n .IP """vnewSVpvf""" 4
27728 .el .IP \f(CWvnewSVpvf\fR 4
27729 .IX Xref "vnewSVpvf"
27730 .IX Item "vnewSVpvf"
27731 Like \f(CW"newSVpvf"\fR but the arguments are an encapsulated argument list.
27732 .RS 4
27733 .Sp
27734 .Vb 4
27735 \& SV * vnewSVpvf( const char * const pat,
27736 \& va_list * const args)
27737 \& SV * Perl_vnewSVpvf(pTHX_ const char * const pat,
27738 \& va_list * const args)
27739 .Ve
27740 .RE
27741 .RS 4
27742 .RE
27743 .SH Tainting
27744 .IX Header "Tainting"
27745 .ie n .IP """SvTAINT""" 4
27746 .el .IP \f(CWSvTAINT\fR 4
27747 .IX Xref "SvTAINT"
27748 .IX Item "SvTAINT"
27749 Taints an SV if tainting is enabled, and if some input to the current
27750 expression is tainted\-\-usually a variable, but possibly also implicit
27751 inputs such as locale settings. \f(CW\*(C`SvTAINT\*(C'\fR propagates that taintedness to
27752 the outputs of an expression in a pessimistic fashion; i.e., without paying
27753 attention to precisely which outputs are influenced by which inputs.
27754 .RS 4
27755 .Sp
27756 .Vb 1
27757 \& void SvTAINT(SV* sv)
27758 .Ve
27759 .RE
27760 .RS 4
27761 .RE
27762 .ie n .IP """SvTAINTED""" 4
27763 .el .IP \f(CWSvTAINTED\fR 4
27764 .IX Xref "SvTAINTED"
27765 .IX Item "SvTAINTED"
27766 Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
27767 not.
27768 .RS 4
27769 .Sp
27770 .Vb 1
27771 \& bool SvTAINTED(SV* sv)
27772 .Ve
27773 .RE
27774 .RS 4
27775 .RE
27776 .ie n .IP """SvTAINTED_off""" 4
27777 .el .IP \f(CWSvTAINTED_off\fR 4
27778 .IX Xref "SvTAINTED_off"
27779 .IX Item "SvTAINTED_off"
27780 Untaints an SV. Be \fIvery\fR careful with this routine, as it short\-circuits
27781 some of Perl\*(Aqs fundamental security features. XS module authors should not
27782 use this function unless they fully understand all the implications of
27783 unconditionally untainting the value. Untainting should be done in the
27784 standard perl fashion, via a carefully crafted regexp, rather than directly
27785 untainting variables.
27786 .RS 4
27787 .Sp
27788 .Vb 1
27789 \& void SvTAINTED_off(SV* sv)
27790 .Ve
27791 .RE
27792 .RS 4
27793 .RE
27794 .ie n .IP """SvTAINTED_on""" 4
27795 .el .IP \f(CWSvTAINTED_on\fR 4
27796 .IX Xref "SvTAINTED_on"
27797 .IX Item "SvTAINTED_on"
27798 Marks an SV as tainted if tainting is enabled.
27799 .RS 4
27800 .Sp
27801 .Vb 1
27802 \& void SvTAINTED_on(SV* sv)
27803 .Ve
27804 .RE
27805 .RS 4
27806 .RE
27807 .SH Time
27808 .IX Header "Time"
27809 .ie n .IP """ASCTIME_R_PROTO""" 4
27810 .el .IP \f(CWASCTIME_R_PROTO\fR 4
27811 .IX Xref "ASCTIME_R_PROTO"
27812 .IX Item "ASCTIME_R_PROTO"
27813 This symbol encodes the prototype of \f(CW\*(C`asctime_r\*(C'\fR.
27814 It is zero if \f(CW\*(C`d_asctime_r\*(C'\fR is undef, and one of the
27815 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_asctime_r\*(C'\fR
27816 is defined.
27817 .ie n .IP """CTIME_R_PROTO""" 4
27818 .el .IP \f(CWCTIME_R_PROTO\fR 4
27819 .IX Xref "CTIME_R_PROTO"
27820 .IX Item "CTIME_R_PROTO"
27821 This symbol encodes the prototype of \f(CW\*(C`ctime_r\*(C'\fR.
27822 It is zero if \f(CW\*(C`d_ctime_r\*(C'\fR is undef, and one of the
27823 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_ctime_r\*(C'\fR
27824 is defined.
27825 .ie n .IP """GMTIME_MAX""" 4
27826 .el .IP \f(CWGMTIME_MAX\fR 4
27827 .IX Xref "GMTIME_MAX"
27828 .IX Item "GMTIME_MAX"
27829 This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that
27830 the system function gmtime () accepts, and defaults to 0
27831 .ie n .IP """GMTIME_MIN""" 4
27832 .el .IP \f(CWGMTIME_MIN\fR 4
27833 .IX Xref "GMTIME_MIN"
27834 .IX Item "GMTIME_MIN"
27835 This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that
27836 the system function gmtime () accepts, and defaults to 0
27837 .ie n .IP """GMTIME_R_PROTO""" 4
27838 .el .IP \f(CWGMTIME_R_PROTO\fR 4
27839 .IX Xref "GMTIME_R_PROTO"
27840 .IX Item "GMTIME_R_PROTO"
27841 This symbol encodes the prototype of \f(CW\*(C`gmtime_r\*(C'\fR.
27842 It is zero if \f(CW\*(C`d_gmtime_r\*(C'\fR is undef, and one of the
27843 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_gmtime_r\*(C'\fR
27844 is defined.
27845 .ie n .IP """HAS_ASCTIME_R""" 4
27846 .el .IP \f(CWHAS_ASCTIME_R\fR 4
27847 .IX Xref "HAS_ASCTIME_R"
27848 .IX Item "HAS_ASCTIME_R"
27849 This symbol, if defined, indicates that the \f(CW\*(C`asctime_r\*(C'\fR routine
27850 is available to asctime re\-entrantly.
27851 .ie n .IP """HAS_ASCTIME64""" 4
27852 .el .IP \f(CWHAS_ASCTIME64\fR 4
27853 .IX Xref "HAS_ASCTIME64"
27854 .IX Item "HAS_ASCTIME64"
27855 This symbol, if defined, indicates that the \f(CW\*(C`asctime64\*(C'\fR () routine is
27856 available to do the 64bit variant of asctime ()
27857 .ie n .IP """HAS_CTIME_R""" 4
27858 .el .IP \f(CWHAS_CTIME_R\fR 4
27859 .IX Xref "HAS_CTIME_R"
27860 .IX Item "HAS_CTIME_R"
27861 This symbol, if defined, indicates that the \f(CW\*(C`ctime_r\*(C'\fR routine
27862 is available to ctime re\-entrantly.
27863 .ie n .IP """HAS_CTIME64""" 4
27864 .el .IP \f(CWHAS_CTIME64\fR 4
27865 .IX Xref "HAS_CTIME64"
27866 .IX Item "HAS_CTIME64"
27867 This symbol, if defined, indicates that the \f(CW\*(C`ctime64\*(C'\fR () routine is
27868 available to do the 64bit variant of ctime ()
27869 .ie n .IP """HAS_DIFFTIME""" 4
27870 .el .IP \f(CWHAS_DIFFTIME\fR 4
27871 .IX Xref "HAS_DIFFTIME"
27872 .IX Item "HAS_DIFFTIME"
27873 This symbol, if defined, indicates that the \f(CW\*(C`difftime\*(C'\fR routine is
27874 available.
27875 .ie n .IP """HAS_DIFFTIME64""" 4
27876 .el .IP \f(CWHAS_DIFFTIME64\fR 4
27877 .IX Xref "HAS_DIFFTIME64"
27878 .IX Item "HAS_DIFFTIME64"
27879 This symbol, if defined, indicates that the \f(CW\*(C`difftime64\*(C'\fR () routine is
27880 available to do the 64bit variant of difftime ()
27881 .ie n .IP """HAS_FUTIMES""" 4
27882 .el .IP \f(CWHAS_FUTIMES\fR 4
27883 .IX Xref "HAS_FUTIMES"
27884 .IX Item "HAS_FUTIMES"
27885 This symbol, if defined, indicates that the \f(CW\*(C`futimes\*(C'\fR routine is
27886 available to change file descriptor time stamps with \f(CW\*(C`struct timevals\*(C'\fR.
27887 .ie n .IP """HAS_GETITIMER""" 4
27888 .el .IP \f(CWHAS_GETITIMER\fR 4
27889 .IX Xref "HAS_GETITIMER"
27890 .IX Item "HAS_GETITIMER"
27891 This symbol, if defined, indicates that the \f(CW\*(C`getitimer\*(C'\fR routine is
27892 available to return interval timers.
27893 .ie n .IP """HAS_GETTIMEOFDAY""" 4
27894 .el .IP \f(CWHAS_GETTIMEOFDAY\fR 4
27895 .IX Xref "HAS_GETTIMEOFDAY"
27896 .IX Item "HAS_GETTIMEOFDAY"
27897 This symbol, if defined, indicates that the \f(CWgettimeofday()\fR system
27898 call is available for a sub\-second accuracy clock. Usually, the file
27899 \&\fIsys/resource.h\fR needs to be included (see \f(CW"I_SYS_RESOURCE"\fR).
27900 The type "Timeval" should be used to refer to "\f(CW\*(C`struct timeval\*(C'\fR".
27901 .ie n .IP """HAS_GMTIME_R""" 4
27902 .el .IP \f(CWHAS_GMTIME_R\fR 4
27903 .IX Xref "HAS_GMTIME_R"
27904 .IX Item "HAS_GMTIME_R"
27905 This symbol, if defined, indicates that the \f(CW\*(C`gmtime_r\*(C'\fR routine
27906 is available to gmtime re\-entrantly.
27907 .ie n .IP """HAS_GMTIME64""" 4
27908 .el .IP \f(CWHAS_GMTIME64\fR 4
27909 .IX Xref "HAS_GMTIME64"
27910 .IX Item "HAS_GMTIME64"
27911 This symbol, if defined, indicates that the \f(CW\*(C`gmtime64\*(C'\fR () routine is
27912 available to do the 64bit variant of gmtime ()
27913 .ie n .IP """HAS_LOCALTIME_R""" 4
27914 .el .IP \f(CWHAS_LOCALTIME_R\fR 4
27915 .IX Xref "HAS_LOCALTIME_R"
27916 .IX Item "HAS_LOCALTIME_R"
27917 This symbol, if defined, indicates that the \f(CW\*(C`localtime_r\*(C'\fR routine
27918 is available to localtime re\-entrantly.
27919 .ie n .IP """HAS_LOCALTIME64""" 4
27920 .el .IP \f(CWHAS_LOCALTIME64\fR 4
27921 .IX Xref "HAS_LOCALTIME64"
27922 .IX Item "HAS_LOCALTIME64"
27923 This symbol, if defined, indicates that the \f(CW\*(C`localtime64\*(C'\fR () routine is
27924 available to do the 64bit variant of localtime ()
27925 .ie n .IP """HAS_MKTIME""" 4
27926 .el .IP \f(CWHAS_MKTIME\fR 4
27927 .IX Xref "HAS_MKTIME"
27928 .IX Item "HAS_MKTIME"
27929 This symbol, if defined, indicates that the \f(CW\*(C`mktime\*(C'\fR routine is
27930 available.
27931 .ie n .IP """HAS_MKTIME64""" 4
27932 .el .IP \f(CWHAS_MKTIME64\fR 4
27933 .IX Xref "HAS_MKTIME64"
27934 .IX Item "HAS_MKTIME64"
27935 This symbol, if defined, indicates that the \f(CW\*(C`mktime64\*(C'\fR () routine is
27936 available to do the 64bit variant of mktime ()
27937 .ie n .IP """HAS_NANOSLEEP""" 4
27938 .el .IP \f(CWHAS_NANOSLEEP\fR 4
27939 .IX Xref "HAS_NANOSLEEP"
27940 .IX Item "HAS_NANOSLEEP"
27941 This symbol, if defined, indicates that the \f(CW\*(C`nanosleep\*(C'\fR
27942 system call is available to sleep with 1E\-9 sec accuracy.
27943 .ie n .IP """HAS_SETITIMER""" 4
27944 .el .IP \f(CWHAS_SETITIMER\fR 4
27945 .IX Xref "HAS_SETITIMER"
27946 .IX Item "HAS_SETITIMER"
27947 This symbol, if defined, indicates that the \f(CW\*(C`setitimer\*(C'\fR routine is
27948 available to set interval timers.
27949 .ie n .IP """HAS_STRFTIME""" 4
27950 .el .IP \f(CWHAS_STRFTIME\fR 4
27951 .IX Xref "HAS_STRFTIME"
27952 .IX Item "HAS_STRFTIME"
27953 This symbol, if defined, indicates that the \f(CW\*(C`strftime\*(C'\fR routine is
27954 available to do time formatting.
27955 .ie n .IP """HAS_TIME""" 4
27956 .el .IP \f(CWHAS_TIME\fR 4
27957 .IX Xref "HAS_TIME"
27958 .IX Item "HAS_TIME"
27959 This symbol, if defined, indicates that the \f(CWtime()\fR routine exists.
27960 .ie n .IP """HAS_TIMEGM""" 4
27961 .el .IP \f(CWHAS_TIMEGM\fR 4
27962 .IX Xref "HAS_TIMEGM"
27963 .IX Item "HAS_TIMEGM"
27964 This symbol, if defined, indicates that the \f(CW\*(C`timegm\*(C'\fR routine is
27965 available to do the opposite of gmtime ()
27966 .ie n .IP """HAS_TIMES""" 4
27967 .el .IP \f(CWHAS_TIMES\fR 4
27968 .IX Xref "HAS_TIMES"
27969 .IX Item "HAS_TIMES"
27970 This symbol, if defined, indicates that the \f(CWtimes()\fR routine exists.
27971 Note that this became obsolete on some systems (\f(CW\*(C`SUNOS\*(C'\fR), which now
27972 use \f(CWgetrusage()\fR. It may be necessary to include \fIsys/times.h\fR.
27973 .ie n .IP """HAS_TM_TM_GMTOFF""" 4
27974 .el .IP \f(CWHAS_TM_TM_GMTOFF\fR 4
27975 .IX Xref "HAS_TM_TM_GMTOFF"
27976 .IX Item "HAS_TM_TM_GMTOFF"
27977 This symbol, if defined, indicates to the C program that
27978 the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_gmtoff\*(C'\fR field.
27979 .ie n .IP """HAS_TM_TM_ZONE""" 4
27980 .el .IP \f(CWHAS_TM_TM_ZONE\fR 4
27981 .IX Xref "HAS_TM_TM_ZONE"
27982 .IX Item "HAS_TM_TM_ZONE"
27983 This symbol, if defined, indicates to the C program that
27984 the \f(CW\*(C`struct tm\*(C'\fR has a \f(CW\*(C`tm_zone\*(C'\fR field.
27985 .ie n .IP """HAS_TZNAME""" 4
27986 .el .IP \f(CWHAS_TZNAME\fR 4
27987 .IX Xref "HAS_TZNAME"
27988 .IX Item "HAS_TZNAME"
27989 This symbol, if defined, indicates that the \f(CW\*(C`tzname[]\*(C'\fR array is
27990 available to access timezone names.
27991 .ie n .IP """HAS_USLEEP""" 4
27992 .el .IP \f(CWHAS_USLEEP\fR 4
27993 .IX Xref "HAS_USLEEP"
27994 .IX Item "HAS_USLEEP"
27995 This symbol, if defined, indicates that the \f(CW\*(C`usleep\*(C'\fR routine is
27996 available to let the process sleep on a sub\-second accuracy.
27997 .ie n .IP """HAS_USLEEP_PROTO""" 4
27998 .el .IP \f(CWHAS_USLEEP_PROTO\fR 4
27999 .IX Xref "HAS_USLEEP_PROTO"
28000 .IX Item "HAS_USLEEP_PROTO"
28001 This symbol, if defined, indicates that the system provides
28002 a prototype for the \f(CWusleep()\fR function. Otherwise, it is up
28003 to the program to supply one. A good guess is
28004 .Sp
28005 .Vb 1
28006 \& extern int usleep(useconds_t);
28007 .Ve
28008 .ie n .IP """I_TIME""" 4
28009 .el .IP \f(CWI_TIME\fR 4
28010 .IX Xref "I_TIME"
28011 .IX Item "I_TIME"
28012 This symbol is always defined, and indicates to the C program that
28013 it should include \fItime.h\fR.
28014 .RS 4
28015 .Sp
28016 .Vb 3
28017 \& #ifdef I_TIME
28018 \& #include <time.h>
28019 \& #endif
28020 .Ve
28021 .RE
28022 .RS 4
28023 .RE
28024 .ie n .IP """I_UTIME""" 4
28025 .el .IP \f(CWI_UTIME\fR 4
28026 .IX Xref "I_UTIME"
28027 .IX Item "I_UTIME"
28028 This symbol, if defined, indicates to the C program that it should
28029 include \fIutime.h\fR.
28030 .RS 4
28031 .Sp
28032 .Vb 3
28033 \& #ifdef I_UTIME
28034 \& #include <utime.h>
28035 \& #endif
28036 .Ve
28037 .RE
28038 .RS 4
28039 .RE
28040 .ie n .IP """L_R_TZSET""" 4
28041 .el .IP \f(CWL_R_TZSET\fR 4
28042 .IX Xref "L_R_TZSET"
28043 .IX Item "L_R_TZSET"
28044 If \f(CWlocaltime_r()\fR needs tzset, it is defined in this define
28045 .ie n .IP """LOCALTIME_MAX""" 4
28046 .el .IP \f(CWLOCALTIME_MAX\fR 4
28047 .IX Xref "LOCALTIME_MAX"
28048 .IX Item "LOCALTIME_MAX"
28049 This symbol contains the maximum value for the \f(CW\*(C`time_t\*(C'\fR offset that
28050 the system function localtime () accepts, and defaults to 0
28051 .ie n .IP """LOCALTIME_MIN""" 4
28052 .el .IP \f(CWLOCALTIME_MIN\fR 4
28053 .IX Xref "LOCALTIME_MIN"
28054 .IX Item "LOCALTIME_MIN"
28055 This symbol contains the minimum value for the \f(CW\*(C`time_t\*(C'\fR offset that
28056 the system function localtime () accepts, and defaults to 0
28057 .ie n .IP """LOCALTIME_R_NEEDS_TZSET""" 4
28058 .el .IP \f(CWLOCALTIME_R_NEEDS_TZSET\fR 4
28059 .IX Xref "LOCALTIME_R_NEEDS_TZSET"
28060 .IX Item "LOCALTIME_R_NEEDS_TZSET"
28061 Many libc\*(Aqs \f(CW\*(C`localtime_r\*(C'\fR implementations do not call tzset,
28062 making them differ from \f(CWlocaltime()\fR, and making timezone
28063 changes using $\f(CW\*(C`ENV\*(C'\fR{TZ} without explicitly calling tzset
28064 impossible. This symbol makes us call tzset before \f(CW\*(C`localtime_r\*(C'\fR
28065 .ie n .IP """LOCALTIME_R_PROTO""" 4
28066 .el .IP \f(CWLOCALTIME_R_PROTO\fR 4
28067 .IX Xref "LOCALTIME_R_PROTO"
28068 .IX Item "LOCALTIME_R_PROTO"
28069 This symbol encodes the prototype of \f(CW\*(C`localtime_r\*(C'\fR.
28070 It is zero if \f(CW\*(C`d_localtime_r\*(C'\fR is undef, and one of the
28071 \&\f(CW\*(C`REENTRANT_PROTO_T_ABC\*(C'\fR macros of \fIreentr.h\fR if \f(CW\*(C`d_localtime_r\*(C'\fR
28072 is defined.
28073 .ie n .IP """mini_mktime""" 4
28074 .el .IP \f(CWmini_mktime\fR 4
28075 .IX Xref "mini_mktime"
28076 .IX Item "mini_mktime"
28077 normalise \f(CW\*(C`struct\ tm\*(C'\fR values without the \fBlocaltime()\fR semantics (and
28078 overhead) of \fBmktime()\fR.
28079 .RS 4
28080 .Sp
28081 .Vb 2
28082 \& void mini_mktime(struct tm *ptm)
28083 \& void Perl_mini_mktime(struct tm *ptm)
28084 .Ve
28085 .RE
28086 .RS 4
28087 .RE
28088 .ie n .IP """sv_strftime_ints""" 4
28089 .el .IP \f(CWsv_strftime_ints\fR 4
28090 .IX Item "sv_strftime_ints"
28091 .PD 0
28092 .ie n .IP """sv_strftime_tm""" 4
28093 .el .IP \f(CWsv_strftime_tm\fR 4
28094 .IX Item "sv_strftime_tm"
28095 .ie n .IP """my_strftime""" 4
28096 .el .IP \f(CWmy_strftime\fR 4
28097 .IX Xref "my_strftime sv_strftime_ints sv_strftime_tm"
28098 .IX Item "my_strftime"
28099 .PD
28100 These implement libc \fBstrftime()\fR, overcoming various deficiencies it has; you
28101 will come to regret sooner or later using it directly instead of these.
28102 .Sp
28103 On failure, they return NULL, and set \f(CW\*(C`errno\*(C'\fR to \f(CW\*(C`EINVAL\*(C'\fR.
28104 .Sp
28105 \&\f(CW\*(C`sv_strftime_tm\*(C'\fR and \f(CW\*(C`sv_strftime_ints\*(C'\fR are preferred, as they transparently
28106 handle the UTF\-8ness of the current locale, the input \f(CW\*(C`fmt\*(C'\fR, and the returned
28107 result. Only if the 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) will the result be marked as UTF\-8.
28108 .Sp
28109 For these, the caller assumes ownership of the returned SV with a reference
28110 count of 1.
28111 .Sp
28112 \&\f(CW\*(C`my_strftime\*(C'\fR is kept for backwards compatibility. Knowing if its result
28113 should be considered UTF\-8 or not requires significant extra logic.
28114 .Sp
28115 Note that all three functions are always executed in the underlying
28116 \&\f(CW\*(C`LC_TIME\*(C'\fR locale of the program, giving results based on that locale.
28117 .Sp
28118 The stringified \f(CW\*(C`fmt\*(C'\fR parameter in all is the same as the system libc
28119 \&\f(CW\*(C`strftime\*(C'\fR. The available conversion specifications vary by platform. These
28120 days, every specification listed in the ANSI C99 standard should be usable
28121 everywhere. These are \f(CW\*(C`a A b B c d H I j m M p S U w W x X y Y Z %\*(C'\fR.
28122 .Sp
28123 But note that the \fBresults\fR of some of the conversion specifiers are
28124 non\-portable. For example, the specifiers \f(CW\*(C`a A b B c p Z\*(C'\fR change according
28125 to the locale settings of the user, and both how to set locales (the
28126 locale names) and what output to expect are not standardized.
28127 The specifier \f(CW\*(C`c\*(C'\fR changes according to the timezone settings of the
28128 user and the timezone computation rules of the operating system.
28129 The \f(CW\*(C`Z\*(C'\fR specifier is notoriously unportable since the names of
28130 timezones are not standardized. Sticking to the numeric specifiers is the
28131 safest route.
28132 .Sp
28133 At the time of this writing, for example, \f(CW%s\fR is not available on
28134 Windows\-like systems.
28135 .Sp
28136 The functions differ as follows:
28137 .RS 4
28138 .IP \(bu 4
28139 The \f(CW\*(C`fmt\*(C'\fR parameter and the return from \f(CW\*(C`my_strftime\*(C'\fR are \f(CW\*(C`char\ *\*(C'\fR
28140 instead of the \f(CW\*(C`SV\ *\*(C'\fR in the other two functions. This means the
28141 UTF\-8ness of the format and result are unspecified. The result MUST be
28142 arranged to be FREED BY THE CALLER).
28143 .IP \(bu 4
28144 \&\f(CW\*(C`sv_strftime_ints\*(C'\fR and \f(CW\*(C`my_strftime\*(C'\fR take a bunch of integer parameters that
28145 together completely define a given time. They calculate the \f(CW\*(C`struct\ tm\*(C'\fR
28146 to pass to libc \fBstrftime()\fR, and call that function. See below for the meaning
28147 of the parameters.
28148 .Sp
28149 \&\f(CW\*(C`sv_strftime_tm\*(C'\fR takes a pointer to an already filled\-in \f(CW\*(C`struct\ tm\*(C'\fR
28150 parameter, so avoids that calculation.
28151 .IP \(bu 4
28152 \&\f(CW\*(C`my_strftime\*(C'\fR takes two extra parameters that are ignored, being kept only
28153 for historical reasons. These are \f(CW\*(C`wday\*(C'\fR and \f(CW\*(C`yday\*(C'\fR.
28154 .RE
28155 .RS 4
28156 .Sp
28157 The C99 Standard calls for \f(CW\*(C`struct\ tm\*(C'\fR to contain at least these fields:
28158 .Sp
28159 .Vb 9
28160 \& int tm_sec; // seconds after the minute — [0, 60]
28161 \& int tm_min; // minutes after the hour — [0, 59]
28162 \& int tm_hour; // hours since midnight — [0, 23]
28163 \& int tm_mday; // day of the month — [1, 31]
28164 \& int tm_mon; // months since January — [0, 11]
28165 \& int tm_year; // years since 1900
28166 \& int tm_wday; // days since Sunday — [0, 6]
28167 \& int tm_yday; // days since January 1 — [0, 365]
28168 \& int tm_isdst; // Daylight Saving Time flag
28169 .Ve
28170 .Sp
28171 \&\f(CW\*(C`tm_wday\*(C'\fR and \f(CW\*(C`tm_yday\*(C'\fR are output only; the other fields give enough
28172 information to accurately calculate these, and are internally used for that
28173 purpose.
28174 .Sp
28175 The numbers enclosed in the square brackets above give the maximum legal
28176 ranges for values in the corresponding field. Those ranges are restricted for
28177 some inputs. For example, not all months have 31 days, but all hours have 60
28178 minutes. If you set a number that is outside the corresponding range, perl
28179 and the libc functions will automatically normalize it to be inside the range,
28180 adjusting other values as necessary. For example, specifying February 29, is
28181 the same as saying March 1 for non\-leap years; and using a minute value of 60
28182 will instead change that to a 0, and increment the hour, which in turn, if the
28183 hour was 23, will roll it over to 0 it and increment the day, and so on.
28184 .Sp
28185 Each parameter to \f(CW\*(C`sv_strftime_ints\*(C'\fR and \f(CW\*(C`my_strftime\*(C'\fR populates the
28186 similarly\-named field in this structure.
28187 .Sp
28188 A value of 60 is legal for \f(CW\*(C`tm_sec\*(C'\fR, but only for those moments when an
28189 official leap second has been declared. It is undefined behavior to use them
28190 otherwise, and the behavior does vary depending on the implementation.
28191 Some implementations take your word for it that this is a leap second, leaving
28192 it as the 61st second of the given minute; some roll it over to be the 0th
28193 second of the following minute; some treat it as 0. Some non\-conforming
28194 implementations always roll it over to the next minute, regardless of whether
28195 an actual leap second is occurring or not. (And yes, it is a real problem
28196 that different computers have a different conception of what the current time
28197 is; you can search the internet for details.)
28198 .Sp
28199 There is no limit (outside the size of \f(CW\*(C`int\*(C'\fR) for the value of \f(CW\*(C`tm_year\*(C'\fR,
28200 but sufficiently negative values (for earlier than 1900) may have different
28201 results on different systems and locales. Some libc implementations may know
28202 when a given locale adopted the Greorian calendar, and adjust for that.
28203 Others will not. (And some countries didn\*(Aqt adopt the Gregorian calendar
28204 until after 1900.) Probably all implementations assume modern time zones go
28205 back forever, before they were actually invented, starting in the last half of
28206 the 19th century.
28207 .Sp
28208 The treatment of the \f(CW\*(C`isdst\*(C'\fR field has varied over previous Perl versions,
28209 and has been buggy (both by perl and by some libc implementations), but is now
28210 aligned, as best we can, with the POSIX Standard, as follows:
28211 .ie n .IP """is_dist"" is 0" 4
28212 .el .IP "\f(CWis_dist\fR is 0" 4
28213 .IX Item "is_dist is 0"
28214 The function is to assume that daylight savings time is not in effect. This
28215 should now always work properly, as perl uses its own implementation in this
28216 case, avoiding non\-conforming libc ones.
28217 .ie n .IP """is_dist"" is >0" 4
28218 .el .IP "\f(CWis_dist\fR is >0" 4
28219 .IX Item "is_dist is >0"
28220 The function is to assume that daylight savings time is in effect, though some
28221 underlying libc implementations treat this as a hint instead of a mandate.
28222 .ie n .IP """is_dist"" is <0" 4
28223 .el .IP "\f(CWis_dist\fR is <0" 4
28224 .IX Item "is_dist is <0"
28225 The function is to itself try to calculate if daylight savings time is in
28226 effect. More recent libc implementations are better at this than earlier
28227 ones.
28228 .RE
28229 .RS 4
28230 .Sp
28231 Some libc implementations have extra fields in \f(CW\*(C`struct\ tm\*(C'\fR. The two that
28232 perl handles are:
28233 .Sp
28234 .Vb 2
28235 \& int tm_gmtoff; // Seconds East of UTC [%z]
28236 \& const char * tm_zone; // Timezone abbreviation [%Z]
28237 .Ve
28238 .Sp
28239 These are both output only. Using the respective conversion specifications
28240 (enclosed in the square brackets) in the \f(CW\*(C`fmt\*(C'\fR parameter is a portable way to
28241 gain access to these values, working both on systems that have and don\*(Aqt have
28242 these fields.
28243 .Sp
28244 Example, in the \f(CW\*(C`C\*(C'\fR locale:
28245 .Sp
28246 .Vb 1
28247 \& my_strftime( "%A, %B %d, %Y", 0, 0, 0, 12, 11, 95, 0, 0, \-1 );
28248 .Ve
28249 .Sp
28250 returns
28251 .Sp
28252 .Vb 1
28253 \& "Tuesday, December 12, 1995"
28254 .Ve
28255 .Sp
28256 .Vb 10
28257 \& SV * sv_strftime_ints( SV *fmt, int sec, int min,
28258 \& int hour, int mday, int mon,
28259 \& int year, int isdst)
28260 \& SV * Perl_sv_strftime_ints(pTHX_ SV *fmt, int sec, int min,
28261 \& int hour, int mday, int mon,
28262 \& int year, int isdst)
28263 \& SV * sv_strftime_tm ( SV *fmt,
28264 \& const struct tm *mytm)
28265 \& SV * Perl_sv_strftime_tm (pTHX_ SV *fmt,
28266 \& const struct tm *mytm)
28267 \& char * my_strftime ( const char *fmt, int sec,
28268 \& int min, int hour, int mday,
28269 \& int mon, int year, int wday,
28270 \& int yday, int isdst)
28271 \& char * Perl_my_strftime (pTHX_ const char *fmt, int sec,
28272 \& int min, int hour, int mday,
28273 \& int mon, int year, int wday,
28274 \& int yday, int isdst)
28275 .Ve
28276 .RE
28277 .RS 4
28278 .RE
28279 .SH "Typedef names"
28280 .IX Header "Typedef names"
28281 .ie n .IP """DB_Hash_t""" 4
28282 .el .IP \f(CWDB_Hash_t\fR 4
28283 .IX Xref "DB_Hash_t"
28284 .IX Item "DB_Hash_t"
28285 This symbol contains the type of the prefix structure element
28286 in the \fIdb.h\fR header file. In older versions of DB, it was
28287 int, while in newer ones it is \f(CW\*(C`size_t\*(C'\fR.
28288 .ie n .IP """DB_Prefix_t""" 4
28289 .el .IP \f(CWDB_Prefix_t\fR 4
28290 .IX Xref "DB_Prefix_t"
28291 .IX Item "DB_Prefix_t"
28292 This symbol contains the type of the prefix structure element
28293 in the \fIdb.h\fR header file. In older versions of DB, it was
28294 int, while in newer ones it is \f(CW\*(C`u_int32_t\*(C'\fR.
28295 .ie n .IP """Direntry_t""" 4
28296 .el .IP \f(CWDirentry_t\fR 4
28297 .IX Xref "Direntry_t"
28298 .IX Item "Direntry_t"
28299 This symbol is set to \*(Aq\f(CW\*(C`struct direct\*(C'\fR\*(Aq or \*(Aq\f(CW\*(C`struct dirent\*(C'\fR\*(Aq depending on
28300 whether dirent is available or not. You should use this pseudo type to
28301 portably declare your directory entries.
28302 .ie n .IP """Fpos_t""" 4
28303 .el .IP \f(CWFpos_t\fR 4
28304 .IX Xref "Fpos_t"
28305 .IX Item "Fpos_t"
28306 This symbol holds the type used to declare file positions in libc.
28307 It can be \f(CW\*(C`fpos_t\*(C'\fR, long, uint, etc... It may be necessary to include
28308 \&\fIsys/types.h\fR to get any typedef\*(Aqed information.
28309 .ie n .IP """Free_t""" 4
28310 .el .IP \f(CWFree_t\fR 4
28311 .IX Xref "Free_t"
28312 .IX Item "Free_t"
28313 This variable contains the return type of \f(CWfree()\fR. It is usually
28314 void, but occasionally int.
28315 .ie n .IP """Gid_t""" 4
28316 .el .IP \f(CWGid_t\fR 4
28317 .IX Xref "Gid_t"
28318 .IX Item "Gid_t"
28319 This symbol holds the return type of \f(CWgetgid()\fR and the type of
28320 argument to \f(CWsetrgid()\fR and related functions. Typically,
28321 it is the type of group ids in the kernel. It can be int, ushort,
28322 \&\f(CW\*(C`gid_t\*(C'\fR, etc... It may be necessary to include \fIsys/types.h\fR to get
28323 any typedef\*(Aqed information.
28324 .ie n .IP """Gid_t_f""" 4
28325 .el .IP \f(CWGid_t_f\fR 4
28326 .IX Xref "Gid_t_f"
28327 .IX Item "Gid_t_f"
28328 This symbol defines the format string used for printing a \f(CW\*(C`Gid_t\*(C'\fR.
28329 .ie n .IP """Gid_t_sign""" 4
28330 .el .IP \f(CWGid_t_sign\fR 4
28331 .IX Xref "Gid_t_sign"
28332 .IX Item "Gid_t_sign"
28333 This symbol holds the signedness of a \f(CW\*(C`Gid_t\*(C'\fR.
28334 1 for unsigned, \-1 for signed.
28335 .ie n .IP """Gid_t_size""" 4
28336 .el .IP \f(CWGid_t_size\fR 4
28337 .IX Xref "Gid_t_size"
28338 .IX Item "Gid_t_size"
28339 This symbol holds the size of a \f(CW\*(C`Gid_t\*(C'\fR in bytes.
28340 .ie n .IP """Groups_t""" 4
28341 .el .IP \f(CWGroups_t\fR 4
28342 .IX Xref "Groups_t"
28343 .IX Item "Groups_t"
28344 This symbol holds the type used for the second argument to
28345 \&\f(CWgetgroups()\fR and \f(CWsetgroups()\fR. Usually, this is the same as
28346 gidtype (\f(CW\*(C`gid_t\*(C'\fR) , but sometimes it isn\*(Aqt.
28347 It can be int, ushort, \f(CW\*(C`gid_t\*(C'\fR, etc...
28348 It may be necessary to include \fIsys/types.h\fR to get any
28349 typedef\*(Aqed information. This is only required if you have
28350 \&\f(CWgetgroups()\fR or \f(CWsetgroups()\fR..
28351 .ie n .IP """Malloc_t""" 4
28352 .el .IP \f(CWMalloc_t\fR 4
28353 .IX Xref "Malloc_t"
28354 .IX Item "Malloc_t"
28355 This symbol is the type of pointer returned by malloc and realloc.
28356 .ie n .IP """Mmap_t""" 4
28357 .el .IP \f(CWMmap_t\fR 4
28358 .IX Xref "Mmap_t"
28359 .IX Item "Mmap_t"
28360 This symbol holds the return type of the \f(CWmmap()\fR system call
28361 (and simultaneously the type of the first argument).
28362 Usually set to \*(Aqvoid *\*(Aq or \*(Aq\f(CW\*(C`caddr_t\*(C'\fR\*(Aq.
28363 .ie n .IP """Mode_t""" 4
28364 .el .IP \f(CWMode_t\fR 4
28365 .IX Xref "Mode_t"
28366 .IX Item "Mode_t"
28367 This symbol holds the type used to declare file modes
28368 for systems calls. It is usually \f(CW\*(C`mode_t\*(C'\fR, but may be
28369 int or unsigned short. It may be necessary to include \fIsys/types.h\fR
28370 to get any typedef\*(Aqed information.
28371 .ie n .IP """Netdb_hlen_t""" 4
28372 .el .IP \f(CWNetdb_hlen_t\fR 4
28373 .IX Xref "Netdb_hlen_t"
28374 .IX Item "Netdb_hlen_t"
28375 This symbol holds the type used for the 2nd argument
28376 to \f(CWgethostbyaddr()\fR.
28377 .ie n .IP """Netdb_host_t""" 4
28378 .el .IP \f(CWNetdb_host_t\fR 4
28379 .IX Xref "Netdb_host_t"
28380 .IX Item "Netdb_host_t"
28381 This symbol holds the type used for the 1st argument
28382 to \f(CWgethostbyaddr()\fR.
28383 .ie n .IP """Netdb_name_t""" 4
28384 .el .IP \f(CWNetdb_name_t\fR 4
28385 .IX Xref "Netdb_name_t"
28386 .IX Item "Netdb_name_t"
28387 This symbol holds the type used for the argument to
28388 \&\f(CWgethostbyname()\fR.
28389 .ie n .IP """Netdb_net_t""" 4
28390 .el .IP \f(CWNetdb_net_t\fR 4
28391 .IX Xref "Netdb_net_t"
28392 .IX Item "Netdb_net_t"
28393 This symbol holds the type used for the 1st argument to
28394 \&\f(CWgetnetbyaddr()\fR.
28395 .ie n .IP """Off_t""" 4
28396 .el .IP \f(CWOff_t\fR 4
28397 .IX Xref "Off_t"
28398 .IX Item "Off_t"
28399 This symbol holds the type used to declare offsets in the kernel.
28400 It can be int, long, \f(CW\*(C`off_t\*(C'\fR, etc... It may be necessary to include
28401 \&\fIsys/types.h\fR to get any typedef\*(Aqed information.
28402 .ie n .IP """Off_t_size""" 4
28403 .el .IP \f(CWOff_t_size\fR 4
28404 .IX Xref "Off_t_size"
28405 .IX Item "Off_t_size"
28406 This symbol holds the number of bytes used by the \f(CW\*(C`Off_t\*(C'\fR.
28407 .ie n .IP """Pid_t""" 4
28408 .el .IP \f(CWPid_t\fR 4
28409 .IX Xref "Pid_t"
28410 .IX Item "Pid_t"
28411 This symbol holds the type used to declare process ids in the kernel.
28412 It can be int, uint, \f(CW\*(C`pid_t\*(C'\fR, etc... It may be necessary to include
28413 \&\fIsys/types.h\fR to get any typedef\*(Aqed information.
28414 .ie n .IP """Rand_seed_t""" 4
28415 .el .IP \f(CWRand_seed_t\fR 4
28416 .IX Xref "Rand_seed_t"
28417 .IX Item "Rand_seed_t"
28418 This symbol defines the type of the argument of the
28419 random seed function.
28420 .ie n .IP """Select_fd_set_t""" 4
28421 .el .IP \f(CWSelect_fd_set_t\fR 4
28422 .IX Xref "Select_fd_set_t"
28423 .IX Item "Select_fd_set_t"
28424 This symbol holds the type used for the 2nd, 3rd, and 4th
28425 arguments to select. Usually, this is \*(Aq\f(CW\*(C`fd_set\*(C'\fR *\*(Aq, if \f(CW\*(C`HAS_FD_SET\*(C'\fR
28426 is defined, and \*(Aqint *\*(Aq otherwise. This is only useful if you
28427 have \f(CWselect()\fR, of course.
28428 .ie n .IP """Shmat_t""" 4
28429 .el .IP \f(CWShmat_t\fR 4
28430 .IX Xref "Shmat_t"
28431 .IX Item "Shmat_t"
28432 This symbol holds the return type of the \f(CWshmat()\fR system call.
28433 Usually set to \*(Aqvoid *\*(Aq or \*(Aqchar *\*(Aq.
28434 .ie n .IP """Signal_t""" 4
28435 .el .IP \f(CWSignal_t\fR 4
28436 .IX Xref "Signal_t"
28437 .IX Item "Signal_t"
28438 This symbol\*(Aqs value is either "void" or "int", corresponding to the
28439 appropriate return type of a signal handler. Thus, you can declare
28440 a signal handler using "\f(CW\*(C`Signal_t\*(C'\fR (*handler)()", and define the
28441 handler using "\f(CW\*(C`Signal_t\*(C'\fR \f(CWhandler(sig)\fR".
28442 .ie n .IP """Size_t""" 4
28443 .el .IP \f(CWSize_t\fR 4
28444 .IX Xref "Size_t"
28445 .IX Item "Size_t"
28446 This symbol holds the type used to declare length parameters
28447 for string functions. It is usually \f(CW\*(C`size_t\*(C'\fR, but may be
28448 unsigned long, int, etc. It may be necessary to include
28449 \&\fIsys/types.h\fR to get any typedef\*(Aqed information.
28450 .ie n .IP """Size_t_size""" 4
28451 .el .IP \f(CWSize_t_size\fR 4
28452 .IX Xref "Size_t_size"
28453 .IX Item "Size_t_size"
28454 This symbol holds the size of a \f(CW\*(C`Size_t\*(C'\fR in bytes.
28455 .ie n .IP """Sock_size_t""" 4
28456 .el .IP \f(CWSock_size_t\fR 4
28457 .IX Xref "Sock_size_t"
28458 .IX Item "Sock_size_t"
28459 This symbol holds the type used for the size argument of
28460 various socket calls (just the base type, not the pointer\-to).
28461 .ie n .IP """SSize_t""" 4
28462 .el .IP \f(CWSSize_t\fR 4
28463 .IX Xref "SSize_t"
28464 .IX Item "SSize_t"
28465 This symbol holds the type used by functions that return
28466 a count of bytes or an error condition. It must be a signed type.
28467 It is usually \f(CW\*(C`ssize_t\*(C'\fR, but may be long or int, etc.
28468 It may be necessary to include \fIsys/types.h\fR or \fIunistd.h\fR
28469 to get any typedef\*(Aqed information.
28470 We will pick a type such that \f(CWsizeof(SSize_t)\fR == \f(CWsizeof(Size_t)\fR.
28471 .ie n .IP """Time_t""" 4
28472 .el .IP \f(CWTime_t\fR 4
28473 .IX Xref "Time_t"
28474 .IX Item "Time_t"
28475 This symbol holds the type returned by \f(CWtime()\fR. It can be long,
28476 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
28477 included).
28478 .ie n .IP """Uid_t""" 4
28479 .el .IP \f(CWUid_t\fR 4
28480 .IX Xref "Uid_t"
28481 .IX Item "Uid_t"
28482 This symbol holds the type used to declare user ids in the kernel.
28483 It can be int, ushort, \f(CW\*(C`uid_t\*(C'\fR, etc... It may be necessary to include
28484 \&\fIsys/types.h\fR to get any typedef\*(Aqed information.
28485 .ie n .IP """Uid_t_f""" 4
28486 .el .IP \f(CWUid_t_f\fR 4
28487 .IX Xref "Uid_t_f"
28488 .IX Item "Uid_t_f"
28489 This symbol defines the format string used for printing a \f(CW\*(C`Uid_t\*(C'\fR.
28490 .ie n .IP """Uid_t_sign""" 4
28491 .el .IP \f(CWUid_t_sign\fR 4
28492 .IX Xref "Uid_t_sign"
28493 .IX Item "Uid_t_sign"
28494 This symbol holds the signedness of a \f(CW\*(C`Uid_t\*(C'\fR.
28495 1 for unsigned, \-1 for signed.
28496 .ie n .IP """Uid_t_size""" 4
28497 .el .IP \f(CWUid_t_size\fR 4
28498 .IX Xref "Uid_t_size"
28499 .IX Item "Uid_t_size"
28500 This symbol holds the size of a \f(CW\*(C`Uid_t\*(C'\fR in bytes.
28501 .SH "Unicode Support"
28502 .IX Xref "UNI_DISPLAY_BACKSLASH UNI_DISPLAY_BACKSPACE UNI_DISPLAY_ISPRINT UNI_DISPLAY_QQ UNI_DISPLAY_REGEX 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 UTF8_ALLOW_CONTINUATION UTF8_ALLOW_EMPTY UTF8_ALLOW_LONG UTF8_ALLOW_NON_CONTINUATION UTF8_ALLOW_OVERFLOW UTF8_ALLOW_PERL_EXTENDED UTF8_ALLOW_SHORT 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_NON_CONTINUATION UTF8_GOT_NONCHAR 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"
28503 .IX Header "Unicode Support"
28504 "Unicode Support" in perlguts has an introduction to this API.
28505 .PP
28506 See also \f(CW"Character classification"\fR,
28507 \&\f(CW"Character case changing"\fR,
28508 and \f(CW"String Handling"\fR.
28509 Various functions outside this section also work specially with
28510 Unicode. Search for the string "utf8" in this document.
28511 .ie n .IP """BOM_UTF8""" 4
28512 .el .IP \f(CWBOM_UTF8\fR 4
28513 .IX Xref "BOM_UTF8"
28514 .IX Item "BOM_UTF8"
28515 This is a macro that evaluates to a string constant of the UTF\-8 bytes that
28516 define the Unicode BYTE ORDER MARK (U+FEFF) for the platform that perl
28517 is compiled on. This allows code to use a mnemonic for this character that
28518 works on both ASCII and EBCDIC platforms.
28519 \&\f(CW\*(C`sizeof(BOM_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in
28520 bytes.
28521 .ie n .IP """bytes_cmp_utf8""" 4
28522 .el .IP \f(CWbytes_cmp_utf8\fR 4
28523 .IX Xref "bytes_cmp_utf8"
28524 .IX Item "bytes_cmp_utf8"
28525 Compares the sequence of characters (stored as octets) in \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`blen\*(C'\fR with the
28526 sequence of characters (stored as UTF\-8)
28527 in \f(CW\*(C`u\*(C'\fR, \f(CW\*(C`ulen\*(C'\fR. Returns 0 if they are
28528 equal, \-1 or \-2 if the first string is less than the second string, +1 or +2
28529 if the first string is greater than the second string.
28530 .Sp
28531 \&\-1 or +1 is returned if the shorter string was identical to the start of the
28532 longer string. \-2 or +2 is returned if
28533 there was a difference between characters
28534 within the strings.
28535 .RS 4
28536 .Sp
28537 .Vb 4
28538 \& int bytes_cmp_utf8( const U8 *b, STRLEN blen,
28539 \& const U8 *u, STRLEN ulen)
28540 \& int Perl_bytes_cmp_utf8(pTHX_ const U8 *b, STRLEN blen,
28541 \& const U8 *u, STRLEN ulen)
28542 .Ve
28543 .RE
28544 .RS 4
28545 .RE
28546 .ie n .IP """bytes_from_utf8*""" 4
28547 .el .IP \f(CWbytes_from_utf8*\fR 4
28548 .IX Item "bytes_from_utf8*"
28549 Described under \f(CW"utf8_to_bytes_overwrite"\fR
28550 .ie n .IP """bytes_to_utf8""" 4
28551 .el .IP \f(CWbytes_to_utf8\fR 4
28552 .IX Item "bytes_to_utf8"
28553 .PD 0
28554 .ie n .IP """bytes_to_utf8_free_me""" 4
28555 .el .IP \f(CWbytes_to_utf8_free_me\fR 4
28556 .IX Item "bytes_to_utf8_free_me"
28557 .ie n .IP """bytes_to_utf8_temp_pv""" 4
28558 .el .IP \f(CWbytes_to_utf8_temp_pv\fR 4
28559 .IX Xref "bytes_to_utf8 bytes_to_utf8_free_me bytes_to_utf8_temp_pv"
28560 .IX Item "bytes_to_utf8_temp_pv"
28561 .PD
28562 These each convert a string \f(CW\*(C`s\*(C'\fR of length \f(CW*lenp\fR bytes from the native
28563 encoding into UTF\-8 (UTF\-EBCDIC on EBCDIC platforms), returning a pointer to
28564 the UTF\-8 string, and setting \f(CW*lenp\fR to its length in bytes.
28565 .Sp
28566 \&\f(CW\*(C`bytes_to_utf8\*(C'\fR always allocates new memory for the result, making sure it is
28567 NUL\-terminated.
28568 .Sp
28569 \&\f(CW\*(C`bytes_to_utf8_free_me\*(C'\fR simply returns a pointer to the input string if the
28570 string\*(Aqs UTF\-8 representation is the same as its native representation.
28571 Otherwise, it behaves like \f(CW\*(C`bytes_to_utf8\*(C'\fR, returning a pointer to new memory
28572 containing the conversion of the input. In other words, it returns the input
28573 string if converting the string would be a no\-op. Note that when no new string
28574 is allocated, the function can\*(Aqt add a NUL to the original string if one wasn\*(Aqt
28575 already there.
28576 .Sp
28577 In both cases, the caller is responsible for arranging for any new memory to
28578 get freed.
28579 .Sp
28580 \&\f(CW\*(C`bytes_to_utf8_temp_pv\*(C'\fR simply returns a pointer to the input string if the
28581 string\*(Aqs UTF\-8 representation is the same as its native representation, thus
28582 behaving like \f(CW\*(C`bytes_to_utf8_free_me\*(C'\fR in this situation. Otherwise, it
28583 behaves like \f(CW\*(C`bytes_to_utf8\*(C'\fR, returning a pointer to new memory containing the
28584 conversion of the input. The difference is that it also arranges for the new
28585 memory to automatically be freed by calling \f(CW"SAVEFREEPV"\fR on it.
28586 .Sp
28587 \&\f(CW\*(C`bytes_to_utf8_free_me\*(C'\fR takes an extra parameter, \f(CW\*(C`free_me\*(C'\fR to communicate.
28588 to the caller that memory was allocated or not. If that parameter is NULL,
28589 \&\f(CW\*(C`bytes_to_utf8_free_me\*(C'\fR acts identically to \f(CW\*(C`bytes_to_utf8\*(C'\fR, always
28590 allocating new memory.
28591 .Sp
28592 But when it is a non\-NULL pointer, \f(CW\*(C`bytes_to_utf8_free_me\*(C'\fR stores into it
28593 either NULL if no memory was allocated; or a pointer to that new memory. This
28594 allows the following convenient paradigm:
28595 .Sp
28596 .Vb 2
28597 \& void * free_me;
28598 \& U8 converted = bytes_to_utf8_free_me(string, &len, &free_me);
28599 \&
28600 \& ...
28601 \&
28602 \& Safefree(free_me);
28603 .Ve
28604 .Sp
28605 You don\*(Aqt have to know if memory was allocated or not. Just call \f(CW\*(C`Safefree\*(C'\fR
28606 unconditionally. \f(CW\*(C`free_me\*(C'\fR will contain a suitable value to pass to
28607 \&\f(CW\*(C`Safefree\*(C'\fR for it to do the right thing, regardless.
28608 Your design is likely flawed if you find yourself using \f(CW\*(C`free_me\*(C'\fR for anything
28609 other than passing to \f(CW\*(C`Safefree\*(C'\fR.
28610 .Sp
28611 Upon return, the number of variants in the string can be computed by having
28612 saved the value of \f(CW*lenp\fR before the call, and subtracting the after\-call
28613 value of \f(CW*lenp\fR from it.
28614 .Sp
28615 If you want to convert to UTF\-8 from encodings other than the native (Latin1 or
28616 EBCDIC), see "sv_recode_to_utf8"().
28617 .RS 4
28618 .Sp
28619 .Vb 8
28620 \& U8 * bytes_to_utf8 ( const U8 *s, STRLEN *lenp)
28621 \& U8 * Perl_bytes_to_utf8 (pTHX_ const U8 *s, STRLEN *lenp)
28622 \& U8 * bytes_to_utf8_free_me( const U8 *s, STRLEN *lenp,
28623 \& void **free_me)
28624 \& U8 * Perl_bytes_to_utf8_free_me(pTHX_ const U8 *s, STRLEN *lenp,
28625 \& void **free_me)
28626 \& U8 * bytes_to_utf8_temp_pv( const U8 *s, STRLEN *lenp)
28627 \& U8 * Perl_bytes_to_utf8_temp_pv(pTHX_ const U8 *s, STRLEN *lenp)
28628 .Ve
28629 .RE
28630 .RS 4
28631 .RE
28632 .ie n .IP """c9strict_utf8_to_uv*""" 4
28633 .el .IP \f(CWc9strict_utf8_to_uv*\fR 4
28634 .IX Item "c9strict_utf8_to_uv*"
28635 Described under \f(CW"utf8_to_uv"\fR
28636 .ie n .IP """DO_UTF8""" 4
28637 .el .IP \f(CWDO_UTF8\fR 4
28638 .IX Xref "DO_UTF8"
28639 .IX Item "DO_UTF8"
28640 Returns a bool giving whether or not the PV in \f(CW\*(C`sv\*(C'\fR is to be treated as being
28641 encoded in UTF\-8.
28642 .Sp
28643 You should use this \fIafter\fR a call to \f(CWSvPV()\fR or one of its variants, in
28644 case any call to string overloading updates the internal UTF\-8 encoding flag.
28645 .RS 4
28646 .Sp
28647 .Vb 1
28648 \& bool DO_UTF8(SV* sv)
28649 .Ve
28650 .RE
28651 .RS 4
28652 .RE
28653 .ie n .IP """extended_utf8_to_uv*""" 4
28654 .el .IP \f(CWextended_utf8_to_uv*\fR 4
28655 .IX Item "extended_utf8_to_uv*"
28656 Described under \f(CW"utf8_to_uv"\fR
28657 .ie n .IP """foldEQ_utf8""" 4
28658 .el .IP \f(CWfoldEQ_utf8\fR 4
28659 .IX Xref "foldEQ_utf8"
28660 .IX Item "foldEQ_utf8"
28661 Returns true if the leading portions of the strings \f(CW\*(C`s1\*(C'\fR and \f(CW\*(C`s2\*(C'\fR (either or
28662 both of which may be in UTF\-8) are the same case\-insensitively; false
28663 otherwise. How far into the strings to compare is determined by other input
28664 parameters.
28665 .Sp
28666 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;
28667 otherwise it is assumed to be in native 8\-bit encoding. Correspondingly for
28668 \&\f(CW\*(C`u2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR.
28669 .Sp
28670 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
28671 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.
28672 The scan will not be considered to be a match unless the goal is reached, and
28673 scanning won\*(Aqt continue past that goal. Correspondingly for \f(CW\*(C`l2\*(C'\fR with respect
28674 to \f(CW\*(C`s2\*(C'\fR.
28675 .Sp
28676 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
28677 pointer is considered an end pointer to the position 1 byte past the maximum
28678 point in \f(CW\*(C`s1\*(C'\fR beyond which scanning will not continue under any circumstances.
28679 (This routine assumes that UTF\-8 encoded input strings are not malformed;
28680 malformed input can cause it to read past \f(CW\*(C`pe1\*(C'\fR). This means that if both
28681 \&\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
28682 will never be successful because it can never
28683 get as far as its goal (and in fact is asserted against). Correspondingly for
28684 \&\f(CW\*(C`pe2\*(C'\fR with respect to \f(CW\*(C`s2\*(C'\fR.
28685 .Sp
28686 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
28687 \&\f(CW\*(C`l2\*(C'\fR must be non\-zero), and if both do, both have to be
28688 reached for a successful match. Also, if the fold of a character is multiple
28689 characters, all of them must be matched (see tr21 reference below for
28690 \&\*(Aqfolding\*(Aq).
28691 .Sp
28692 Upon a successful match, if \f(CW\*(C`pe1\*(C'\fR is non\-\f(CW\*(C`NULL\*(C'\fR,
28693 it will be set to point to the beginning of the \fInext\fR character of \f(CW\*(C`s1\*(C'\fR
28694 beyond what was matched. Correspondingly for \f(CW\*(C`pe2\*(C'\fR and \f(CW\*(C`s2\*(C'\fR.
28695 .Sp
28696 For case\-insensitiveness, the "casefolding" of Unicode is used
28697 instead of upper/lowercasing both the characters, see
28698 <https://www.unicode.org/reports/tr21/> (Case Mappings).
28699 .RS 4
28700 .Sp
28701 .Vb 2
28702 \& I32 foldEQ_utf8(const char *s1, char **pe1, UV l1, bool u1,
28703 \& const char *s2, char **pe2, UV l2, bool u2)
28704 .Ve
28705 .RE
28706 .RS 4
28707 .RE
28708 .ie n .IP """is_ascii_string*""" 4
28709 .el .IP \f(CWis_ascii_string*\fR 4
28710 .IX Item "is_ascii_string*"
28711 Described under \f(CW"is_utf8_invariant_string"\fR
28712 .ie n .IP """is_c9strict_utf8_string*""" 4
28713 .el .IP \f(CWis_c9strict_utf8_string*\fR 4
28714 .IX Item "is_c9strict_utf8_string*"
28715 .PD 0
28716 .ie n .IP """is_c9strict_utf8_string_loc*""" 4
28717 .el .IP \f(CWis_c9strict_utf8_string_loc*\fR 4
28718 .IX Item "is_c9strict_utf8_string_loc*"
28719 .ie n .IP """is_c9strict_utf8_string_loclen*""" 4
28720 .el .IP \f(CWis_c9strict_utf8_string_loclen*\fR 4
28721 .IX Item "is_c9strict_utf8_string_loclen*"
28722 .PD
28723 Described under \f(CW"is_utf8_string"\fR
28724 .ie n .IP """is_invariant_string*""" 4
28725 .el .IP \f(CWis_invariant_string*\fR 4
28726 .IX Item "is_invariant_string*"
28727 Described under \f(CW"is_utf8_invariant_string"\fR
28728 .ie n .IP """is_strict_utf8_string*""" 4
28729 .el .IP \f(CWis_strict_utf8_string*\fR 4
28730 .IX Item "is_strict_utf8_string*"
28731 .PD 0
28732 .ie n .IP """is_strict_utf8_string_loc*""" 4
28733 .el .IP \f(CWis_strict_utf8_string_loc*\fR 4
28734 .IX Item "is_strict_utf8_string_loc*"
28735 .ie n .IP """is_strict_utf8_string_loclen*""" 4
28736 .el .IP \f(CWis_strict_utf8_string_loclen*\fR 4
28737 .IX Item "is_strict_utf8_string_loclen*"
28738 .PD
28739 Described under \f(CW"is_utf8_string"\fR
28740 .ie n .IP """is_utf8_char_buf*""" 4
28741 .el .IP \f(CWis_utf8_char_buf*\fR 4
28742 .IX Item "is_utf8_char_buf*"
28743 Described under \f(CW"isUTF8_CHAR"\fR
28744 .ie n .IP """is_utf8_fixed_width_buf_flags""" 4
28745 .el .IP \f(CWis_utf8_fixed_width_buf_flags\fR 4
28746 .IX Item "is_utf8_fixed_width_buf_flags"
28747 .PD 0
28748 .ie n .IP """is_utf8_fixed_width_buf_loc_flags""" 4
28749 .el .IP \f(CWis_utf8_fixed_width_buf_loc_flags\fR 4
28750 .IX Item "is_utf8_fixed_width_buf_loc_flags"
28751 .ie n .IP """is_utf8_fixed_width_buf_loclen_flags""" 4
28752 .el .IP \f(CWis_utf8_fixed_width_buf_loclen_flags\fR 4
28753 .IX Xref "is_utf8_fixed_width_buf_flags is_utf8_fixed_width_buf_loc_flags is_utf8_fixed_width_buf_loclen_flags"
28754 .IX Item "is_utf8_fixed_width_buf_loclen_flags"
28755 .PD
28756 These each return TRUE if the fixed\-width buffer starting at \f(CW\*(C`s\*(C'\fR with length
28757 \&\f(CW\*(C`len\*(C'\fR is entirely valid UTF\-8, subject to the restrictions given by \f(CW\*(C`flags\*(C'\fR;
28758 otherwise they return FALSE.
28759 .Sp
28760 If \f(CW\*(C`flags\*(C'\fR is 0, any well\-formed UTF\-8, as extended by Perl, is accepted
28761 without restriction. If the final few bytes of the buffer do not form a
28762 complete code point, this will return TRUE anyway, provided that
28763 \&\f(CW"is_utf8_valid_partial_char_flags"\fR returns TRUE for them.
28764 .Sp
28765 \&\f(CW\*(C`flags\*(C'\fR can be zero or any combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags
28766 accepted by \f(CW"utf8_to_uv"\fR, and with the same meanings.
28767 .Sp
28768 The functions differ from \f(CW"is_utf8_string_flags"\fR only in that the latter
28769 returns FALSE if the final few bytes of the string don\*(Aqt form a complete code
28770 point.
28771 .Sp
28772 \&\f(CW\*(C`is_utf8_fixed_width_buf_loc_flags\*(C'\fR> does all the preceding, but takes an
28773 extra parameter, \f(CW\*(C`ep\*(C'\fR into which it stores the location of the failure, if
28774 \&\f(CW\*(C`ep\*(C'\fR is not NULL. If instead the function returns TRUE, \f(CW*ep\fR will point to
28775 the beginning of any partial character at the end of the buffer; if there is no
28776 partial character \f(CW*ep\fR will contain \f(CW\*(C`s\*(C'\fR+\f(CW\*(C`len\*(C'\fR.
28777 .Sp
28778 \&\f(CW\*(C`is_utf8_fixed_width_buf_loclen_flags\*(C'\fR> does all the preceding, but takes
28779 another extra parameter, \f(CW\*(C`el\*(C'\fR into which it stores the number of complete,
28780 valid characters found, if \f(CW\*(C`el\*(C'\fR is not NULL.
28781 .RS 4
28782 .Sp
28783 .Vb 10
28784 \& bool is_utf8_fixed_width_buf_flags (
28785 \& const U8 * const s,
28786 \& STRLEN len,
28787 \& const U32 flags)
28788 \& bool is_utf8_fixed_width_buf_loc_flags (
28789 \& const U8 * const s,
28790 \& STRLEN len,
28791 \& const U8 **ep,
28792 \& const U32 flags)
28793 \& bool is_utf8_fixed_width_buf_loclen_flags(
28794 \& const U8 * const s,
28795 \& STRLEN len,
28796 \& const U8 **ep,
28797 \& STRLEN *el,
28798 \& const U32 flags)
28799 \& bool Perl_is_utf8_fixed_width_buf_loclen_flags(
28800 \& const U8 * const s,
28801 \& STRLEN len,
28802 \& const U8 **ep,
28803 \& STRLEN *el,
28804 \& const U32 flags)
28805 .Ve
28806 .RE
28807 .RS 4
28808 .RE
28809 .ie n .IP """is_utf8_invariant_string""" 4
28810 .el .IP \f(CWis_utf8_invariant_string\fR 4
28811 .IX Item "is_utf8_invariant_string"
28812 .PD 0
28813 .ie n .IP """is_utf8_invariant_string_loc""" 4
28814 .el .IP \f(CWis_utf8_invariant_string_loc\fR 4
28815 .IX Item "is_utf8_invariant_string_loc"
28816 .ie n .IP """is_ascii_string""" 4
28817 .el .IP \f(CWis_ascii_string\fR 4
28818 .IX Item "is_ascii_string"
28819 .ie n .IP """is_invariant_string""" 4
28820 .el .IP \f(CWis_invariant_string\fR 4
28821 .IX Xref "is_ascii_string is_invariant_string is_utf8_invariant_string is_utf8_invariant_string_loc"
28822 .IX Item "is_invariant_string"
28823 .PD
28824 These each return TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of the string \f(CW\*(C`s\*(C'\fR are the
28825 same regardless of the UTF\-8 encoding of the string (or UTF\-EBCDIC encoding on
28826 EBCDIC machines); otherwise they returns FALSE. That is, they return TRUE if
28827 they are UTF\-8 invariant. On ASCII\-ish machines, all the ASCII characters and
28828 only the ASCII characters fit this definition. On EBCDIC machines, the
28829 ASCII\-range characters are invariant, but so also are the C1 controls.
28830 .Sp
28831 If \f(CW\*(C`len\*(C'\fR is 0, it will be calculated using \f(CWstrlen(s)\fR, (which means if you
28832 use this option, that \f(CW\*(C`s\*(C'\fR can\*(Aqt have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to
28833 have a terminating \f(CW\*(C`NUL\*(C'\fR byte).
28834 .Sp
28835 All forms except \f(CW\*(C`is_utf8_invariant_string_loc\*(C'\fR have identical behavior. The
28836 only difference with it is that it has an extra pointer parameter, \f(CW\*(C`ep\*(C'\fR, into
28837 which, if it isn\*(Aqt NULL, the location of the first UTF\-8 variant character in
28838 the \f(CW\*(C`ep\*(C'\fR pointer will be stored upon failure. If all characters are UTF\-8
28839 invariant, this function does not change the contents of \f(CW*ep\fR.
28840 .Sp
28841 \&\f(CW\*(C`is_invariant_string\*(C'\fR is somewhat misleadingly named.
28842 \&\f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred, as it indicates under what conditions
28843 the string is invariant.
28844 .Sp
28845 \&\f(CW\*(C`is_ascii_string\*(C'\fR is misleadingly\-named. On ASCII\-ish platforms, the name
28846 isn\*(Aqt misleading: the ASCII\-range characters are exactly the UTF\-8 invariants.
28847 But EBCDIC machines have more UTF\-8 invariants than just the ASCII characters,
28848 so the name \f(CW\*(C`is_utf8_invariant_string\*(C'\fR is preferred.
28849 .Sp
28850 See also
28851 \&\f(CW"is_utf8_string"\fR and \f(CW"is_utf8_fixed_width_buf_flags"\fR.
28852 .RS 4
28853 .Sp
28854 .Vb 12
28855 \& bool is_utf8_invariant_string (const U8 * const s,
28856 \& STRLEN len)
28857 \& bool is_utf8_invariant_string_loc(const U8 * const s,
28858 \& STRLEN len,
28859 \& const U8 **ep)
28860 \& bool Perl_is_utf8_invariant_string_loc(const U8 * const s,
28861 \& STRLEN len,
28862 \& const U8 **ep)
28863 \& bool is_ascii_string (const U8 * const s,
28864 \& STRLEN len)
28865 \& bool is_invariant_string (const U8 * const s,
28866 \& STRLEN len)
28867 .Ve
28868 .RE
28869 .RS 4
28870 .RE
28871 .ie n .IP """is_utf8_string""" 4
28872 .el .IP \f(CWis_utf8_string\fR 4
28873 .IX Item "is_utf8_string"
28874 .PD 0
28875 .ie n .IP """is_utf8_string_loc""" 4
28876 .el .IP \f(CWis_utf8_string_loc\fR 4
28877 .IX Item "is_utf8_string_loc"
28878 .ie n .IP """is_utf8_string_loclen""" 4
28879 .el .IP \f(CWis_utf8_string_loclen\fR 4
28880 .IX Item "is_utf8_string_loclen"
28881 .ie n .IP """is_strict_utf8_string""" 4
28882 .el .IP \f(CWis_strict_utf8_string\fR 4
28883 .IX Item "is_strict_utf8_string"
28884 .ie n .IP """is_strict_utf8_string_loc""" 4
28885 .el .IP \f(CWis_strict_utf8_string_loc\fR 4
28886 .IX Item "is_strict_utf8_string_loc"
28887 .ie n .IP """is_strict_utf8_string_loclen""" 4
28888 .el .IP \f(CWis_strict_utf8_string_loclen\fR 4
28889 .IX Item "is_strict_utf8_string_loclen"
28890 .ie n .IP """is_c9strict_utf8_string""" 4
28891 .el .IP \f(CWis_c9strict_utf8_string\fR 4
28892 .IX Item "is_c9strict_utf8_string"
28893 .ie n .IP """is_c9strict_utf8_string_loc""" 4
28894 .el .IP \f(CWis_c9strict_utf8_string_loc\fR 4
28895 .IX Item "is_c9strict_utf8_string_loc"
28896 .ie n .IP """is_c9strict_utf8_string_loclen""" 4
28897 .el .IP \f(CWis_c9strict_utf8_string_loclen\fR 4
28898 .IX Item "is_c9strict_utf8_string_loclen"
28899 .ie n .IP """is_utf8_string_flags""" 4
28900 .el .IP \f(CWis_utf8_string_flags\fR 4
28901 .IX Item "is_utf8_string_flags"
28902 .ie n .IP """is_utf8_string_loc_flags""" 4
28903 .el .IP \f(CWis_utf8_string_loc_flags\fR 4
28904 .IX Item "is_utf8_string_loc_flags"
28905 .ie n .IP """is_utf8_string_loclen_flags""" 4
28906 .el .IP \f(CWis_utf8_string_loclen_flags\fR 4
28907 .IX Xref "is_c9strict_utf8_string is_c9strict_utf8_string_loc is_c9strict_utf8_string_loclen is_strict_utf8_string is_strict_utf8_string_loc is_strict_utf8_string_loclen is_utf8_string is_utf8_string_flags is_utf8_string_loc is_utf8_string_loc_flags is_utf8_string_loclen is_utf8_string_loclen_flags"
28908 .IX Item "is_utf8_string_loclen_flags"
28909 .PD
28910 These each return TRUE if the first \f(CW\*(C`len\*(C'\fR bytes of string \f(CW\*(C`s\*(C'\fR form a valid
28911 UTF\-8 string for varying degrees of strictness, FALSE otherwise. If \f(CW\*(C`len\*(C'\fR is
28912 0, it will be calculated using \f(CWstrlen(s)\fR (which means if you use this
28913 option, that \f(CW\*(C`s\*(C'\fR can\*(Aqt have embedded \f(CW\*(C`NUL\*(C'\fR characters and has to have a
28914 terminating \f(CW\*(C`NUL\*(C'\fR byte). Note that all characters being ASCII constitute \*(Aqa
28915 valid UTF\-8 string\*(Aq.
28916 .Sp
28917 Some of the functions also return information about the string. Those that
28918 have the suffix \f(CW\*(C`_loc\*(C'\fR in their names have an extra parameter, \f(CW\*(C`ep\*(C'\fR. If that
28919 is not NULL, the function stores into it the location of how far it got in
28920 parsing \f(CW\*(C`s\*(C'\fR. If the function is returning TRUE, this will be a pointer to the
28921 byte immediately after the end of \f(CW\*(C`s\*(C'\fR. If FALSE, it will be the location of
28922 the first byte that fails the criteria.
28923 .Sp
28924 The functions that instead have the suffix \f(CW\*(C`_loclen\*(C'\fR have a second extra
28925 parameter, \f(CW\*(C`el\*(C'\fR. They act as the plain \f(CW\*(C`_loc\*(C'\fR functions do with their \f(CW\*(C`ep\*(C'\fR
28926 parameter, but if \f(CW\*(C`el\*(C'\fR is not null, the functions store into it the number of
28927 UTF\-8 encoded characters found at the point where parsing stopped. If the
28928 function is returning TRUE, this will be the full count of the UTF\-8 characters
28929 in \f(CW\*(C`s\*(C'\fR; if FALSE, it will be the count before the first invalid one.
28930 .Sp
28931 \&\f(CW\*(C`is_utf8_string\*(C'\fR (and \f(CW\*(C`is_utf8_string_loc\*(C'\fR and \f(CW\*(C`is_utf8_string_loclen\*(C'\fR)
28932 consider Perl\*(Aqs extended UTF\-8 to be valid. That means that
28933 code points above Unicode, surrogates, and non\-character code points are
28934 all considered valid by this function. Problems may arise in interchange with
28935 non\-Perl applications, or (unlikely) between machines with different word
28936 sizes.
28937 .Sp
28938 \&\f(CW\*(C`is_strict_utf8_string\*(C'\fR (and \f(CW\*(C`is_strict_utf8_string_loc\*(C'\fR and
28939 \&\f(CW\*(C`is_strict_utf8_string_loclen\*(C'\fR) consider only Unicode\-range (0 to 0x10FFFF)
28940 code points to be valid, with the surrogates and non\-character code points
28941 invalid. This level of strictness is what is safe to accept from outside
28942 sources that use Unicode rules.
28943 .Sp
28944 The forms whose names contain \f(CW\*(C`c9strict\*(C'\fR conform to the level of strictness
28945 given in
28946 Unicode Corrigendum #9 <http://www.unicode.org/versions/corrigendum9.html>.
28947 This means Unicode\-range code points including non\-character ones are
28948 considered valid, but not the surrogates. This level of strictness is
28949 considered safe for cooperating components that know how the other components
28950 handle non\-character code points.
28951 .Sp
28952 The forms whose names contain \f(CW\*(C`_flags\*(C'\fR allow you to customize the acceptable
28953 level of strictness. They have an extra parameter, \f(CW\*(C`flags\*(C'\fR to indicate the
28954 types of code points that are acceptable. If \f(CW\*(C`flags\*(C'\fR is 0, they give the
28955 same results as \f(CW"is_utf8_string"\fR (and kin); if \f(CW\*(C`flags\*(C'\fR is
28956 \&\f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, they give the same results as
28957 \&\f(CW"is_strict_utf8_string"\fR (and kin); and if \f(CW\*(C`flags\*(C'\fR is
28958 \&\f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, they give the same results as
28959 \&\f(CW"is_c9strict_utf8_string"\fR (and kin). Otherwise \f(CW\*(C`flags\*(C'\fR may be any
28960 combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR flags understood by
28961 \&\f(CW"utf8_to_uv"\fR, with the same meanings.
28962 .Sp
28963 It\*(Aqs better to use one of the non\-\f(CW\*(C`_flags\*(C'\fR functions if they give you the
28964 desired strictness, as those have a better chance of being inlined by the C
28965 compiler.
28966 .Sp
28967 See also
28968 \&\f(CW"is_utf8_invariant_string"\fR,
28969 \&\f(CW"is_utf8_fixed_width_buf_flags"\fR,
28970 .RS 4
28971 .Sp
28972 .Vb 10
28973 \& bool is_utf8_string (const U8 *s,
28974 \& STRLEN len)
28975 \& bool is_utf8_string_loc (const U8 *s,
28976 \& const STRLEN len,
28977 \& const U8 **ep)
28978 \& bool Perl_is_utf8_string_loc (const U8 *s,
28979 \& const STRLEN len,
28980 \& const U8 **ep)
28981 \& bool is_utf8_string_loclen (const U8 *s,
28982 \& STRLEN len,
28983 \& const U8 **ep,
28984 \& STRLEN *el)
28985 \& bool Perl_is_utf8_string_loclen (const U8 *s,
28986 \& STRLEN len,
28987 \& const U8 **ep,
28988 \& STRLEN *el)
28989 \& bool is_strict_utf8_string (const U8 *s,
28990 \& STRLEN len)
28991 \& bool is_strict_utf8_string_loc (const U8 *s,
28992 \& STRLEN len,
28993 \& const U8 **ep)
28994 \& bool is_strict_utf8_string_loclen (const U8 *s,
28995 \& STRLEN len,
28996 \& const U8 **ep,
28997 \& STRLEN *el)
28998 \& bool Perl_is_strict_utf8_string_loclen (const U8 *s,
28999 \& STRLEN len,
29000 \& const U8 **ep,
29001 \& STRLEN *el)
29002 \& bool is_c9strict_utf8_string (const U8 *s,
29003 \& STRLEN len)
29004 \& bool is_c9strict_utf8_string_loc (const U8 *s,
29005 \& STRLEN len,
29006 \& const U8 **ep)
29007 \& bool is_c9strict_utf8_string_loclen(const U8 *s,
29008 \& STRLEN len,
29009 \& const U8 **ep,
29010 \& STRLEN *el)
29011 \& bool Perl_is_c9strict_utf8_string_loclen(const U8 *s,
29012 \& STRLEN len,
29013 \& const U8 **ep,
29014 \& STRLEN *el)
29015 \& bool is_utf8_string_flags (const U8 *s,
29016 \& STRLEN len,
29017 \& const U32 flags)
29018 \& bool Perl_is_utf8_string_flags (const U8 *s,
29019 \& STRLEN len,
29020 \& const U32 flags)
29021 \& bool is_utf8_string_loc_flags (const U8 *s,
29022 \& STRLEN len,
29023 \& const U8 **ep,
29024 \& const U32 flags)
29025 \& bool is_utf8_string_loclen_flags (const U8 *s,
29026 \& STRLEN len,
29027 \& const U8 **ep,
29028 \& STRLEN *el,
29029 \& const U32 flags)
29030 \& bool Perl_is_utf8_string_loclen_flags (const U8 *s,
29031 \& STRLEN len,
29032 \& const U8 **ep,
29033 \& STRLEN *el,
29034 \& const U32 flags)
29035 .Ve
29036 .RE
29037 .RS 4
29038 .RE
29039 .ie n .IP """is_utf8_valid_partial_char""" 4
29040 .el .IP \f(CWis_utf8_valid_partial_char\fR 4
29041 .IX Item "is_utf8_valid_partial_char"
29042 .PD 0
29043 .ie n .IP """is_utf8_valid_partial_char_flags""" 4
29044 .el .IP \f(CWis_utf8_valid_partial_char_flags\fR 4
29045 .IX Xref "is_utf8_valid_partial_char is_utf8_valid_partial_char_flags"
29046 .IX Item "is_utf8_valid_partial_char_flags"
29047 .PD
29048 These each return FALSE if the sequence of bytes starting at \f(CW\*(C`s\*(C'\fR and looking no
29049 further than \f(CW\*(C`e\ \-\ 1\*(C'\fR is the UTF\-8 encoding for one or more code points.
29050 That is, FALSE is returned if \f(CW\*(C`s\*(C'\fR points to at least one entire UTF\-8 encoded
29051 character.
29052 .Sp
29053 Otherwise, they return TRUE if there exists at least one non\-empty sequence of
29054 bytes that when appended to sequence \f(CW\*(C`s\*(C'\fR, starting at position \f(CW\*(C`e\*(C'\fR causes the
29055 entire sequence to be the well\-formed UTF\-8 of some code point
29056 .Sp
29057 In other words they return TRUE if \f(CW\*(C`s\*(C'\fR points to an incomplete UTF\-8\-encoded
29058 code point; FALSE otherwise.
29059 .Sp
29060 This is useful when a fixed\-length buffer is being tested for being well\-formed
29061 UTF\-8, but the final few bytes in it don\*(Aqt comprise a full character; that is,
29062 it is split somewhere in the middle of the final code point\*(Aqs UTF\-8
29063 representation. (Presumably when the buffer is refreshed with the next chunk
29064 of data, the new first bytes will complete the partial code point.) This
29065 function is used to verify that the final bytes in the current buffer are in
29066 fact the legal beginning of some code point, so that if they aren\*(Aqt, the
29067 failure can be signalled without having to wait for the next read.
29068 .Sp
29069 \&\f(CW\*(C`is_utf8_valid_partial_char\*(C'\fR behaves identically to
29070 \&\f(CW\*(C`is_utf8_valid_partial_char_flags\*(C'\fR when the latter is called with a zero
29071 \&\f(CW\*(C`flags\*(C'\fR parameter. This parameter is used to restrict the classes of code
29072 points that are considered to be valid. When zero, Perl\*(Aqs extended UTF\-8 is
29073 used. Otherwise \f(CW\*(C`flags\*(C'\fR can be any combination of the \f(CW\*(C`UTF8_DISALLOW_\fR\f(CIfoo\fR\f(CW\*(C'\fR
29074 flags accepted by \f(CW"utf8_to_uv"\fR. If there is any sequence of bytes
29075 that can complete the input partial character in such a way that a
29076 non\-prohibited character is formed, the function returns TRUE; otherwise FALSE.
29077 Non\-character code points cannot be determined based on partial character
29078 input, so TRUE is always returned if \f(CW\*(C`s\*(C'\fR looks like it could be the beginning
29079 on one of those. But many of the other possible excluded types can be
29080 determined from just the first one or two bytes.
29081 .RS 4
29082 .Sp
29083 .Vb 8
29084 \& bool is_utf8_valid_partial_char (const U8 * const s0,
29085 \& const U8 * const e)
29086 \& bool is_utf8_valid_partial_char_flags(const U8 * const s0,
29087 \& const U8 * const e,
29088 \& const U32 flags)
29089 \& bool Perl_is_utf8_valid_partial_char_flags(const U8 * const s0,
29090 \& const U8 * const e,
29091 \& const U32 flags)
29092 .Ve
29093 .RE
29094 .RS 4
29095 .RE
29096 .ie n .IP """isUTF8_CHAR""" 4
29097 .el .IP \f(CWisUTF8_CHAR\fR 4
29098 .IX Item "isUTF8_CHAR"
29099 .PD 0
29100 .ie n .IP """isSTRICT_UTF8_CHAR""" 4
29101 .el .IP \f(CWisSTRICT_UTF8_CHAR\fR 4
29102 .IX Item "isSTRICT_UTF8_CHAR"
29103 .ie n .IP """isC9_STRICT_UTF8_CHAR""" 4
29104 .el .IP \f(CWisC9_STRICT_UTF8_CHAR\fR 4
29105 .IX Item "isC9_STRICT_UTF8_CHAR"
29106 .ie n .IP """isUTF8_CHAR_flags""" 4
29107 .el .IP \f(CWisUTF8_CHAR_flags\fR 4
29108 .IX Item "isUTF8_CHAR_flags"
29109 .ie n .IP """is_utf8_char_buf""" 4
29110 .el .IP \f(CWis_utf8_char_buf\fR 4
29111 .IX Xref "is_utf8_char_buf isC9_STRICT_UTF8_CHAR isSTRICT_UTF8_CHAR isUTF8_CHAR isUTF8_CHAR_flags"
29112 .IX Item "is_utf8_char_buf"
29113 .PD
29114 These each evaluate to non\-zero if the first few bytes of the string starting
29115 at \f(CW\*(C`s\*(C'\fR and looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well\-formed UTF\-8 that
29116 represents some code point, for varying degrees of strictness. Otherwise they
29117 evaluate to 0. If non\-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR
29118 comprise the code point\*(Aqs representation. Any bytes remaining before \f(CW\*(C`e\*(C'\fR, but
29119 beyond the ones needed to form the first code point in \f(CW\*(C`s\*(C'\fR, are not examined.
29120 .Sp
29121 These are used to efficiently decide if the next few bytes in \f(CW\*(C`s\*(C'\fR are
29122 legal UTF\-8 for a single character.
29123 .Sp
29124 With \f(CW\*(C`isUTF8_CHAR\*(C'\fR, the code point can be any that will fit in an IV on this
29125 machine, using Perl\*(Aqs extension to official UTF\-8 to represent those higher
29126 than the Unicode maximum of 0x10FFFF. That means that this will consider byte
29127 sequences to be valid that are unrecognized or considered illegal by non\-Perl
29128 applications.
29129 .Sp
29130 With \f(CW"isSTRICT_UTF8_CHAR"\fR, acceptable code points are restricted to those
29131 defined by Unicode to be fully interchangeable across applications.
29132 This means code points above the Unicode range (max legal is 0x10FFFF),
29133 surrogates, and non\-character code points are rejected.
29134 .Sp
29135 With \f(CW"isC9_STRICT_UTF8_CHAR"\fR, acceptable code points are restricted to
29136 those defined by Unicode to be fully interchangeable within an application.
29137 This means code points above the Unicode range and surrogates are rejected, but
29138 non\-character code points are accepted. See Unicode Corrigendum
29139 #9 <http://www.unicode.org/versions/corrigendum9.html>.
29140 .Sp
29141 Use \f(CW"isUTF8_CHAR_flags"\fR to customize what code points are acceptable.
29142 If \f(CW\*(C`flags\*(C'\fR is 0, this gives the same results as \f(CW"isUTF8_CHAR"\fR;
29143 if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR, this gives the same results
29144 as \f(CW"isSTRICT_UTF8_CHAR"\fR;
29145 and if \f(CW\*(C`flags\*(C'\fR is \f(CW\*(C`UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR, this gives
29146 the same results as \f(CW"isC9_STRICT_UTF8_CHAR"\fR.
29147 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
29148 understood by \f(CW"utf8_to_uv"\fR, with the same meanings.
29149 .Sp
29150 The three alternative macros are for the most commonly needed validations; they
29151 are likely to run somewhat faster than this more general one, as they can be
29152 inlined into your code.
29153 .Sp
29154 Use one of the \f(CW"is_utf8_string"\fR forms to check entire strings.
29155 .Sp
29156 Note also that a UTF\-8 "invariant" character (i.e. ASCII on non\-EBCDIC
29157 machines) is a valid UTF\-8 character.
29158 .Sp
29159 \&\f(CW\*(C`is_utf8_char_buf\*(C'\fR is the old name for \f(CW\*(C`isUTF8_CHAR\*(C'\fR. Do not use it in new
29160 code.
29161 .RS 4
29162 .Sp
29163 .Vb 10
29164 \& Size_t isUTF8_CHAR (const U8 * const s0,
29165 \& const U8 * const e)
29166 \& Size_t Perl_isUTF8_CHAR (const U8 * const s0,
29167 \& const U8 * const e)
29168 \& Size_t isSTRICT_UTF8_CHAR (const U8 * const s0,
29169 \& const U8 * const e)
29170 \& Size_t Perl_isSTRICT_UTF8_CHAR (const U8 * const s0,
29171 \& const U8 * const e)
29172 \& Size_t isC9_STRICT_UTF8_CHAR(const U8 * const s0,
29173 \& const U8 * const e)
29174 \& Size_t Perl_isC9_STRICT_UTF8_CHAR(const U8 * const s0,
29175 \& const U8 * const e)
29176 \& Size_t isUTF8_CHAR_flags (const U8 * const s0,
29177 \& const U8 * const e,
29178 \& const U32 flags)
29179 \& Size_t Perl_isUTF8_CHAR_flags (const U8 * const s0,
29180 \& const U8 * const e,
29181 \& const U32 flags)
29182 \& STRLEN is_utf8_char_buf (const U8 *buf,
29183 \& const U8 *buf_end)
29184 \& STRLEN Perl_is_utf8_char_buf (const U8 *buf,
29185 \& const U8 *buf_end)
29186 .Ve
29187 .RE
29188 .RS 4
29189 .RE
29190 .ie n .IP """LATIN1_TO_NATIVE""" 4
29191 .el .IP \f(CWLATIN1_TO_NATIVE\fR 4
29192 .IX Xref "LATIN1_TO_NATIVE"
29193 .IX Item "LATIN1_TO_NATIVE"
29194 Returns the native equivalent of the input Latin\-1 code point (including ASCII
29195 and control characters) given by \f(CW\*(C`ch\*(C'\fR. Thus, \f(CWLATIN1_TO_NATIVE(66)\fR on
29196 EBCDIC platforms returns 194. These each represent the character \f(CW"B"\fR on
29197 their respective platforms. On ASCII platforms no conversion is needed, so
29198 this macro expands to just its input, adding no time nor space requirements to
29199 the implementation.
29200 .Sp
29201 For conversion of code points potentially larger than will fit in a character,
29202 use "UNI_TO_NATIVE".
29203 .RS 4
29204 .Sp
29205 .Vb 1
29206 \& U8 LATIN1_TO_NATIVE(U8 ch)
29207 .Ve
29208 .RE
29209 .RS 4
29210 .RE
29211 .ie n .IP """NATIVE_TO_LATIN1""" 4
29212 .el .IP \f(CWNATIVE_TO_LATIN1\fR 4
29213 .IX Xref "NATIVE_TO_LATIN1"
29214 .IX Item "NATIVE_TO_LATIN1"
29215 Returns the Latin\-1 (including ASCII and control characters) equivalent of the
29216 input native code point given by \f(CW\*(C`ch\*(C'\fR. Thus, \f(CWNATIVE_TO_LATIN1(193)\fR on
29217 EBCDIC platforms returns 65. These each represent the character \f(CW"A"\fR on
29218 their respective platforms. On ASCII platforms no conversion is needed, so
29219 this macro expands to just its input, adding no time nor space requirements to
29220 the implementation.
29221 .Sp
29222 For conversion of code points potentially larger than will fit in a character,
29223 use "NATIVE_TO_UNI".
29224 .RS 4
29225 .Sp
29226 .Vb 1
29227 \& U8 NATIVE_TO_LATIN1(U8 ch)
29228 .Ve
29229 .RE
29230 .RS 4
29231 .RE
29232 .ie n .IP """NATIVE_TO_UNI""" 4
29233 .el .IP \f(CWNATIVE_TO_UNI\fR 4
29234 .IX Xref "NATIVE_TO_UNI"
29235 .IX Item "NATIVE_TO_UNI"
29236 Returns the Unicode equivalent of the input native code point given by \f(CW\*(C`ch\*(C'\fR.
29237 Thus, \f(CWNATIVE_TO_UNI(195)\fR on EBCDIC platforms returns 67. These each
29238 represent the character \f(CW"C"\fR on their respective platforms. On ASCII
29239 platforms no conversion is needed, so this macro expands to just its input,
29240 adding no time nor space requirements to the implementation.
29241 .RS 4
29242 .Sp
29243 .Vb 1
29244 \& UV NATIVE_TO_UNI(UV ch)
29245 .Ve
29246 .RE
29247 .RS 4
29248 .RE
29249 .ie n .IP """pv_uni_display""" 4
29250 .el .IP \f(CWpv_uni_display\fR 4
29251 .IX Xref "pv_uni_display"
29252 .IX Item "pv_uni_display"
29253 Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the UTF\-8 encoded string
29254 \&\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
29255 long (if longer, the rest is truncated and \f(CW"..."\fR will be appended).
29256 .Sp
29257 The \f(CW\*(C`flags\*(C'\fR argument can have any combination of these flag bits
29258 .RS 4
29259 .ie n .IP """UNI_DISPLAY_ISPRINT""" 4
29260 .el .IP \f(CWUNI_DISPLAY_ISPRINT\fR 4
29261 .IX Item "UNI_DISPLAY_ISPRINT"
29262 to display \f(CWisPRINT()\fRable characters as themselves
29263 .ie n .IP """UNI_DISPLAY_BACKSLASH""" 4
29264 .el .IP \f(CWUNI_DISPLAY_BACKSLASH\fR 4
29265 .IX Item "UNI_DISPLAY_BACKSLASH"
29266 to display the \f(CW\*(C`\e\e[nrfta\e\e]\*(C'\fR as the backslashed versions (like \f(CW"\en"\fR)
29267 .Sp
29268 (\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).
29269 .ie n .IP """UNI_DISPLAY_BACKSPACE""" 4
29270 .el .IP \f(CWUNI_DISPLAY_BACKSPACE\fR 4
29271 .IX Item "UNI_DISPLAY_BACKSPACE"
29272 to display \f(CW\*(C`\eb\*(C'\fR for a backspace, but only when \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR also
29273 is set.
29274 .ie n .IP """UNI_DISPLAY_REGEX""" 4
29275 .el .IP \f(CWUNI_DISPLAY_REGEX\fR 4
29276 .IX Item "UNI_DISPLAY_REGEX"
29277 This a shorthand for \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR along with
29278 \&\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR.
29279 .ie n .IP """UNI_DISPLAY_QQ""" 4
29280 .el .IP \f(CWUNI_DISPLAY_QQ\fR 4
29281 .IX Item "UNI_DISPLAY_QQ"
29282 This a shorthand for all three \f(CW\*(C`UNI_DISPLAY_ISPRINT\*(C'\fR,
29283 \&\f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR, and \f(CW\*(C`UNI_DISPLAY_BACKSLASH\*(C'\fR.
29284 .RE
29285 .RS 4
29286 .Sp
29287 The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned.
29288 .Sp
29289 See also "sv_uni_display".
29290 .Sp
29291 .Vb 6
29292 \& char * pv_uni_display( SV *dsv, const U8 *spv,
29293 \& STRLEN len, STRLEN pvlim,
29294 \& UV flags)
29295 \& char * Perl_pv_uni_display(pTHX_ SV *dsv, const U8 *spv,
29296 \& STRLEN len, STRLEN pvlim,
29297 \& UV flags)
29298 .Ve
29299 .RE
29300 .RS 4
29301 .RE
29302 .ie n .IP """REPLACEMENT_CHARACTER_UTF8""" 4
29303 .el .IP \f(CWREPLACEMENT_CHARACTER_UTF8\fR 4
29304 .IX Xref "REPLACEMENT_CHARACTER_UTF8"
29305 .IX Item "REPLACEMENT_CHARACTER_UTF8"
29306 This is a macro that evaluates to a string constant of the UTF\-8 bytes that
29307 define the Unicode REPLACEMENT CHARACTER (U+FFFD) for the platform that perl
29308 is compiled on. This allows code to use a mnemonic for this character that
29309 works on both ASCII and EBCDIC platforms.
29310 \&\f(CW\*(C`sizeof(REPLACEMENT_CHARACTER_UTF8)\ \-\ 1\*(C'\fR can be used to get its length in
29311 bytes.
29312 .ie n .IP """strict_utf8_to_uv*""" 4
29313 .el .IP \f(CWstrict_utf8_to_uv*\fR 4
29314 .IX Item "strict_utf8_to_uv*"
29315 Described under \f(CW"utf8_to_uv"\fR
29316 .ie n .IP """sv_cat_decode""" 4
29317 .el .IP \f(CWsv_cat_decode\fR 4
29318 .IX Xref "sv_cat_decode"
29319 .IX Item "sv_cat_decode"
29320 \&\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
29321 assumed to be octets in that encoding and decoding the input starts
29322 from the position which \f(CW\*(C`(PV\ +\ *offset)\*(C'\fR pointed to. \f(CW\*(C`dsv\*(C'\fR will be
29323 concatenated with the decoded UTF\-8 string from \f(CW\*(C`ssv\*(C'\fR. Decoding will terminate
29324 when the string \f(CW\*(C`tstr\*(C'\fR appears in decoding output or the input ends on
29325 the PV of \f(CW\*(C`ssv\*(C'\fR. The value which \f(CW\*(C`offset\*(C'\fR points will be modified
29326 to the last input position on \f(CW\*(C`ssv\*(C'\fR.
29327 .Sp
29328 Returns TRUE if the terminator was found, else returns FALSE.
29329 .RS 4
29330 .Sp
29331 .Vb 4
29332 \& bool sv_cat_decode( SV *dsv, SV *encoding, SV *ssv,
29333 \& int *offset, char *tstr, int tlen)
29334 \& bool Perl_sv_cat_decode(pTHX_ SV *dsv, SV *encoding, SV *ssv,
29335 \& int *offset, char *tstr, int tlen)
29336 .Ve
29337 .RE
29338 .RS 4
29339 .RE
29340 .ie n .IP """sv_recode_to_utf8""" 4
29341 .el .IP \f(CWsv_recode_to_utf8\fR 4
29342 .IX Xref "sv_recode_to_utf8"
29343 .IX Item "sv_recode_to_utf8"
29344 \&\f(CW\*(C`encoding\*(C'\fR is assumed to be an \f(CW\*(C`Encode\*(C'\fR object, on entry the PV
29345 of \f(CW\*(C`sv\*(C'\fR is assumed to be octets in that encoding, and \f(CW\*(C`sv\*(C'\fR
29346 will be converted into Unicode (and UTF\-8).
29347 .Sp
29348 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
29349 is not a reference, nothing is done to \f(CW\*(C`sv\*(C'\fR. If \f(CW\*(C`encoding\*(C'\fR is not
29350 an \f(CW\*(C`Encode::XS\*(C'\fR Encoding object, bad things will happen.
29351 (See encoding and Encode.)
29352 .Sp
29353 The PV of \f(CW\*(C`sv\*(C'\fR is returned.
29354 .RS 4
29355 .Sp
29356 .Vb 2
29357 \& char * sv_recode_to_utf8( SV *sv, SV *encoding)
29358 \& char * Perl_sv_recode_to_utf8(pTHX_ SV *sv, SV *encoding)
29359 .Ve
29360 .RE
29361 .RS 4
29362 .RE
29363 .ie n .IP """sv_uni_display""" 4
29364 .el .IP \f(CWsv_uni_display\fR 4
29365 .IX Xref "sv_uni_display"
29366 .IX Item "sv_uni_display"
29367 Build to the scalar \f(CW\*(C`dsv\*(C'\fR a displayable version of the scalar \f(CW\*(C`sv\*(C'\fR,
29368 the displayable version being at most \f(CW\*(C`pvlim\*(C'\fR bytes long
29369 (if longer, the rest is truncated and "..." will be appended).
29370 .Sp
29371 The \f(CW\*(C`flags\*(C'\fR argument is as in "pv_uni_display"().
29372 .Sp
29373 The pointer to the PV of the \f(CW\*(C`dsv\*(C'\fR is returned.
29374 .RS 4
29375 .Sp
29376 .Vb 4
29377 \& char * sv_uni_display( SV *dsv, SV *ssv, STRLEN pvlim,
29378 \& UV flags)
29379 \& char * Perl_sv_uni_display(pTHX_ SV *dsv, SV *ssv, STRLEN pvlim,
29380 \& UV flags)
29381 .Ve
29382 .RE
29383 .RS 4
29384 .RE
29385 .ie n .IP """UNI_TO_NATIVE""" 4
29386 .el .IP \f(CWUNI_TO_NATIVE\fR 4
29387 .IX Xref "UNI_TO_NATIVE"
29388 .IX Item "UNI_TO_NATIVE"
29389 Returns the native equivalent of the input Unicode code point given by \f(CW\*(C`ch\*(C'\fR.
29390 Thus, \f(CWUNI_TO_NATIVE(68)\fR on EBCDIC platforms returns 196. These each
29391 represent the character \f(CW"D"\fR on their respective platforms. On ASCII
29392 platforms no conversion is needed, so this macro expands to just its input,
29393 adding no time nor space requirements to the implementation.
29394 .RS 4
29395 .Sp
29396 .Vb 1
29397 \& UV UNI_TO_NATIVE(UV ch)
29398 .Ve
29399 .RE
29400 .RS 4
29401 .RE
29402 .ie n .IP """UNICODE_IS_NONCHAR""" 4
29403 .el .IP \f(CWUNICODE_IS_NONCHAR\fR 4
29404 .IX Xref "UNICODE_IS_NONCHAR"
29405 .IX Item "UNICODE_IS_NONCHAR"
29406 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode
29407 non\-character code points
29408 .RS 4
29409 .Sp
29410 .Vb 1
29411 \& bool UNICODE_IS_NONCHAR(const UV uv)
29412 .Ve
29413 .RE
29414 .RS 4
29415 .RE
29416 .ie n .IP """UNICODE_IS_REPLACEMENT""" 4
29417 .el .IP \f(CWUNICODE_IS_REPLACEMENT\fR 4
29418 .IX Xref "UNICODE_IS_REPLACEMENT"
29419 .IX Item "UNICODE_IS_REPLACEMENT"
29420 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is the Unicode REPLACEMENT
29421 CHARACTER
29422 .RS 4
29423 .Sp
29424 .Vb 1
29425 \& bool UNICODE_IS_REPLACEMENT(const UV uv)
29426 .Ve
29427 .RE
29428 .RS 4
29429 .RE
29430 .ie n .IP """UNICODE_IS_SUPER""" 4
29431 .el .IP \f(CWUNICODE_IS_SUPER\fR 4
29432 .IX Xref "UNICODE_IS_SUPER"
29433 .IX Item "UNICODE_IS_SUPER"
29434 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is above the maximum legal Unicode
29435 code point of U+10FFFF.
29436 .RS 4
29437 .Sp
29438 .Vb 1
29439 \& bool UNICODE_IS_SUPER(const UV uv)
29440 .Ve
29441 .RE
29442 .RS 4
29443 .RE
29444 .ie n .IP """UNICODE_IS_SURROGATE""" 4
29445 .el .IP \f(CWUNICODE_IS_SURROGATE\fR 4
29446 .IX Xref "UNICODE_IS_SURROGATE"
29447 .IX Item "UNICODE_IS_SURROGATE"
29448 Returns a boolean as to whether or not \f(CW\*(C`uv\*(C'\fR is one of the Unicode surrogate
29449 code points
29450 .RS 4
29451 .Sp
29452 .Vb 1
29453 \& bool UNICODE_IS_SURROGATE(const UV uv)
29454 .Ve
29455 .RE
29456 .RS 4
29457 .RE
29458 .ie n .IP """UNICODE_REPLACEMENT""" 4
29459 .el .IP \f(CWUNICODE_REPLACEMENT\fR 4
29460 .IX Xref "UNICODE_REPLACEMENT"
29461 .IX Item "UNICODE_REPLACEMENT"
29462 Evaluates to 0xFFFD, the code point of the Unicode REPLACEMENT CHARACTER
29463 .ie n .IP """UTF8_CHK_SKIP*""" 4
29464 .el .IP \f(CWUTF8_CHK_SKIP*\fR 4
29465 .IX Item "UTF8_CHK_SKIP*"
29466 Described under \f(CW"UTF8SKIP"\fR
29467 .ie n .IP """utf8_distance""" 4
29468 .el .IP \f(CWutf8_distance\fR 4
29469 .IX Xref "utf8_distance"
29470 .IX Item "utf8_distance"
29471 Returns the number of UTF\-8 characters between the UTF\-8 pointers \f(CW\*(C`a\*(C'\fR
29472 and \f(CW\*(C`b\*(C'\fR.
29473 .Sp
29474 WARNING: use only if you *know* that the pointers point inside the
29475 same UTF\-8 buffer.
29476 .RS 4
29477 .Sp
29478 .Vb 2
29479 \& IV utf8_distance( const U8 *a, const U8 *b)
29480 \& IV Perl_utf8_distance(pTHX_ const U8 *a, const U8 *b)
29481 .Ve
29482 .RE
29483 .RS 4
29484 .RE
29485 .ie n .IP """utf8_hop""" 4
29486 .el .IP \f(CWutf8_hop\fR 4
29487 .IX Xref "utf8_hop"
29488 .IX Item "utf8_hop"
29489 Return the UTF\-8 pointer \f(CW\*(C`s\*(C'\fR displaced by \f(CW\*(C`off\*(C'\fR characters, either
29490 forward (if \f(CW\*(C`off\*(C'\fR is positive) or backward (if negative). \f(CW\*(C`s\*(C'\fR does not need
29491 to be pointing to the starting byte of a character. If it isn\*(Aqt, one count of
29492 \&\f(CW\*(C`off\*(C'\fR will be used up to get to the start of the next character for forward
29493 hops, and to the start of the current character for negative ones.
29494 .Sp
29495 WARNING: Prefer "utf8_hop_safe" to this one.
29496 .Sp
29497 Do NOT use this function unless you \fBknow\fR \f(CW\*(C`off\*(C'\fR is within
29498 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
29499 on the first byte of a character or just after the last byte of a character.
29500 .RS 4
29501 .Sp
29502 .Vb 2
29503 \& U8 * utf8_hop(const U8 *s, SSize_t off)
29504 \& U8 * Perl_utf8_hop(const U8 *s, SSize_t off)
29505 .Ve
29506 .RE
29507 .RS 4
29508 .RE
29509 .ie n .IP """utf8_hop_back""" 4
29510 .el .IP \f(CWutf8_hop_back\fR 4
29511 .IX Item "utf8_hop_back"
29512 .PD 0
29513 .ie n .IP """utf8_hop_back_overshoot""" 4
29514 .el .IP \f(CWutf8_hop_back_overshoot\fR 4
29515 .IX Xref "utf8_hop_back utf8_hop_back_overshoot"
29516 .IX Item "utf8_hop_back_overshoot"
29517 .PD
29518 These each take as input a string encoded as UTF\-8 which starts at \f(CW\*(C`start\*(C'\fR,
29519 and a position into it given by \f(CW\*(C`s\*(C'\fR, and return the position within it that is
29520 \&\f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters backwards.
29521 .Sp
29522 If there are fewer than \f(CW\*(C`off\*(C'\fR characters between \f(CW\*(C`start\*(C'\fR and \f(CW\*(C`s\*(C'\fR, the
29523 functions return \f(CW\*(C`start\*(C'\fR.
29524 .Sp
29525 The functions differ in that \f(CW\*(C`utf8_hop_back_overshoot\*(C'\fR can return how many
29526 characters \f(CW\*(C`off\*(C'\fR beyond the edge the request was for. When its parameter,
29527 \&\f(CW&remaining\fR, is not NULL, the function stores into it the count of the
29528 excess; zero if the request was completely fulfilled. The actual number of
29529 characters that were displaced can then be calculated as \f(CW\*(C`off\ \-\ remaining\*(C'\fR.
29530 This function acts identically to plain \f(CW\*(C`utf8_hop_back\*(C'\fR when this parameter is
29531 NULL.
29532 .Sp
29533 \&\f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a character. If it
29534 isn\*(Aqt, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to that start.
29535 .Sp
29536 \&\f(CW\*(C`off\*(C'\fR must be non\-positive, and if zero, no action is taken; \f(CW\*(C`s\*(C'\fR is returned
29537 unchanged. That it otherwise must be negative means that the earlier
29538 description is a lie, to avoid burdening you with this detail too soon. An
29539 \&\f(CW\*(C`off\*(C'\fR of \f(CW\-2\fR means to displace two characters backwards, so the displacement
29540 is actually the absolute value of \f(CW\*(C`off\*(C'\fR. \f(CW\*(C`remaining\*(C'\fR will also be
29541 non\-positive. If there was only one character between \f(CW\*(C`start\*(C'\fR and \f(CW\*(C`s\*(C'\fR, and a
29542 displacement of \f(CW\-2\fR was requested, \f(CW\*(C`remaining\*(C'\fR would be set to \f(CW\-1\fR. The
29543 subtraction formula works, yielding the result that only \f(CW\-1\fR character was
29544 displaced.
29545 .RS 4
29546 .Sp
29547 .Vb 10
29548 \& U8 * utf8_hop_back (const U8 *s, SSize_t off,
29549 \& const U8 * const start)
29550 \& U8 * Perl_utf8_hop_back (const U8 *s, SSize_t off,
29551 \& const U8 * const start)
29552 \& U8 * utf8_hop_back_overshoot(const U8 *s, SSize_t off,
29553 \& const U8 * const start,
29554 \& SSize_t *remaining)
29555 \& U8 * Perl_utf8_hop_back_overshoot(const U8 *s, SSize_t off,
29556 \& const U8 * const start,
29557 \& SSize_t *remaining)
29558 .Ve
29559 .RE
29560 .RS 4
29561 .RE
29562 .ie n .IP """utf8_hop_forward""" 4
29563 .el .IP \f(CWutf8_hop_forward\fR 4
29564 .IX Item "utf8_hop_forward"
29565 .PD 0
29566 .ie n .IP """utf8_hop_forward_overshoot""" 4
29567 .el .IP \f(CWutf8_hop_forward_overshoot\fR 4
29568 .IX Xref "utf8_hop_forward utf8_hop_forward_overshoot"
29569 .IX Item "utf8_hop_forward_overshoot"
29570 .PD
29571 These each take as input a position, \f(CW\*(C`s0\*(C'\fR, into a string encoded as UTF\-8
29572 which ends at the byte before \f(CW\*(C`end\*(C'\fR, and return the position within it that is
29573 \&\f(CW\*(C`s0\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters forwards.
29574 .Sp
29575 If there are fewer than \f(CW\*(C`off\*(C'\fR characters between \f(CW\*(C`s0\*(C'\fR and \f(CW\*(C`end\*(C'\fR, the
29576 functions return \f(CW\*(C`end\*(C'\fR.
29577 .Sp
29578 The functions differ in two ways
29579 .RS 4
29580 .IP \(bu 4
29581 \&\f(CW\*(C`utf8_hop_forward_overshoot\*(C'\fR can return how many characters beyond the edge
29582 the request was for. When its parameter, \f(CW&remaining\fR, is not NULL, the
29583 function stores into it the count of the excess; zero if the request was
29584 completely fulfilled. The actual number of characters that were displaced can
29585 then be calculated as \f(CW\*(C`off\ \-\ remaining\*(C'\fR.
29586 .IP \(bu 4
29587 \&\f(CW\*(C`utf8_hop_forward\*(C'\fR will panic if called with \f(CW\*(C`s0\*(C'\fR already positioned at or
29588 beyond the edge of the string ending at \f(CW\*(C`end\*(C'\fR and the request is to go even
29589 further over the edge. \f(CW\*(C`utf8_hop_forward_overshoot\*(C'\fR presumes the caller will
29590 handle any errors, and just stores \f(CW\*(C`off\*(C'\fR into \f(CW\*(C`remaining\*(C'\fR without doing
29591 anything else.
29592 .RE
29593 .RS 4
29594 .Sp
29595 (The above contains a slight lie. When \f(CW\*(C`remaining\*(C'\fR is NULL, the two functions
29596 act identically.)
29597 .Sp
29598 \&\f(CW\*(C`s0\*(C'\fR does not need to be pointing to the starting byte of a character. If it
29599 isn\*(Aqt, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to that start.
29600 .Sp
29601 \&\f(CW\*(C`off\*(C'\fR must be non\-negative, and if zero, no action is taken; \f(CW\*(C`s0\*(C'\fR is returned
29602 unchanged.
29603 .Sp
29604 .Vb 10
29605 \& U8 * utf8_hop_forward (const U8 *s, SSize_t off,
29606 \& const U8 * const end)
29607 \& U8 * Perl_utf8_hop_forward (const U8 *s, SSize_t off,
29608 \& const U8 * const end)
29609 \& U8 * utf8_hop_forward_overshoot(const U8 *s, SSize_t off,
29610 \& const U8 * const end,
29611 \& SSize_t *remaining)
29612 \& U8 * Perl_utf8_hop_forward_overshoot(const U8 *s, SSize_t off,
29613 \& const U8 * const end,
29614 \& SSize_t *remaining)
29615 .Ve
29616 .RE
29617 .RS 4
29618 .RE
29619 .ie n .IP """utf8_hop_safe""" 4
29620 .el .IP \f(CWutf8_hop_safe\fR 4
29621 .IX Item "utf8_hop_safe"
29622 .PD 0
29623 .ie n .IP """utf8_hop_overshoot""" 4
29624 .el .IP \f(CWutf8_hop_overshoot\fR 4
29625 .IX Xref "utf8_hop_overshoot utf8_hop_safe"
29626 .IX Item "utf8_hop_overshoot"
29627 .PD
29628 These each take as input a string encoded as UTF\-8 which starts at \f(CW\*(C`start\*(C'\fR,
29629 ending at \f(CW\*(C`end\*(C'\fR, and a position into it given by \f(CW\*(C`s\*(C'\fR, and return the
29630 position within it that is \f(CW\*(C`s\*(C'\fR displaced by up to \f(CW\*(C`off\*(C'\fR characters, either
29631 forwards if \f(CW\*(C`off\*(C'\fR is positive, or backwards if \f(CW\*(C`off\*(C'\fR is negative. (Nothing
29632 is done if \f(CW\*(C`off\*(C'\fR is 0.)
29633 .Sp
29634 If there are fewer than \f(CW\*(C`off\*(C'\fR characters between \f(CW\*(C`s\*(C'\fR and the respective edge,
29635 the functions return that edge.
29636 .Sp
29637 The functions differ in that \f(CW\*(C`utf8_hop_overshoot\*(C'\fR can return how many
29638 characters beyond the edge the request was for. When its parameter,
29639 \&\f(CW&remaining\fR, is not NULL, the function stores into it the count of the
29640 excess; zero if the request was completely fulfilled. The actual number of
29641 characters that were displaced can then be calculated as \f(CW\*(C`off\ \-\ remaining\*(C'\fR.
29642 This function acts identically to plain \f(CW\*(C`utf8_hop_safe\*(C'\fR when this parameter is
29643 NULL.
29644 .Sp
29645 \&\f(CW\*(C`s\*(C'\fR does not need to be pointing to the starting byte of a character. If it
29646 isn\*(Aqt, one count of \f(CW\*(C`off\*(C'\fR will be used up to get to that start.
29647 .Sp
29648 To be more precise, the displacement is by the absolute value of \f(CW\*(C`off\*(C'\fR, and
29649 the excess count is the absolute value of \f(CW\*(C`remaining\*(C'\fR.
29650 .RS 4
29651 .Sp
29652 .Vb 10
29653 \& U8 * utf8_hop_safe (const U8 *s, SSize_t off,
29654 \& const U8 * const start,
29655 \& const U8 * const end)
29656 \& U8 * Perl_utf8_hop_safe (const U8 *s, SSize_t off,
29657 \& const U8 * const start,
29658 \& const U8 * const end)
29659 \& U8 * utf8_hop_overshoot(const U8 *s, SSize_t off,
29660 \& const U8 * const start,
29661 \& const U8 * const end,
29662 \& SSize_t *remaining)
29663 \& U8 * Perl_utf8_hop_overshoot(const U8 *s, SSize_t off,
29664 \& const U8 * const start,
29665 \& const U8 * const end,
29666 \& SSize_t *remaining)
29667 .Ve
29668 .RE
29669 .RS 4
29670 .RE
29671 .ie n .IP """UTF8_IS_INVARIANT""" 4
29672 .el .IP \f(CWUTF8_IS_INVARIANT\fR 4
29673 .IX Xref "UTF8_IS_INVARIANT"
29674 .IX Item "UTF8_IS_INVARIANT"
29675 Evaluates to 1 if the byte \f(CW\*(C`c\*(C'\fR represents the same character when encoded in
29676 UTF\-8 as when not; otherwise evaluates to 0. UTF\-8 invariant characters can be
29677 copied as\-is when converting to/from UTF\-8, saving time.
29678 .Sp
29679 In spite of the name, this macro gives the correct result if the input string
29680 from which \f(CW\*(C`c\*(C'\fR comes is not encoded in UTF\-8.
29681 .Sp
29682 See \f(CW"UVCHR_IS_INVARIANT"\fR for checking if a UV is invariant.
29683 .RS 4
29684 .Sp
29685 .Vb 1
29686 \& bool UTF8_IS_INVARIANT(char c)
29687 .Ve
29688 .RE
29689 .RS 4
29690 .RE
29691 .ie n .IP """UTF8_IS_NONCHAR""" 4
29692 .el .IP \f(CWUTF8_IS_NONCHAR\fR 4
29693 .IX Xref "UTF8_IS_NONCHAR"
29694 .IX Item "UTF8_IS_NONCHAR"
29695 Evaluates to non\-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
29696 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well\-formed UTF\-8 that represents one
29697 of the Unicode non\-character code points; otherwise it evaluates to 0. If
29698 non\-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code
29699 point\*(Aqs representation.
29700 .RS 4
29701 .Sp
29702 .Vb 1
29703 \& bool UTF8_IS_NONCHAR(const U8 *s, const U8 *e)
29704 .Ve
29705 .RE
29706 .RS 4
29707 .RE
29708 .ie n .IP """UTF8_IS_REPLACEMENT""" 4
29709 .el .IP \f(CWUTF8_IS_REPLACEMENT\fR 4
29710 .IX Xref "UTF8_IS_REPLACEMENT"
29711 .IX Item "UTF8_IS_REPLACEMENT"
29712 Evaluates to non\-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
29713 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well\-formed UTF\-8 that represents the
29714 Unicode REPLACEMENT CHARACTER; otherwise it evaluates to 0. If non\-zero, the
29715 value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code point\*(Aqs
29716 representation.
29717 .RS 4
29718 .Sp
29719 .Vb 1
29720 \& bool UTF8_IS_REPLACEMENT(const U8 *s, const U8 *e)
29721 .Ve
29722 .RE
29723 .RS 4
29724 .RE
29725 .ie n .IP """UTF8_IS_SUPER""" 4
29726 .el .IP \f(CWUTF8_IS_SUPER\fR 4
29727 .IX Xref "UTF8_IS_SUPER"
29728 .IX Item "UTF8_IS_SUPER"
29729 Recall that Perl recognizes an extension to UTF\-8 that can encode code
29730 points larger than the ones defined by Unicode, which are 0..0x10FFFF.
29731 .Sp
29732 This macro evaluates to non\-zero if the first few bytes of the string starting
29733 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;
29734 otherwise it evaluates to 0. If non\-zero, the return is how many bytes
29735 starting at \f(CW\*(C`s\*(C'\fR comprise the code point\*(Aqs representation.
29736 .Sp
29737 0 is returned if the bytes are not well\-formed extended UTF\-8, or if they
29738 represent a code point that cannot fit in a UV on the current platform. Hence
29739 this macro can give different results when run on a 64\-bit word machine than on
29740 one with a 32\-bit word size.
29741 .Sp
29742 Note that it is illegal in Perl to have code points that are larger than what can
29743 fit in an IV on the current machine; and illegal in Unicode to have any that
29744 this macro matches
29745 .RS 4
29746 .Sp
29747 .Vb 1
29748 \& bool UTF8_IS_SUPER(const U8 *s, const U8 *e)
29749 .Ve
29750 .RE
29751 .RS 4
29752 .RE
29753 .ie n .IP """UTF8_IS_SURROGATE""" 4
29754 .el .IP \f(CWUTF8_IS_SURROGATE\fR 4
29755 .IX Xref "UTF8_IS_SURROGATE"
29756 .IX Item "UTF8_IS_SURROGATE"
29757 Evaluates to non\-zero if the first few bytes of the string starting at \f(CW\*(C`s\*(C'\fR and
29758 looking no further than \f(CW\*(C`e\ \-\ 1\*(C'\fR are well\-formed UTF\-8 that represents one
29759 of the Unicode surrogate code points; otherwise it evaluates to 0. If
29760 non\-zero, the value gives how many bytes starting at \f(CW\*(C`s\*(C'\fR comprise the code
29761 point\*(Aqs representation.
29762 .RS 4
29763 .Sp
29764 .Vb 1
29765 \& bool UTF8_IS_SURROGATE(const U8 *s, const U8 *e)
29766 .Ve
29767 .RE
29768 .RS 4
29769 .RE
29770 .ie n .IP """utf8_length""" 4
29771 .el .IP \f(CWutf8_length\fR 4
29772 .IX Xref "utf8_length"
29773 .IX Item "utf8_length"
29774 Returns the number of characters in the sequence of UTF\-8\-encoded bytes starting
29775 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
29776 same place, it returns 0 with no warning raised.
29777 .Sp
29778 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
29779 and returns the number of valid characters.
29780 .RS 4
29781 .Sp
29782 .Vb 2
29783 \& STRLEN utf8_length( const U8 *s0, const U8 *e)
29784 \& STRLEN Perl_utf8_length(pTHX_ const U8 *s0, const U8 *e)
29785 .Ve
29786 .RE
29787 .RS 4
29788 .RE
29789 .ie n .IP """UTF8_MAXBYTES""" 4
29790 .el .IP \f(CWUTF8_MAXBYTES\fR 4
29791 .IX Xref "UTF8_MAXBYTES"
29792 .IX Item "UTF8_MAXBYTES"
29793 The maximum width of a single UTF\-8 encoded character, in bytes.
29794 .Sp
29795 NOTE: Strictly speaking Perl\*(Aqs UTF\-8 should not be called UTF\-8 since UTF\-8
29796 is an encoding of Unicode, and Unicode\*(Aqs upper limit, 0x10FFFF, can be
29797 expressed with 4 bytes. However, Perl thinks of UTF\-8 as a way to encode
29798 non\-negative integers in a binary format, even those above Unicode.
29799 .ie n .IP """UTF8_MAXBYTES_CASE""" 4
29800 .el .IP \f(CWUTF8_MAXBYTES_CASE\fR 4
29801 .IX Xref "UTF8_MAXBYTES_CASE"
29802 .IX Item "UTF8_MAXBYTES_CASE"
29803 The maximum number of UTF\-8 bytes a single Unicode character can
29804 uppercase/lowercase/titlecase/fold into.
29805 .ie n .IP """UTF8_SAFE_SKIP*""" 4
29806 .el .IP \f(CWUTF8_SAFE_SKIP*\fR 4
29807 .IX Item "UTF8_SAFE_SKIP*"
29808 .PD 0
29809 .ie n .IP """UTF8_SKIP*""" 4
29810 .el .IP \f(CWUTF8_SKIP*\fR 4
29811 .IX Item "UTF8_SKIP*"
29812 .PD
29813 Described under \f(CW"UTF8SKIP"\fR
29814 .ie n .IP """utf8_to_bytes_overwrite""" 4
29815 .el .IP \f(CWutf8_to_bytes_overwrite\fR 4
29816 .IX Item "utf8_to_bytes_overwrite"
29817 .PD 0
29818 .ie n .IP """utf8_to_bytes_new_pv""" 4
29819 .el .IP \f(CWutf8_to_bytes_new_pv\fR 4
29820 .IX Item "utf8_to_bytes_new_pv"
29821 .ie n .IP """utf8_to_bytes_temp_pv""" 4
29822 .el .IP \f(CWutf8_to_bytes_temp_pv\fR 4
29823 .IX Item "utf8_to_bytes_temp_pv"
29824 .ie n .IP """utf8_to_bytes""" 4
29825 .el .IP \f(CWutf8_to_bytes\fR 4
29826 .IX Item "utf8_to_bytes"
29827 .ie n .IP """bytes_from_utf8""" 4
29828 .el .IP \f(CWbytes_from_utf8\fR 4
29829 .IX Xref "bytes_from_utf8 utf8_to_bytes utf8_to_bytes_new_pv utf8_to_bytes_overwrite utf8_to_bytes_temp_pv"
29830 .IX Item "bytes_from_utf8"
29831 .PD
29832 NOTE: \f(CW\*(C`utf8_to_bytes\*(C'\fR is \fBexperimental\fR and may change or be
29833 removed without notice.
29834 .Sp
29835 These each convert a string encoded as UTF\-8 into the equivalent native byte
29836 representation, if possible. The first three forms are preferred; their API is
29837 more convenient to use, and each return \f(CW\*(C`true\*(C'\fR if the result is in bytes;
29838 \&\f(CW\*(C`false\*(C'\fR if the conversion failed.
29839 .RS 4
29840 .IP \(bu 4
29841 \&\f(CW\*(C`utf8_to_bytes_overwrite\*(C'\fR
29842 .IP \(bu 4
29843 \&\f(CW\*(C`utf8_to_bytes_new_pv\*(C'\fR
29844 .IP \(bu 4
29845 \&\f(CW\*(C`utf8_to_bytes_temp_pv\*(C'\fR
29846 .Sp
29847 These differ primarily in the form of the returned string and the allowed
29848 constness of the input string. In each, if the input string was already in
29849 native bytes or was not convertible, the input isn\*(Aqt changed.
29850 .Sp
29851 In each of these three functions, the input \f(CW\*(C`s_ptr\*(C'\fR is a pointer to the string
29852 to be converted and \f(CW*lenp\fR is its length (so that the first byte will be at
29853 \&\f(CW*sptr[0]\fR).
29854 .Sp
29855 \&\f(CW\*(C`utf8_to_bytes_overwrite\*(C'\fR overwrites the input string with the bytes
29856 conversion. Hence, the input string should not be \f(CW\*(C`const\*(C'\fR. (Converting the
29857 multi\-byte UTF\-8 encoding to single bytes never expands the result, so
29858 overwriting is always feasible.)
29859 .Sp
29860 Both \f(CW\*(C`utf8_to_bytes_new_pv\*(C'\fR and \f(CW\*(C`utf8_to_bytes_temp_pv\*(C'\fR allocate new memory
29861 to hold the converted string, never changing the input. Hence the input string
29862 may be \f(CW\*(C`const\*(C'\fR. They differ in that \f(CW\*(C`utf8_to_bytes_temp_pv\*(C'\fR arranges for the
29863 new memory to automatically be freed. With \f(CW\*(C`utf8_to_bytes_new_pv\*(C'\fR, the caller
29864 is responsible for freeing the memory. As explained below, not all successful
29865 calls result in new memory being allocated. Hence this function also returns
29866 to the caller (via an extra parameter, \f(CW*free_me\fR) a pointer to any new
29867 memory, or \f(CW\*(C`NULL\*(C'\fR if none was allocated.
29868 .Sp
29869 The functions return \f(CW\*(C`false\*(C'\fR when the input is not well\-formed UTF\-8 or contains
29870 at least one UTF\-8 sequence that represents a code point that can\*(Aqt be
29871 expressed as a byte. The contents of \f(CW*s_ptr\fR and \f(CW*lenp\fR are not changed.
29872 \&\f(CW\*(C`utf8_to_bytes_new_pv\*(C'\fR sets \f(CW*free_me\fR to \f(CW\*(C`NULL\*(C'\fR.
29873 .Sp
29874 They all return \f(CW\*(C`true\*(C'\fR when either:
29875 .RS 4
29876 .IP "The input turned out to already be in bytes form" 4
29877 .IX Item "The input turned out to already be in bytes form"
29878 The contents of \f(CW*s_ptr\fR and \f(CW*lenp\fR are not changed.
29879 \&\f(CW\*(C`utf8_to_bytes_new_pv\*(C'\fR sets \f(CW*free_me\fR to \f(CW\*(C`NULL\*(C'\fR.
29880 .IP "The input was successfully converted" 4
29881 .IX Item "The input was successfully converted"
29882 .RS 4
29883 .PD 0
29884 .ie n .IP "For ""utf8_to_bytes_overwrite""" 4
29885 .el .IP "For \f(CWutf8_to_bytes_overwrite\fR" 4
29886 .IX Item "For utf8_to_bytes_overwrite"
29887 .PD
29888 The input string \f(CW*s_ptr\fR was overwritten with the native bytes, including a
29889 NUL terminator. \f(CW*lenp\fR has been updated with the new length.
29890 .ie n .IP "For ""utf8_to_bytes_new_pv"" and ""utf8_to_bytes_temp_pv""" 4
29891 .el .IP "For \f(CWutf8_to_bytes_new_pv\fR and \f(CWutf8_to_bytes_temp_pv\fR" 4
29892 .IX Item "For utf8_to_bytes_new_pv and utf8_to_bytes_temp_pv"
29893 The input string was not changed. Instead, new memory has been allocated
29894 containing the translation of the input into native bytes, with a NUL
29895 terminator byte. \f(CW*s_ptr\fR now points to that new memory, and \f(CW*lenp\fR
29896 contains its length.
29897 .Sp
29898 For \f(CW\*(C`utf8_to_bytes_temp_pv\*(C'\fR, the new memory has been arranged to be
29899 automatically freed, via a call to \f(CW"SAVEFREEPV"\fR.
29900 .Sp
29901 For \f(CW\*(C`utf8_to_bytes_new_pv\*(C'\fR, \f(CW*free_me\fR has been set to \f(CW*s_ptr\fR, and it is
29902 the caller\*(Aqs responsibility to free the new memory when done using it.
29903 The following paradigm is convenient to use for this:
29904 .Sp
29905 .Vb 7
29906 \& void * free_me;
29907 \& if (utf8_to_bytes_new_pv(&s, &len, &free_me) {
29908 \& ...
29909 \& }
29910 \& else {
29911 \& ...
29912 \& }
29913 \&
29914 \& ...
29915 \&
29916 \& Safefree(free_me);
29917 .Ve
29918 .Sp
29919 \&\f(CW\*(C`free_me\*(C'\fR can be used as a boolean (non\-NULL meaning \f(CW\*(C`true\*(C'\fR) to indicate that
29920 the input was indeed changed if you need to revisit that later in the code.
29921 Your design is likely flawed if you find yourself using \f(CW\*(C`free_me\*(C'\fR for any
29922 other purpose.
29923 .RE
29924 .RS 4
29925 .RE
29926 .RE
29927 .RS 4
29928 .Sp
29929 Note that in all cases, \f(CW*s_ptr\fR and \f(CW*lenp\fR will have correct and consistent
29930 values, updated as was necessary.
29931 .Sp
29932 Also note that upon successful conversion, the number of variants in the string
29933 can be computed by having saved the value of \f(CW*lenp\fR before the call, and
29934 subtracting the after\-call value of \f(CW*lenp\fR from it. This is also true for
29935 the other two functions described below.
29936 .RE
29937 .IP \(bu 4
29938 \&\f(CW\*(C`utf8_to_bytes\*(C'\fR
29939 .Sp
29940 Plain \f(CW\*(C`utf8_to_bytes\*(C'\fR (which has never lost its experimental status) also
29941 converts a UTF\-8 encoded string to bytes, but there are more glitches that the
29942 caller has to be prepared to handle.
29943 .Sp
29944 The input string is passed with one less indirection level, \f(CW\*(C`s\*(C'\fR.
29945 .RS 4
29946 .IP "If the conversion was a noop" 4
29947 .IX Item "If the conversion was a noop"
29948 The contents of \f(CW\*(C`s\*(C'\fR and \f(CW*lenp\fR are not changed, and the function returns
29949 \&\f(CW\*(C`s\*(C'\fR.
29950 .IP "If the conversion was successful" 4
29951 .IX Item "If the conversion was successful"
29952 The contents of \f(CW\*(C`s\*(C'\fR were changed, and \f(CW*lenp\fR updated to be the correct length.
29953 The function returns \f(CW\*(C`s\*(C'\fR (unchanged).
29954 .IP "If the conversion failed" 4
29955 .IX Item "If the conversion failed"
29956 The contents of \f(CW\*(C`s\*(C'\fR were not changed.
29957 .Sp
29958 The function returns NULL and sets \f(CW*lenp\fR to \-1, cast to \f(CW\*(C`STRLEN\*(C'\fR.
29959 This means that you will have to use a temporary containing the string length
29960 to pass to the function if you will need the value afterwards.
29961 .RE
29962 .RS 4
29963 .RE
29964 .IP \(bu 4
29965 \&\f(CW\*(C`bytes_from_utf8\*(C'\fR
29966 .Sp
29967 \&\f(CW\*(C`bytes_from_utf8\*(C'\fR also converts a potentially UTF\-8 encoded string \f(CW\*(C`s\*(C'\fR to
29968 bytes. It preserves \f(CW\*(C`s\*(C'\fR, allocating new memory for the converted string.
29969 .Sp
29970 In contrast to the other functions, the input string to this one need not
29971 be UTF\-8. If not, the caller has set \f(CW*is_utf8p\fR to be \f(CW\*(C`false\*(C'\fR, and the
29972 function does nothing, returning the original \f(CW\*(C`s\*(C'\fR.
29973 .Sp
29974 Also do nothing if there are code points in the string not expressible in
29975 native byte encoding, returning the original \f(CW\*(C`s\*(C'\fR.
29976 .Sp
29977 Otherwise, \f(CW*is_utf8p\fR is set to 0, and the return value is a pointer to a
29978 newly created string containing the native byte equivalent of \f(CW\*(C`s\*(C'\fR, and whose
29979 length is returned in \f(CW*lenp\fR, updated. The new string is \f(CW\*(C`NUL\*(C'\fR\-terminated.
29980 The caller is responsible for arranging for the memory used by this string to
29981 get freed.
29982 .Sp
29983 The major problem with this function is that memory is allocated and filled
29984 even when the input string was already in bytes form.
29985 .RE
29986 .RS 4
29987 .Sp
29988 New code should use the first three functions listed above.
29989 .Sp
29990 .Vb 10
29991 \& bool utf8_to_bytes_overwrite( U8 **s_ptr,
29992 \& STRLEN *lenp)
29993 \& bool Perl_utf8_to_bytes_overwrite(pTHX_ U8 **s_ptr,
29994 \& STRLEN *lenp)
29995 \& bool utf8_to_bytes_new_pv ( U8 const **s_ptr,
29996 \& STRLEN *lenp,
29997 \& void **free_me)
29998 \& bool Perl_utf8_to_bytes_new_pv (pTHX_ U8 const **s_ptr,
29999 \& STRLEN *lenp,
30000 \& void **free_me)
30001 \& bool utf8_to_bytes_temp_pv ( U8 const **s_ptr,
30002 \& STRLEN *lenp)
30003 \& bool Perl_utf8_to_bytes_temp_pv (pTHX_ U8 const **s_ptr,
30004 \& STRLEN *lenp)
30005 \& U8 * utf8_to_bytes ( U8 *s, STRLEN *lenp)
30006 \& U8 * Perl_utf8_to_bytes (pTHX_ U8 *s, STRLEN *lenp)
30007 \& U8 * bytes_from_utf8 ( const U8 *s,
30008 \& STRLEN *lenp,
30009 \& bool *is_utf8p)
30010 \& U8 * Perl_bytes_from_utf8 (pTHX_ const U8 *s,
30011 \& STRLEN *lenp,
30012 \& bool *is_utf8p)
30013 .Ve
30014 .RE
30015 .RS 4
30016 .RE
30017 .ie n .IP """utf8_to_uv""" 4
30018 .el .IP \f(CWutf8_to_uv\fR 4
30019 .IX Item "utf8_to_uv"
30020 .PD 0
30021 .ie n .IP """extended_utf8_to_uv""" 4
30022 .el .IP \f(CWextended_utf8_to_uv\fR 4
30023 .IX Item "extended_utf8_to_uv"
30024 .ie n .IP """strict_utf8_to_uv""" 4
30025 .el .IP \f(CWstrict_utf8_to_uv\fR 4
30026 .IX Item "strict_utf8_to_uv"
30027 .ie n .IP """c9strict_utf8_to_uv""" 4
30028 .el .IP \f(CWc9strict_utf8_to_uv\fR 4
30029 .IX Item "c9strict_utf8_to_uv"
30030 .ie n .IP """utf8_to_uv_or_die""" 4
30031 .el .IP \f(CWutf8_to_uv_or_die\fR 4
30032 .IX Item "utf8_to_uv_or_die"
30033 .ie n .IP """utf8_to_uvchr_buf""" 4
30034 .el .IP \f(CWutf8_to_uvchr_buf\fR 4
30035 .IX Item "utf8_to_uvchr_buf"
30036 .ie n .IP """utf8_to_uvchr""" 4
30037 .el .IP \f(CWutf8_to_uvchr\fR 4
30038 .IX Xref "c9strict_utf8_to_uv extended_utf8_to_uv strict_utf8_to_uv utf8_to_uv utf8_to_uv_or_die utf8_to_uvchr utf8_to_uvchr_buf"
30039 .IX Item "utf8_to_uvchr"
30040 .PD
30041 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`utf8_to_uvchr\*(C'\fR
30042 from a future release of Perl. Do not use it for
30043 new code; remove it from existing code.
30044 .Sp
30045 These functions each translate from UTF\-8 to UTF\-32 (or UTF\-64 on 64 bit
30046 platforms). In other words, to a code point ordinal value. (On EBCDIC
30047 platforms, the initial encoding is UTF\-EBCDIC, and the output is a native code
30048 point).
30049 .Sp
30050 For example, the string "A" would be converted to the number 65 on an ASCII
30051 platform, and to 193 on an EBCDIC one. Converting the string "ABC" would yield
30052 the same results, as the functions stop after the first character converted.
30053 Converting the string "\eN{LATIN CAPITAL LETTER A WITH MACRON} plus anything
30054 more in the string" would yield the number 0x100 on both types of platforms,
30055 since the first character is U+0100.
30056 .Sp
30057 The functions whose names contain \f(CW\*(C`to_uvchr\*(C'\fR are older than the functions
30058 whose names don\*(Aqt have \f(CW\*(C`chr\*(C'\fR in them. The API in the older functions is
30059 harder to use correctly, and so they are kept only for backwards compatibility,
30060 and may eventually become deprecated. If you are writing a module and use
30061 Devel::PPPort, your code can use the new functions back to at least Perl
30062 v5.7.1.
30063 .Sp
30064 All the functions accept, without complaint, well\-formed UTF\-8 for any
30065 non\-problematic Unicode code point 0 .. 0x10FFFF. There are two types of
30066 Unicode problematic code points: surrogate characters and non\-character code
30067 points. (See perlunicode.) Some of the functions reject one or both of
30068 these. Private use characters and those code points yet to be assigned to a
30069 particular character are never considered problematic. Additionally, most of
30070 the functions accept non\-Unicode code points, those starting at 0x110000.
30071 .Sp
30072 There are two sets of these functions:
30073 .RS 4
30074 .ie n .IP """utf8_to_uv"" forms" 4
30075 .el .IP "\f(CWutf8_to_uv\fR forms" 4
30076 .IX Item "utf8_to_uv forms"
30077 Almost all code should use only \f(CW\*(C`utf8_to_uv\*(C'\fR, \f(CW\*(C`extended_utf8_to_uv\*(C'\fR,
30078 \&\f(CW\*(C`strict_utf8_to_uv\*(C'\fR, \f(CW\*(C`c9strict_utf8_to_uv\*(C'\fR, or \f(CW\*(C`utf8_to_uv_or_die\*(C'\fR. The
30079 other functions are either the problematic old form, or are for specialized
30080 uses.
30081 .Sp
30082 \&\f(CW\*(C`utf8_to_uv_or_die\*(C'\fR has a simpler interface than the other four, for use when
30083 any errors encountered should be fatal. It throws an exception with any errors
30084 found, otherwise it returns the code point the input sequence represents.
30085 .Sp
30086 The other four functions each return \f(CW\*(C`true\*(C'\fR if the sequence of bytes starting
30087 at \f(CW\*(C`s\*(C'\fR form a complete, legal UTF\-8 (or UTF\-EBCDIC) sequence for a code point;
30088 or false otherwise. They take an extra parameter, the address of an IV,
30089 \&\f(CW&cp\fR. \f(CW*cp\fR will be set to the native code point value the sequence
30090 represents, and \f(CW*advance\fR will be set to its length, in bytes.
30091 .Sp
30092 If the functions returns \f(CW\*(C`false\*(C'\fR, \f(CW*cp\fR is set to the Unicode REPLACEMENT
30093 CHARACTER, and \f(CW*advance\fR to the next position along \f(CW\*(C`s\*(C'\fR, where the next
30094 possible UTF\-8 character could begin. Failing to use this position as the next
30095 starting point during parsing of strings has led to successful attacks by
30096 crafted inputs.
30097 .Sp
30098 The functions only examine as many bytes along \f(CW\*(C`s\*(C'\fR as are needed to form a
30099 complete UTF\-8 representation of a single code point; they never examine the
30100 byte at \f(CW\*(C`e\*(C'\fR, or beyond. They return false (or die in the case of
30101 \&\f(CW\*(C`utf8_to_uv_or_die\*(C'\fR) if the code point requires more than \f(CW\*(C`e\ \-\ s\*(C'\fR bytes to
30102 represent.
30103 .Sp
30104 The functions differ only in what flavor of UTF\-8 they accept. All reject
30105 syntactically invalid UTF\-8.
30106 .RS 4
30107 .IP \(bu 4
30108 \&\f(CW\*(C`strict_utf8_to_uv\*(C'\fR
30109 .Sp
30110 additionally rejects any UTF\-8 that translates into a code point that isn\*(Aqt
30111 specified by Unicode to be freely exchangeable, namely the surrogate characters
30112 and non\-character code points (besides non\-Unicode code points, any above
30113 0x10FFFF). It does not raise a warning when rejecting these.
30114 .IP \(bu 4
30115 \&\f(CW\*(C`c9strict_utf8_to_uv\*(C'\fR
30116 .Sp
30117 instead uses the exchangeable definition given by Unicode\*(Aqs Corregendum #9,
30118 which accepts non\-character code points while still rejecting surrogates. It
30119 does not raise a warning when rejecting these.
30120 .IP \(bu 4
30121 \&\f(CW\*(C`utf8_to_uv\*(C'\fR
30122 .IP \(bu 4
30123 \&\f(CW\*(C`utf8_to_uv_or die\*(C'\fR
30124 .Sp
30125 accept all syntactically valid UTF\-8, as extended by Perl to allow 64\-bit code
30126 points to be encoded.
30127 .Sp
30128 \&\f(CW\*(C`extended_utf8_to_uv\*(C'\fR is merely a synonym for \f(CW\*(C`utf8_to_uv\*(C'\fR. Use this form
30129 to draw attention to the fact that it accepts any code point. But since
30130 Perl programs traditionally do this by default, plain \f(CW\*(C`utf8_to_uv\*(C'\fR is the form
30131 most often used.
30132 .RE
30133 .RS 4
30134 .Sp
30135 Whenever syntactically invalid input is rejected, an explanatory warning
30136 message is raised, unless \f(CW\*(C`utf8\*(C'\fR warnings (or the appropriate subcategory) are
30137 turned off. A given input sequence may contain multiple malformations, giving
30138 rise to multiple warnings, as the functions attempt to find and report on all
30139 malformations in a sequence. All the possible malformations are listed in
30140 \&\f(CW"utf8_to_uv_msgs"\fR, with some examples of multiple ones for the same
30141 sequence. You can use that function or \f(CW"utf8_to_uv_flags"\fR to exert more
30142 control over the input that is considered acceptable, and the warnings that are
30143 raised.
30144 .Sp
30145 Often, \f(CW\*(C`s\*(C'\fR is an arbitrarily long string containing the UTF\-8 representations
30146 of many code points in a row, and these functions are called in the course of
30147 parsing \f(CW\*(C`s\*(C'\fR to find all those code points.
30148 .Sp
30149 If your code doesn\*(Aqt know how to deal with illegal input, as would be typical
30150 of a low level routine, the loop could look like:
30151 .Sp
30152 .Vb 7
30153 \& while (s < e) {
30154 \& Size_t advance;
30155 \& UV cp;
30156 \& (void) utf8_to_uv(s, e, &cp, &advance);
30157 \& <handle \*(Aqcp\*(Aq>
30158 \& s += advance;
30159 \& }
30160 .Ve
30161 .Sp
30162 A REPLACEMENT CHARACTER will be inserted everywhere that malformed input
30163 occurs. Obviously, we aren\*(Aqt expecting such outcomes, but your code will be
30164 protected from attacks and many harmful effects that could otherwise occur.
30165 .Sp
30166 If the situation is such that it would be a bug for the input to be invalid, a
30167 somewhat simpler loop suffices:
30168 .Sp
30169 .Vb 6
30170 \& while (s < e) {
30171 \& Size_t advance;
30172 \& UV cp = utf8_to_uv_or_die(s, e, &advance);
30173 \& <handle \*(Aqcp\*(Aq>
30174 \& s += advance;
30175 \& }
30176 .Ve
30177 .Sp
30178 This will throw an exception on invalid input, so your code doesn\*(Aqt have to
30179 concern itself with that possibility.
30180 .Sp
30181 If you do have a plan for handling malformed input, you could instead write:
30182 .Sp
30183 .Vb 3
30184 \& while (s < e) {
30185 \& Size_t advance;
30186 \& UV cp;
30187 \&
30188 \& if (UNLIKELY(! utf8_to_uv(s, e, &cp, &advance)) {
30189 \& <bail out or convert to handleable>
30190 \& }
30191 \&
30192 \& <handle \*(Aqcp\*(Aq>
30193 \&
30194 \& s += advance;
30195 \& }
30196 .Ve
30197 .Sp
30198 You may pass NULL to these functions instead of a pointer to your \f(CW\*(C`advance\*(C'\fR
30199 variable. But the only legitimate case to do this is if you are only examining
30200 the first character in \f(CW\*(C`s\*(C'\fR, and have no plans to ever look further. You could
30201 also advance by using \f(CW\*(C`UTF8SKIP\*(C'\fR, but this gives the correct result if and
30202 only if the input is well\-formed; and this practice has led to successful
30203 attacks against such code; and it is extra work always, as the functions have
30204 already done the equivalent work and return the correct value in \f(CW\*(C`advance\*(C'\fR,
30205 regardless of whether the input is well\-formed or not.
30206 .Sp
30207 Except with \f(CW\*(C`utf8_to_uv_or_die\*(C'\fR, you must always pass a non\-NULL pointer into
30208 which to store the (first) code point \f(CW\*(C`s\*(C'\fR represents. If you don\*(Aqt care about
30209 this value, you should be using one of the \f(CW"isUTF8_CHAR"\fR functions
30210 instead.
30211 .RE
30212 .ie n .IP """utf8_to_uvchr"" forms" 4
30213 .el .IP "\f(CWutf8_to_uvchr\fR forms" 4
30214 .IX Item "utf8_to_uvchr forms"
30215 These are the old form equivalents of \f(CW\*(C`utf8_to_uv\*(C'\fR (and its synonym,
30216 \&\f(CW\*(C`extended_utf8_to_uv\*(C'\fR). They are \f(CW\*(C`utf8_to_uvchr\*(C'\fR and \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR.
30217 There is no old form equivalent of either \f(CW\*(C`strict_utf8_to_uv\*(C'\fR nor
30218 \&\f(CW\*(C`c9strict_utf8_to_uv\*(C'\fR.
30219 .Sp
30220 \&\f(CW\*(C`utf8_to_uvchr\*(C'\fR is DEPRECATED. Do NOT use it; it is a security hole ready to
30221 bring destruction onto you and yours.
30222 .Sp
30223 \&\f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR is discouraged and may eventually become deprecated. It
30224 checks if the sequence of bytes starting at \f(CW\*(C`s\*(C'\fR form a complete, legal UTF\-8
30225 (or UTF\-EBCDIC) sequence for a code point. If so, it returns the code point
30226 value the sequence represents, and \f(CW*retlen\fR will be set to its length, in
30227 bytes. Thus, the next possible character in \f(CW\*(C`s\*(C'\fR begins at \f(CW\*(C`s\ +\ *retlen\*(C'\fR.
30228 .Sp
30229 The function only examines as many bytes along \f(CW\*(C`s\*(C'\fR as are needed to form a
30230 complete UTF\-8 representation of a single code point, but it never examines
30231 the byte at \f(CW\*(C`e\*(C'\fR, or beyond.
30232 .Sp
30233 If the sequence examined starting at \f(CW\*(C`s\*(C'\fR is not legal Perl extended UTF\-8, the
30234 translation fails, and the resultant behavior unfortunately depends on if the
30235 warnings category "utf8" is enabled or not.
30236 .RS 4
30237 .ie n .IP "If \*(Aqutf8\*(Aq warnings are disabled" 4
30238 .el .IP "If \f(CW\*(Aqutf8\*(Aq\fR warnings are disabled" 4
30239 .IX Item "If 'utf8' warnings are disabled"
30240 The Unicode REPLACEMENT CHARACTER is silently returned, and \f(CW*retlen\fR is set
30241 (if \f(CW\*(C`retlen\*(C'\fR isn\*(Aqt \f(CW\*(C`NULL\*(C'\fR) so that (\f(CW\*(C`s\*(C'\fR\ +\ \f(CW*retlen\fR) is the next
30242 possible position in \f(CW\*(C`s\*(C'\fR that could begin a non\-malformed character.
30243 .Sp
30244 But note that it is ambiguous whether a REPLACEMENT CHARACTER was actually in
30245 the input, or if this function synthetically generated one. In the unlikely
30246 event that you care, you\*(Aqd have to examine the input to disambiguate.
30247 .ie n .IP "If \*(Aqutf8\*(Aq warnings are enabled" 4
30248 .el .IP "If \f(CW\*(Aqutf8\*(Aq\fR warnings are enabled" 4
30249 .IX Item "If 'utf8' warnings are enabled"
30250 A warning will be displayed, and 0 is returned and \f(CW*retlen\fR is set (if
30251 \&\f(CW\*(C`retlen\*(C'\fR isn\*(Aqt \f(CW\*(C`NULL\*(C'\fR) to \-1.
30252 .Sp
30253 But note that 0 may also be returned if *s is a legal NUL character. This
30254 means that you have to disambiguate a 0 return. You can do this by checking
30255 that the first byte of \f(CW\*(C`s\*(C'\fR is indeed a NUL; or by making sure to always pass a
30256 non\-NULL \f(CW\*(C`retlen\*(C'\fR pointer, and by examining it.
30257 .Sp
30258 Also note that should you wish to proceed with parsing \f(CW\*(C`s\*(C'\fR, you have no easy
30259 way of knowing where to start looking in it for the next possible character.
30260 It is important to look in the right place to prevent attacks on your code.
30261 It would be better to have instead called an equivalent function that provides
30262 this information; any of the \f(CW\*(C`utf8_to_uv\*(C'\fR series, or \f(CW"utf8n_to_uvchr"\fR.
30263 .RE
30264 .RS 4
30265 .Sp
30266 Because of these quirks, \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR is very difficult to use
30267 correctly and handle all cases. Generally, you need to bail out at the first
30268 failure it finds.
30269 .Sp
30270 The deprecated \f(CW\*(C`utf8_to_uvchr\*(C'\fR behaves the same way as \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR for
30271 well\-formed input, and for the malformations it is capable of finding, but
30272 doesn\*(Aqt find all of them, and it can read beyond the end of the input buffer,
30273 which is why it is deprecated.
30274 .RE
30275 .RE
30276 .RS 4
30277 .Sp
30278 The \f(CWutf8_to_uv()\fR family of functions is preferred because they make it
30279 easier to write code safe from attacks. You should be converting to them; this
30280 will result in simpler, more robust code.
30281 .Sp
30282 .Vb 10
30283 \& bool utf8_to_uv ( const U8 * const s,
30284 \& const U8 * const e,
30285 \& UV *cp_p, Size_t *advance_p)
30286 \& bool Perl_utf8_to_uv ( const U8 * const s,
30287 \& const U8 * const e,
30288 \& UV *cp_p, Size_t *advance_p)
30289 \& bool extended_utf8_to_uv( const U8 * const s,
30290 \& const U8 * const e,
30291 \& UV *cp_p, Size_t *advance_p)
30292 \& bool Perl_extended_utf8_to_uv( const U8 * const s,
30293 \& const U8 * const e,
30294 \& UV *cp_p, Size_t *advance_p)
30295 \& bool strict_utf8_to_uv ( const U8 * const s,
30296 \& const U8 * const e,
30297 \& UV *cp_p, Size_t *advance_p)
30298 \& bool Perl_strict_utf8_to_uv ( const U8 * const s,
30299 \& const U8 * const e,
30300 \& UV *cp_p, Size_t *advance_p)
30301 \& bool c9strict_utf8_to_uv( const U8 * const s,
30302 \& const U8 * const e,
30303 \& UV *cp_p, Size_t *advance_p)
30304 \& bool Perl_c9strict_utf8_to_uv( const U8 * const s,
30305 \& const U8 * const e,
30306 \& UV *cp_p, Size_t *advance_p)
30307 \& UV utf8_to_uv_or_die ( const U8 * const s,
30308 \& const U8 *e,
30309 \& Size_t *advance_p)
30310 \& UV Perl_utf8_to_uv_or_die ( const U8 * const s,
30311 \& const U8 *e,
30312 \& Size_t *advance_p)
30313 \& UV utf8_to_uvchr_buf ( const U8 *s, const U8 *send,
30314 \& STRLEN *retlen)
30315 \& UV Perl_utf8_to_uvchr_buf (pTHX_ const U8 *s, const U8 *send,
30316 \& STRLEN *retlen)
30317 \& UV utf8_to_uvchr ( const U8 *s, STRLEN *retlen)
30318 \& UV Perl_utf8_to_uvchr (pTHX_ const U8 *s, STRLEN *retlen)
30319 .Ve
30320 .RE
30321 .RS 4
30322 .RE
30323 .ie n .IP """utf8_to_uv_errors*""" 4
30324 .el .IP \f(CWutf8_to_uv_errors*\fR 4
30325 .IX Item "utf8_to_uv_errors*"
30326 Described under \f(CW"utf8_to_uv_msgs"\fR
30327 .ie n .IP """utf8_to_uv_flags""" 4
30328 .el .IP \f(CWutf8_to_uv_flags\fR 4
30329 .IX Item "utf8_to_uv_flags"
30330 .PD 0
30331 .ie n .IP """utf8n_to_uvchr""" 4
30332 .el .IP \f(CWutf8n_to_uvchr\fR 4
30333 .IX Xref "utf8_to_uv_flags utf8n_to_uvchr"
30334 .IX Item "utf8n_to_uvchr"
30335 .PD
30336 These functions are extensions of \f(CW"utf8_to_uv"\fR, where you need
30337 more control over what UTF\-8 sequences are acceptable. These functions are
30338 unlikely to be needed except for specialized purposes.
30339 .Sp
30340 \&\f(CW\*(C`utf8n_to_uvchr\*(C'\fR is more like an extension of \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR, but
30341 with fewer quirks, and a different method of specifying the bytes in \f(CW\*(C`s\*(C'\fR it is
30342 allowed to examine. It has a \f(CW\*(C`curlen\*(C'\fR parameter instead of an \f(CW\*(C`e\*(C'\fR parameter,
30343 so the furthest byte in \f(CW\*(C`s\*(C'\fR it can look at is \f(CW\*(C`s\ +\ curlen\ \-\ 1\*(C'\fR. Its
30344 return value is, like \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR, ambiguous with respect to the NUL
30345 and REPLACEMENT characters, but the value of \f(CW*retlen\fR can be relied on
30346 (except with the \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag described below) to know where the
30347 next possible character along \f(CW\*(C`s\*(C'\fR starts, removing that quirk. Hence, you
30348 always should use \f(CW*retlen\fR to determine where the next character in \f(CW\*(C`s\*(C'\fR
30349 starts.
30350 .Sp
30351 These functions have an additional parameter, \f(CW\*(C`flags\*(C'\fR, besides the ones in
30352 \&\f(CW\*(C`utf8_to_uv\*(C'\fR and \f(CW\*(C`utf8_to_uvchr_buf\*(C'\fR, which can be used to broaden or
30353 restrict what is acceptable UTF\-8. \f(CW\*(C`flags\*(C'\fR has the same meaning and behavior
30354 in both functions. When \f(CW\*(C`flags\*(C'\fR is 0, these functions accept any
30355 syntactically valid Perl\-extended\-UTF\-8 sequence that doesn\*(Aqt overflow the
30356 platform\*(Aqs word size.
30357 .Sp
30358 There are flags that apply to accepting particular sequences, and flags that
30359 apply to raising warnings about encountering sequences. Each type is
30360 independent of the other. You can reject and not warn; warn and still accept;
30361 or both reject and warn. Rejecting means that the sequence gets translated
30362 into the Unicode REPLACEMENT CHARACTER instead of what it was meant to
30363 represent.
30364 .Sp
30365 Unless otherwise stated below, warnings are subject to the \f(CW\*(C`utf8\*(C'\fR warnings
30366 category being on.
30367 .RS 4
30368 .ie n .IP """UTF8_CHECK_ONLY""" 4
30369 .el .IP \f(CWUTF8_CHECK_ONLY\fR 4
30370 .IX Item "UTF8_CHECK_ONLY"
30371 This suppresses any warnings. And it changes what is stored into
30372 \&\f(CW*retlen\fR with the \f(CW\*(C`uvchr\*(C'\fR family of functions (for the worse). It is not
30373 likely to be of use to you. You can use \f(CW\*(C`UTF8_ALLOW_ANY\*(C'\fR (described below) to
30374 also turn off warnings, and that flag doesn\*(Aqt adversely affect \f(CW*retlen\fR.
30375 .Sp
30376 This flag is ignored if \f(CW\*(C`UTF8_DIE_IF_MALFORMED\*(C'\fR is also set.
30377 .ie n .IP """UTF8_FORCE_WARN_IF_MALFORMED""" 4
30378 .el .IP \f(CWUTF8_FORCE_WARN_IF_MALFORMED\fR 4
30379 .IX Item "UTF8_FORCE_WARN_IF_MALFORMED"
30380 Normally, no warnings are generated if warnings are turned off lexically or
30381 globally, regardless of any flags to the contrary. But this flag effectively
30382 turns on warnings temporarily for the duration of this function\*(Aqs execution.
30383 .Sp
30384 Do not use it lightly.
30385 .Sp
30386 This flag is ignored if \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR is also set.
30387 .ie n .IP """UTF8_DISALLOW_SURROGATE""" 4
30388 .el .IP \f(CWUTF8_DISALLOW_SURROGATE\fR 4
30389 .IX Item "UTF8_DISALLOW_SURROGATE"
30390 .PD 0
30391 .ie n .IP """UTF8_WARN_SURROGATE""" 4
30392 .el .IP \f(CWUTF8_WARN_SURROGATE\fR 4
30393 .IX Item "UTF8_WARN_SURROGATE"
30394 .PD
30395 These reject and/or warn about UTF\-8 sequences that represent surrogate
30396 characters. The warning categories \f(CW\*(C`utf8\*(C'\fR and \f(CW\*(C`non_unicode\*(C'\fR control if
30397 warnings are actually raised.
30398 .ie n .IP """UTF8_DISALLOW_NONCHAR""" 4
30399 .el .IP \f(CWUTF8_DISALLOW_NONCHAR\fR 4
30400 .IX Item "UTF8_DISALLOW_NONCHAR"
30401 .PD 0
30402 .ie n .IP """UTF8_WARN_NONCHAR""" 4
30403 .el .IP \f(CWUTF8_WARN_NONCHAR\fR 4
30404 .IX Item "UTF8_WARN_NONCHAR"
30405 .PD
30406 These reject and/or warn about UTF\-8 sequences that represent non\-character
30407 code points. The warning categories \f(CW\*(C`utf8\*(C'\fR and \f(CW\*(C`nonchar\*(C'\fR control if warnings
30408 are actually raised.
30409 .ie n .IP """UTF8_DISALLOW_SUPER""" 4
30410 .el .IP \f(CWUTF8_DISALLOW_SUPER\fR 4
30411 .IX Item "UTF8_DISALLOW_SUPER"
30412 .PD 0
30413 .ie n .IP """UTF8_WARN_SUPER""" 4
30414 .el .IP \f(CWUTF8_WARN_SUPER\fR 4
30415 .IX Item "UTF8_WARN_SUPER"
30416 .PD
30417 These reject and/or warn about UTF\-8 sequences that represent code points
30418 above 0x10FFFF. The warning categories \f(CW\*(C`utf8\*(C'\fR and \f(CW\*(C`non_unicode\*(C'\fR control if
30419 warnings are actually raised.
30420 .ie n .IP """UTF8_DISALLOW_ILLEGAL_INTERCHANGE""" 4
30421 .el .IP \f(CWUTF8_DISALLOW_ILLEGAL_INTERCHANGE\fR 4
30422 .IX Item "UTF8_DISALLOW_ILLEGAL_INTERCHANGE"
30423 .PD 0
30424 .ie n .IP """UTF8_WARN_ILLEGAL_INTERCHANGE""" 4
30425 .el .IP \f(CWUTF8_WARN_ILLEGAL_INTERCHANGE\fR 4
30426 .IX Item "UTF8_WARN_ILLEGAL_INTERCHANGE"
30427 .PD
30428 These are the same as having selected all three of the corresponding SURROGATE,
30429 NONCHAR and SUPER flags listed above.
30430 .Sp
30431 All such code points are not considered to be safely freely exchangeable
30432 between processes.
30433 .ie n .IP """UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE""" 4
30434 .el .IP \f(CWUTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE\fR 4
30435 .IX Item "UTF8_DISALLOW_ILLEGAL_C9_INTERCHANGE"
30436 .PD 0
30437 .ie n .IP """UTF8_WARN_ILLEGAL_C9_INTERCHANGE""" 4
30438 .el .IP \f(CWUTF8_WARN_ILLEGAL_C9_INTERCHANGE\fR 4
30439 .IX Item "UTF8_WARN_ILLEGAL_C9_INTERCHANGE"
30440 .PD
30441 These are the same as having selected both the corresponding SURROGATE and
30442 SUPER flags listed above.
30443 .Sp
30444 Unicode issued Unicode Corrigendum
30445 #9 <https://www.unicode.org/versions/corrigendum9.html> to allow non\-character
30446 code points to be exchanged by processes aware of the possibility. (They are
30447 still discouraged, however.) For more discussion see
30448 "Noncharacter code points" in perlunicode.
30449 .ie n .IP """UTF8_DISALLOW_PERL_EXTENDED""" 4
30450 .el .IP \f(CWUTF8_DISALLOW_PERL_EXTENDED\fR 4
30451 .IX Item "UTF8_DISALLOW_PERL_EXTENDED"
30452 .PD 0
30453 .ie n .IP """UTF8_WARN_PERL_EXTENDED""" 4
30454 .el .IP \f(CWUTF8_WARN_PERL_EXTENDED\fR 4
30455 .IX Item "UTF8_WARN_PERL_EXTENDED"
30456 .PD
30457 These reject and/or warn on encountering sequences that require Perl\*(Aqs
30458 extension to UTF\-8 to represent them. These are all for code points above
30459 0x10FFFF, so these sequences are a subset of the ones controlled by SUPER or
30460 either of the illegal interchange sets of flags. The warning categories
30461 \&\f(CW\*(C`utf8\*(C'\fR, \f(CW\*(C`non_unicode\*(C'\fR, and \f(CW\*(C`portable\*(C'\fR control if warnings are actually
30462 raised.
30463 .Sp
30464 Perl predates Unicode, and earlier standards allowed for code points up through
30465 0x7FFF_FFFF (2**31 \- 1). Perl, of course, would like you to be able to
30466 represent in UTF\-8 any code point available on the platform. To do so, some
30467 extension must be used to express them. Perl uses a natural extension to UTF\-8
30468 to represent the ones up to 2**36\-1, and invented a further extension to
30469 represent even higher ones, so that any code point that fits in a 64\-bit word
30470 can be represented. We lump both of these extensions together and refer to
30471 them as Perl extended UTF\-8. There exist other extensions that people have
30472 invented, incompatible with Perl\*(Aqs.
30473 .Sp
30474 On EBCDIC platforms starting in Perl v5.24, the Perl extension for representing
30475 extremely high code points kicks in at 0x3FFF_FFFF (2**30 \-1), which is lower
30476 than on ASCII. Prior to that, code points 2**31 and higher were simply
30477 unrepresentable, and a different, incompatible method was used to represent
30478 code points between 2**30 and 2**31 \- 1.
30479 .Sp
30480 It is likely that programs written in something other than Perl would not be
30481 able to read files that contain these; nor would Perl understand files written
30482 by something that uses a different extension. Hence, you can specify that
30483 above\-Unicode code points are generally accepted and/or warned about, but still
30484 exclude the ones that require this extension to represent.
30485 .ie n .IP """UTF8_ALLOW_ANY"" and kin" 4
30486 .el .IP "\f(CWUTF8_ALLOW_ANY\fR and kin" 4
30487 .IX Item "UTF8_ALLOW_ANY and kin"
30488 Other flags can be passed to allow, in a limited way, syntactic malformations
30489 and/or overflowing the number of bits available in a UV on the platform.
30490 The functions will not treat the relevant malformations as errors, hence will
30491 not raise any warnings for them. \f(CW\*(C`utf8_to_uv_msgs\*(C'\fR will return \f(CW\*(C`true\*(C'\fR.
30492 .Sp
30493 \&\fBHowever, all such malformations translate to the REPLACEMENT CHARACTER\fR,
30494 regardless of any of the flags.
30495 .Sp
30496 The only such flag that you would ever have any reason to use is
30497 \&\f(CW\*(C`UTF8_ALLOW_ANY\*(C'\fR which applies to any of the syntactic malformations and
30498 overflow, except for empty input. The other flags are analogous to ones in
30499 the \f(CW\*(C`_GOT_\*(C'\fR bits list in \f(CW"utf8_to_uv_msgs"\fR.
30500 .ie n .IP """UTF8_DIE_IF_MALFORMED""" 4
30501 .el .IP \f(CWUTF8_DIE_IF_MALFORMED\fR 4
30502 .IX Item "UTF8_DIE_IF_MALFORMED"
30503 If the function would otherwise return \f(CW\*(C`false\*(C'\fR, it instead croaks. The
30504 \&\f(CW\*(C`UTF8_FORCE_WARN_IF_MALFORMED\*(C'\fR flag is effectively turned on so that the cause
30505 of the croak is displayed.
30506 .RE
30507 .RS 4
30508 .Sp
30509 .Vb 10
30510 \& bool utf8_to_uv_flags(const U8 * const s,
30511 \& const U8 * const e, UV *cp_p,
30512 \& Size_t *advance_p, U32 flags)
30513 \& bool Perl_utf8_to_uv_flags(const U8 * const s,
30514 \& const U8 * const e, UV *cp_p,
30515 \& Size_t *advance_p, U32 flags)
30516 \& UV utf8n_to_uvchr (const U8 *s, STRLEN curlen,
30517 \& STRLEN *retlen, const U32 flags)
30518 \& UV Perl_utf8n_to_uvchr (const U8 *s, STRLEN curlen,
30519 \& STRLEN *retlen, const U32 flags)
30520 .Ve
30521 .RE
30522 .RS 4
30523 .RE
30524 .ie n .IP """utf8_to_uv_msgs""" 4
30525 .el .IP \f(CWutf8_to_uv_msgs\fR 4
30526 .IX Item "utf8_to_uv_msgs"
30527 .PD 0
30528 .ie n .IP """utf8n_to_uvchr_msgs""" 4
30529 .el .IP \f(CWutf8n_to_uvchr_msgs\fR 4
30530 .IX Item "utf8n_to_uvchr_msgs"
30531 .ie n .IP """utf8_to_uv_errors""" 4
30532 .el .IP \f(CWutf8_to_uv_errors\fR 4
30533 .IX Item "utf8_to_uv_errors"
30534 .ie n .IP """utf8n_to_uvchr_error""" 4
30535 .el .IP \f(CWutf8n_to_uvchr_error\fR 4
30536 .IX Xref "utf8_to_uv_errors utf8_to_uv_msgs utf8n_to_uvchr_error utf8n_to_uvchr_msgs"
30537 .IX Item "utf8n_to_uvchr_error"
30538 .PD
30539 These functions are extensions of \f(CW"utf8_to_uv_flags"\fR and
30540 \&\f(CW"utf8n_to_uvchr"\fR. They are used for the highly specialized purpose of
30541 when the caller needs to know the exact malformations that were encountered
30542 and/or the diagnostics that would be raised.
30543 .Sp
30544 They each take one or two extra parameters, pointers to where to store this
30545 information. The functions with \f(CW\*(C`_msgs\*(C'\fR in their names return both types, so
30546 take two extra parameters; those with \f(CW\*(C`_error\*(C'\fR return just the malformations,
30547 so take just one extra parameter. When the extra parameters are both 0, the
30548 functions behave identically to the function they extend.
30549 .Sp
30550 When the \f(CW\*(C`errors\*(C'\fR parameter is not NULL, it should be the address of a U32
30551 variable, into which the functions store a bitmap, described just below, with a
30552 bit set for each malformation the function found; 0 if none. The \f(CW\*(C`ALLOW\*(C'\fR\-type
30553 flags are ignored when determining the content of this variable. That is, even
30554 if you "allow" a particular malformation, if it is encountered, the
30555 corresponding bit will be set to notify you that one was encountered.
30556 However, the bits for conditions that are accepted by default aren\*(Aqt set
30557 unless the flags passed to the function indicate that they should be
30558 rejected or warned about when encountering them. These are explicitly
30559 noted in the list below along with the controlling flags.
30560 .Sp
30561 The bits returned in \f(CW\*(C`errors\*(C'\fR and their meanings are:
30562 .RS 4
30563 .ie n .IP """UTF8_GOT_CONTINUATION""" 4
30564 .el .IP \f(CWUTF8_GOT_CONTINUATION\fR 4
30565 .IX Item "UTF8_GOT_CONTINUATION"
30566 The input sequence was malformed in that the first byte was a UTF\-8
30567 continuation byte.
30568 .ie n .IP """UTF8_GOT_EMPTY""" 4
30569 .el .IP \f(CWUTF8_GOT_EMPTY\fR 4
30570 .IX Item "UTF8_GOT_EMPTY"
30571 The input parameters indicated the length of \f(CW\*(C`s\*(C'\fR is 0. Technically, this a
30572 coding error, not a malformation; you should check before calling these
30573 functions if there is actually anything to convert. But perl needs to be able
30574 to recover from bad input, and this is how it does it.
30575 .ie n .IP """UTF8_GOT_LONG""" 4
30576 .el .IP \f(CWUTF8_GOT_LONG\fR 4
30577 .IX Item "UTF8_GOT_LONG"
30578 The input sequence was malformed in that there is some other sequence that
30579 evaluates to the same code point, but that sequence is shorter than this one.
30580 .Sp
30581 Until Unicode 3.1, it was legal for programs to accept this malformation, but
30582 it was discovered that this created security issues.
30583 .ie n .IP """UTF8_GOT_NONCHAR""" 4
30584 .el .IP \f(CWUTF8_GOT_NONCHAR\fR 4
30585 .IX Item "UTF8_GOT_NONCHAR"
30586 The code point represented by the input UTF\-8 sequence is for a Unicode
30587 non\-character code point.
30588 This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
30589 \&\f(CW\*(C`UTF8_DISALLOW_NONCHAR\*(C'\fR or the \f(CW\*(C`UTF8_WARN_NONCHAR\*(C'\fR flags.
30590 .ie n .IP """UTF8_GOT_NON_CONTINUATION""" 4
30591 .el .IP \f(CWUTF8_GOT_NON_CONTINUATION\fR 4
30592 .IX Item "UTF8_GOT_NON_CONTINUATION"
30593 The input sequence was malformed in that a non\-continuation\-type byte was found
30594 in a position where only a continuation\-type one should be. See also
30595 \&\f(CW"UTF8_GOT_SHORT"\fR.
30596 .ie n .IP """UTF8_GOT_OVERFLOW""" 4
30597 .el .IP \f(CWUTF8_GOT_OVERFLOW\fR 4
30598 .IX Item "UTF8_GOT_OVERFLOW"
30599 The input sequence was malformed in that it is for a code point that is not
30600 representable in the number of bits available in an IV on the current platform.
30601 .ie n .IP """UTF8_GOT_PERL_EXTENDED""" 4
30602 .el .IP \f(CWUTF8_GOT_PERL_EXTENDED\fR 4
30603 .IX Item "UTF8_GOT_PERL_EXTENDED"
30604 The input sequence is not standard UTF\-8, but a Perl extension. This bit is
30605 set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
30606 \&\f(CW\*(C`UTF8_DISALLOW_PERL_EXTENDED\*(C'\fR or the \f(CW\*(C`UTF8_WARN_PERL_EXTENDED\*(C'\fR flags.
30607 .ie n .IP """UTF8_GOT_SHORT""" 4
30608 .el .IP \f(CWUTF8_GOT_SHORT\fR 4
30609 .IX Item "UTF8_GOT_SHORT"
30610 The input sequence was malformed in that \f(CW\*(C`curlen\*(C'\fR is smaller than required for
30611 a complete sequence. In other words, the input is for a partial character
30612 sequence.
30613 .Sp
30614 \&\f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR and \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR both indicate a too short
30615 sequence. The difference is that \f(CW\*(C`UTF8_GOT_NON_CONTINUATION\*(C'\fR indicates always
30616 that there is an error, while \f(CW\*(C`UTF8_GOT_SHORT\*(C'\fR means that an incomplete
30617 sequence was looked at. If no other flags are present, it means that the
30618 sequence was valid as far as it went. Depending on the application, this could
30619 mean one of three things:
30620 .RS 4
30621 .IP \(bu 4
30622 The \f(CW\*(C`e\*(C'\fR or \f(CW\*(C`curlen\*(C'\fR parameters passed in were too small, and the function
30623 was prevented from examining all the necessary bytes.
30624 .IP \(bu 4
30625 The buffer being looked at is based on reading data, and the data received so
30626 far stopped in the middle of a character, so that the next read will
30627 read the remainder of this character. (It is up to the caller to deal with the
30628 split bytes somehow.)
30629 .IP \(bu 4
30630 This is a real error, and the partial sequence is all we\*(Aqre going to get.
30631 .RE
30632 .RS 4
30633 .RE
30634 .ie n .IP """UTF8_GOT_SUPER""" 4
30635 .el .IP \f(CWUTF8_GOT_SUPER\fR 4
30636 .IX Item "UTF8_GOT_SUPER"
30637 The input sequence was malformed in that it is for a non\-Unicode code point;
30638 that is, one above the legal Unicode maximum.
30639 This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
30640 \&\f(CW\*(C`UTF8_DISALLOW_SUPER\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SUPER\*(C'\fR flags.
30641 .ie n .IP """UTF8_GOT_SURROGATE""" 4
30642 .el .IP \f(CWUTF8_GOT_SURROGATE\fR 4
30643 .IX Item "UTF8_GOT_SURROGATE"
30644 The input sequence was malformed in that it is for a Unicode UTF\-16 surrogate
30645 code point.
30646 This bit is set only if the input \f(CW\*(C`flags\*(C'\fR parameter contains either the
30647 \&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR or the \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR flags.
30648 .RE
30649 .RS 4
30650 .Sp
30651 Note that more than one bit may have been set by these functions. This is
30652 because it is possible for multiple malformations to be present in the same
30653 sequence. An example would be an overlong sequence evaluating to a surrogate
30654 when surrogates are forbidden. Another example is overflow; standard UTF\-8
30655 never overflows, so something that does must have been expressed using Perl\*(Aqs
30656 extended UTF\-8. It also is above all legal Unicode code points. So there will
30657 be a bit set for up to all three of these things. 1) Overflow always; 2)
30658 perl\-extended if the calling flags indicate those should be rejected or warned
30659 about; and 3) above\-Unicode, provided the calling flags indicate those should
30660 be rejected or warned about.
30661 .Sp
30662 If you don\*(Aqt care about the system\*(Aqs messages text nor warning categories, you
30663 can customize error handling by calling one of the \f(CW\*(C`_error\*(C'\fR functions, using
30664 either of the flags \f(CW\*(C`UTF8_ALLOW_ANY\*(C'\fR or \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR to suppress any
30665 warnings, and then examine the \f(CW*errors\fR return. If you don\*(Aqt use those
30666 flags, warnings will be raised as usual.
30667 .Sp
30668 But if you do care, instead use one of the functions with \f(CW\*(C`_msgs\*(C'\fR in their
30669 names. These allow you to completely customize error handling by suppressing
30670 any warnings that would otherwise be raised; instead returning all relevant
30671 information in a structure specified by an extra parameter, \f(CW\*(C`msgs\*(C'\fR, a pointer
30672 to a variable which has been declared to be an \f(CW\*(C`AV*\*(C'\fR, and into which the
30673 function creates a new AV to store information, described below, about all the
30674 malformations that were encountered.
30675 .Sp
30676 When this parameter is non\-NULL, the \f(CW\*(C`UTF8_DIE_IF_MALFORMED\*(C'\fR and
30677 \&\f(CW\*(C`UTF8_FORCE_WARN_IF_MALFORMED\*(C'\fR flags are asserted against in DEBUGGING builds,
30678 and are ignored in non\-DEBUGGING ones. The \f(CW\*(C`UTF8_CHECK_ONLY\*(C'\fR flag is always
30679 ignored.
30680 .Sp
30681 What is considered a malformation is affected by \f(CW\*(C`flags\*(C'\fR, the same as
30682 described in \f(CW"utf8_to_uv_flags"\fR. No array element is generated for
30683 malformations that are "allowed" by the input flags, in contrast to the
30684 bitmap returned in a non\-NULL \f(CW*errors\fR.
30685 .Sp
30686 Each element of the \f(CW\*(C`msgs\*(C'\fR AV array is an anonymous hash with the following
30687 three key\-value pairs:
30688 .ie n .IP """text""" 4
30689 .el .IP \f(CWtext\fR 4
30690 .IX Item "text"
30691 A \f(CW\*(C`SVpv\*(C'\fR containing the text of the message about the problematic input.
30692 This text is identical to any warning that otherwise would have been raised if
30693 the appropriate warning categories were enabled.
30694 .ie n .IP """warn_categories""" 4
30695 .el .IP \f(CWwarn_categories\fR 4
30696 .IX Item "warn_categories"
30697 This is 0 if the \f(CW\*(C`flags\*(C'\fR parameter to the function would ordinarily not have
30698 caused the message to be output as a warning; otherwise it is the warning
30699 category (or categories) that would have been used to generate a warning for
30700 \&\f(CW\*(C`text\*(C'\fR, packed into a \f(CW\*(C`SVuv\*(C'\fR. For example, if \f(CW\*(C`flags\*(C'\fR contains
30701 \&\f(CW\*(C`UTF8_DISALLOW_SURROGATE\*(C'\fR, but not \f(CW\*(C`UTF8_WARN_SURROGATE\*(C'\fR, this would be 0 if
30702 the input was a surrogate.
30703 .ie n .IP """flag""" 4
30704 .el .IP \f(CWflag\fR 4
30705 .IX Item "flag"
30706 A \f(CW\*(C`SVuv\*(C'\fR containing a single flag bit associated with this message. The bit
30707 corresponds to some bit in the \f(CW*errors\fR return value, such as
30708 \&\f(CW\*(C`UTF8_GOT_LONG\*(C'\fR.
30709 .RE
30710 .RS 4
30711 .Sp
30712 The array is sorted so that element \f(CW\*(C`[0]\*(C'\fR contains the first message that
30713 would have otherwise been raised; \f(CW\*(C`[1]\*(C'\fR, the second; and so on.
30714 .Sp
30715 You thus can completely override the normal error handling; you can check the
30716 lexical warnings state (or not) when choosing what to do with the returned
30717 messages.
30718 .Sp
30719 The caller, of course, is responsible for freeing any returned AV.
30720 .Sp
30721 .Vb 10
30722 \& bool utf8_to_uv_msgs (const U8 * const s0, const U8 *e,
30723 \& UV *cp_p, Size_t *advance_p,
30724 \& U32 flags, U32 *errors,
30725 \& AV **msgs)
30726 \& bool Perl_utf8_to_uv_msgs (const U8 * const s0, const U8 *e,
30727 \& UV *cp_p, Size_t *advance_p,
30728 \& U32 flags, U32 *errors,
30729 \& AV **msgs)
30730 \& UV utf8n_to_uvchr_msgs (const U8 * const s0,
30731 \& STRLEN curlen, STRLEN *retlen,
30732 \& const U32 flags, U32 *errors,
30733 \& AV **msgs)
30734 \& UV Perl_utf8n_to_uvchr_msgs (const U8 * const s0,
30735 \& STRLEN curlen, STRLEN *retlen,
30736 \& const U32 flags, U32 *errors,
30737 \& AV **msgs)
30738 \& bool utf8_to_uv_errors (const U8 * const s,
30739 \& const U8 * const e, UV *cp_p,
30740 \& Size_t *advance_p, U32 flags,
30741 \& U32 *errors)
30742 \& bool Perl_utf8_to_uv_errors (const U8 * const s,
30743 \& const U8 * const e, UV *cp_p,
30744 \& Size_t *advance_p, U32 flags,
30745 \& U32 *errors)
30746 \& UV utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
30747 \& STRLEN *retlen, const U32 flags,
30748 \& U32 *errors)
30749 \& UV Perl_utf8n_to_uvchr_error(const U8 *s, STRLEN curlen,
30750 \& STRLEN *retlen, const U32 flags,
30751 \& U32 *errors)
30752 .Ve
30753 .RE
30754 .RS 4
30755 .RE
30756 .ie n .IP """utf8_to_uv_or_die*""" 4
30757 .el .IP \f(CWutf8_to_uv_or_die*\fR 4
30758 .IX Item "utf8_to_uv_or_die*"
30759 .PD 0
30760 .ie n .IP """utf8_to_uvchr*""" 4
30761 .el .IP \f(CWutf8_to_uvchr*\fR 4
30762 .IX Item "utf8_to_uvchr*"
30763 .ie n .IP """utf8_to_uvchr_buf*""" 4
30764 .el .IP \f(CWutf8_to_uvchr_buf*\fR 4
30765 .IX Item "utf8_to_uvchr_buf*"
30766 .PD
30767 Described under \f(CW"utf8_to_uv"\fR
30768 .ie n .IP """utf8n_to_uvchr*""" 4
30769 .el .IP \f(CWutf8n_to_uvchr*\fR 4
30770 .IX Item "utf8n_to_uvchr*"
30771 Described under \f(CW"utf8_to_uv_flags"\fR
30772 .ie n .IP """utf8ness_t""" 4
30773 .el .IP \f(CWutf8ness_t\fR 4
30774 .IX Xref "utf8ness_t"
30775 .IX Item "utf8ness_t"
30776 This typedef is used by several core functions that return PV strings, to
30777 indicate the UTF\-8ness of those strings.
30778 .Sp
30779 (If you write a new function, you probably should instead return the PV in an
30780 SV with the UTF\-8 flag of the SV properly set, rather than use this mechanism.)
30781 .Sp
30782 The possible values this can be are:
30783 .RS 4
30784 .ie n .IP """UTF8NESS_YES""" 4
30785 .el .IP \f(CWUTF8NESS_YES\fR 4
30786 .IX Item "UTF8NESS_YES"
30787 This means the string definitely should be treated as a sequence of
30788 UTF\-8\-encoded characters.
30789 .Sp
30790 Most code that needs to handle this typedef should be of the form:
30791 .Sp
30792 .Vb 3
30793 \& if (utf8ness_flag == UTF8NESS_YES) {
30794 \& treat as utf8; // like turning on an SV UTF\-8 flag
30795 \& }
30796 .Ve
30797 .ie n .IP """UTF8NESS_NO""" 4
30798 .el .IP \f(CWUTF8NESS_NO\fR 4
30799 .IX Item "UTF8NESS_NO"
30800 This means the string definitely should be treated as a sequence of bytes, not
30801 encoded as UTF\-8.
30802 .ie n .IP """UTF8NESS_IMMATERIAL""" 4
30803 .el .IP \f(CWUTF8NESS_IMMATERIAL\fR 4
30804 .IX Item "UTF8NESS_IMMATERIAL"
30805 This means it is equally valid to treat the string as bytes, or as UTF\-8
30806 characters; use whichever way you want. This happens when the string consists
30807 entirely of characters which have the same representation whether encoded in
30808 UTF\-8 or not.
30809 .ie n .IP """UTF8NESS_UNKNOWN""" 4
30810 .el .IP \f(CWUTF8NESS_UNKNOWN\fR 4
30811 .IX Item "UTF8NESS_UNKNOWN"
30812 This means it is unknown how the string should be treated. No core function
30813 will ever return this value to a non\-core caller. Instead, it is used by the
30814 caller to initialize a variable to a non\-legal value. A typical call will look like:
30815 .Sp
30816 .Vb 5
30817 \& utf8ness_t string_is_utf8 = UTF8NESS_UNKNOWN
30818 \& const char * string = foo(arg1, arg2, ..., &string_is_utf8);
30819 \& if (string_is_utf8 == UTF8NESS_YES) {
30820 \& do something for UTF\-8;
30821 \& }
30822 .Ve
30823 .RE
30824 .RS 4
30825 .Sp
30826 The following relationships hold between the enum values:
30827 .ie n .IP """0\ <=\ \fIenum\ value\fR\ <=\ UTF8NESS_IMMATERIAL""" 4
30828 .el .IP "\f(CW0\ <=\ \fR\f(CIenum\ value\fR\f(CW\ <=\ UTF8NESS_IMMATERIAL\fR" 4
30829 .IX Item "0 <= enum value <= UTF8NESS_IMMATERIAL"
30830 the string may be treated in code as non\-UTF8
30831 .ie n .IP """UTF8NESS_IMMATERIAL\ <=\ <\fIenum\ value\fR""" 4
30832 .el .IP "\f(CWUTF8NESS_IMMATERIAL\ <=\ <\fR\f(CIenum\ value\fR\f(CW\fR" 4
30833 .IX Item "UTF8NESS_IMMATERIAL <= <enum value"
30834 the string may be treated in code as encoded in UTF\-8
30835 .RE
30836 .RS 4
30837 .RE
30838 .ie n .IP """UTF8SKIP""" 4
30839 .el .IP \f(CWUTF8SKIP\fR 4
30840 .IX Item "UTF8SKIP"
30841 .PD 0
30842 .ie n .IP """UTF8_SKIP""" 4
30843 .el .IP \f(CWUTF8_SKIP\fR 4
30844 .IX Item "UTF8_SKIP"
30845 .ie n .IP """UTF8_CHK_SKIP""" 4
30846 .el .IP \f(CWUTF8_CHK_SKIP\fR 4
30847 .IX Item "UTF8_CHK_SKIP"
30848 .ie n .IP """UTF8_SAFE_SKIP""" 4
30849 .el .IP \f(CWUTF8_SAFE_SKIP\fR 4
30850 .IX Xref "UTF8_CHK_SKIP UTF8_SAFE_SKIP UTF8_SKIP UTF8SKIP"
30851 .IX Item "UTF8_SAFE_SKIP"
30852 .PD
30853 Each of these returns the number of bytes in the UTF\-8 encoded character
30854 whose first (perhaps only) byte is pointed to by \f(CW\*(C`s\*(C'\fR.
30855 .Sp
30856 \&\f(CW\*(C`UTF8SKIP\*(C'\fR and \f(CW\*(C`UTF8_SKIP\*(C'\fR are synonyms. Use them when there is no
30857 possibility that the character pointed to by \f(CW\*(C`s\*(C'\fR is malformed.
30858 .Sp
30859 If there is a possibility of malformed input, use instead:
30860 .RS 4
30861 .ie n .IP """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by ""s""" 4
30862 .el .IP "\f(CW""UTF8_SAFE_SKIP""\fR if you know the maximum ending pointer in the buffer pointed to by \f(CWs\fR" 4
30863 .IX Item """UTF8_SAFE_SKIP"" if you know the maximum ending pointer in the buffer pointed to by s"
30864 If the buffer has enough bytes to hold the character, it returns the
30865 same value as \f(CW\*(C`UTF8SKIP\*(C'\fR and \f(CW\*(C`UTF8_SKIP\*(C'\fR would. If the buffer has
30866 fewer bytes than can fit, it returns the number of bytes available in
30867 the buffer, which could be 0 if \f(CW\*(C`s\ >=\ e\*(C'\fR. On DEBUGGING builds,
30868 it asserts that \f(CW\*(C`s\ <=\ e\*(C'\fR.
30869 .ie n .IP """UTF8_CHK_SKIP"" if you don\*(Aqt know the maximum ending pointer" 4
30870 .el .IP "\f(CW""UTF8_CHK_SKIP""\fR if you don\*(Aqt know the maximum ending pointer" 4
30871 .IX Item """UTF8_CHK_SKIP"" if you don't know the maximum ending pointer"
30872 This version doesn\*(Aqt blindly assume that the input string pointed to by
30873 \&\f(CW\*(C`s\*(C'\fR is well\-formed, but verifies that there isn\*(Aqt a NUL terminating
30874 character before the expected end of the next character in \f(CW\*(C`s\*(C'\fR. The
30875 length \f(CW\*(C`UTF8_CHK_SKIP\*(C'\fR returns stops just before any such NUL.
30876 .Sp
30877 Perl tends to add NULs, as an insurance policy, after the end of strings in
30878 SV\*(Aqs, so it is likely that using this macro on an SV string will prevent
30879 inadvertent reading beyond the end of the input buffer, even if it is
30880 malformed UTF\-8.
30881 .Sp
30882 This macro is intended to be used by XS modules where the inputs could be
30883 malformed, and it isn\*(Aqt feasible to restructure to use the safer
30884 \&\f(CW"UTF8_SAFE_SKIP"\fR, for example when interfacing with a C library.
30885 .RE
30886 .RS 4
30887 .Sp
30888 .Vb 4
30889 \& STRLEN UTF8SKIP (const char* s)
30890 \& STRLEN UTF8_SKIP (const char* s)
30891 \& STRLEN UTF8_CHK_SKIP (const char* s)
30892 \& STRLEN UTF8_SAFE_SKIP(const char* s, const char* e)
30893 .Ve
30894 .RE
30895 .RS 4
30896 .RE
30897 .ie n .IP """uv_to_utf8""" 4
30898 .el .IP \f(CWuv_to_utf8\fR 4
30899 .IX Item "uv_to_utf8"
30900 .PD 0
30901 .ie n .IP """uv_to_utf8_flags""" 4
30902 .el .IP \f(CWuv_to_utf8_flags\fR 4
30903 .IX Item "uv_to_utf8_flags"
30904 .ie n .IP """uvchr_to_utf8""" 4
30905 .el .IP \f(CWuvchr_to_utf8\fR 4
30906 .IX Item "uvchr_to_utf8"
30907 .ie n .IP """uvchr_to_utf8_flags""" 4
30908 .el .IP \f(CWuvchr_to_utf8_flags\fR 4
30909 .IX Xref "uv_to_utf8 uv_to_utf8_flags uvchr_to_utf8 uvchr_to_utf8_flags"
30910 .IX Item "uvchr_to_utf8_flags"
30911 .PD
30912 These each add the UTF\-8 representation of the native code point \f(CW\*(C`uv\*(C'\fR to the
30913 end 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
30914 \&\f(CW\*(C`UTF8_MAXBYTES+1\*(C'\fR) free bytes available. The return value is the pointer to
30915 the byte after the end of the new character. In other words,
30916 .Sp
30917 .Vb 1
30918 \& d = uv_to_utf8(d, uv);
30919 .Ve
30920 .Sp
30921 This is the Unicode\-aware way of saying
30922 .Sp
30923 .Vb 1
30924 \& *(d++) = uv;
30925 .Ve
30926 .Sp
30927 (\f(CW\*(C`uvchr_to_utf8\*(C'\fR is a synonym for \f(CW\*(C`uv_to_utf8\*(C'\fR.)
30928 .Sp
30929 \&\f(CW\*(C`uv_to_utf8_flags\*(C'\fR is used to make some classes of code points problematic in
30930 some way. \f(CW\*(C`uv_to_utf8\*(C'\fR is effectively the same as calling \f(CW\*(C`uv_to_utf8_flags\*(C'\fR
30931 with \f(CW\*(C`flags\*(C'\fR set to 0, meaning no class of code point is considered
30932 problematic. That means any input code point from 0..\f(CW\*(C`IV_MAX\*(C'\fR is considered
30933 to be fine. \f(CW\*(C`IV_MAX\*(C'\fR is typically 0x7FFF_FFFF in a 32\-bit word.
30934 .Sp
30935 (\f(CW\*(C`uvchr_to_utf8_flags\*(C'\fR is a synonym for \f(CW\*(C`uv_to_utf8_flags\*(C'\fR).
30936 .Sp
30937 A code point can be problematic in one of two ways. Its use could just raise a
30938 warning, and/or it could be forbidden with the function failing, and returning
30939 NULL.
30940 .Sp
30941 The potential classes of problematic code points and the flags that make them
30942 so are:
30943 .Sp
30944 If \f(CW\*(C`uv\*(C'\fR is a Unicode surrogate code point and \f(CW\*(C`UNICODE_WARN_SURROGATE\*(C'\fR is set,
30945 the function will raise a warning, provided UTF8 warnings are enabled. If
30946 instead \f(CW\*(C`UNICODE_DISALLOW_SURROGATE\*(C'\fR is set, the function will fail and return
30947 NULL. If both flags are set, the function will both warn and return NULL.
30948 .Sp
30949 Similarly, the \f(CW\*(C`UNICODE_WARN_NONCHAR\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_NONCHAR\*(C'\fR flags
30950 affect how the function handles a Unicode non\-character.
30951 .Sp
30952 And likewise, the \f(CW\*(C`UNICODE_WARN_SUPER\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR flags
30953 affect the handling of code points that are above the Unicode maximum of
30954 0x10FFFF. Languages other than Perl may not be able to accept files that
30955 contain these.
30956 .Sp
30957 The flag \f(CW\*(C`UNICODE_WARN_ILLEGAL_INTERCHANGE\*(C'\fR selects all three of
30958 the above WARN flags; and \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR selects all
30959 three DISALLOW flags. \f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_INTERCHANGE\*(C'\fR restricts the
30960 allowed inputs to the strict UTF\-8 traditionally defined by Unicode.
30961 Similarly, \f(CW\*(C`UNICODE_WARN_ILLEGAL_C9_INTERCHANGE\*(C'\fR and
30962 \&\f(CW\*(C`UNICODE_DISALLOW_ILLEGAL_C9_INTERCHANGE\*(C'\fR are shortcuts to select the
30963 above\-Unicode and surrogate flags, but not the non\-character ones, as
30964 defined in
30965 Unicode Corrigendum #9 <https://www.unicode.org/versions/corrigendum9.html>.
30966 See "Noncharacter code points" in perlunicode.
30967 .Sp
30968 Extremely high code points were never specified in any standard, and require an
30969 extension to UTF\-8 to express, which Perl does. It is likely that programs
30970 written in something other than Perl would not be able to read files that
30971 contain these; nor would Perl understand files written by something that uses a
30972 different extension. For these reasons, there is a separate set of flags that
30973 can warn and/or disallow these extremely high code points, even if other
30974 above\-Unicode ones are accepted. They are the \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR
30975 and \f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR flags. For more information see
30976 \&\f(CW"UTF8_GOT_PERL_EXTENDED"\fR. Of course \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR will
30977 treat all above\-Unicode code points, including these, as malformations. (Note
30978 that the Unicode standard considers anything above 0x10FFFF to be illegal, but
30979 there are standards predating it that allow up to 0x7FFF_FFFF (2**31 \-1))
30980 .Sp
30981 A somewhat misleadingly named synonym for \f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR is
30982 retained for backward compatibility: \f(CW\*(C`UNICODE_WARN_ABOVE_31_BIT\*(C'\fR. Similarly,
30983 \&\f(CW\*(C`UNICODE_DISALLOW_ABOVE_31_BIT\*(C'\fR is usable instead of the more accurately named
30984 \&\f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR. The names are misleading because on EBCDIC
30985 platforms,these flags can apply to code points that actually do fit in 31 bits.
30986 The new names accurately describe the situation in all cases.
30987 .RS 4
30988 .Sp
30989 .Vb 6
30990 \& U8 * uv_to_utf8 ( U8 *d, UV uv)
30991 \& U8 * Perl_uv_to_utf8 (pTHX_ U8 *d, UV uv)
30992 \& U8 * uv_to_utf8_flags ( U8 *d, UV uv, UV flags)
30993 \& U8 * Perl_uv_to_utf8_flags (pTHX_ U8 *d, UV uv, UV flags)
30994 \& U8 * uvchr_to_utf8 ( U8 *d, UV uv)
30995 \& U8 * uvchr_to_utf8_flags( U8 *d, UV uv, UV flags)
30996 .Ve
30997 .RE
30998 .RS 4
30999 .RE
31000 .ie n .IP """uv_to_utf8_msgs""" 4
31001 .el .IP \f(CWuv_to_utf8_msgs\fR 4
31002 .IX Item "uv_to_utf8_msgs"
31003 .PD 0
31004 .ie n .IP """uvchr_to_utf8_flags_msgs""" 4
31005 .el .IP \f(CWuvchr_to_utf8_flags_msgs\fR 4
31006 .IX Xref "uv_to_utf8_msgs uvchr_to_utf8_flags_msgs"
31007 .IX Item "uvchr_to_utf8_flags_msgs"
31008 .PD
31009 These functions are identical. THEY SHOULD BE USED IN ONLY VERY SPECIALIZED
31010 CIRCUMSTANCES.
31011 .Sp
31012 Most code should use \f(CW\*(C`"uv_to_utf8_flags"()\*(C'\fR rather than call this directly.
31013 .Sp
31014 This function is for code that wants any warning and/or error messages to be
31015 returned to the caller rather than be displayed. Any message that would have
31016 been displayed if all lexical warnings are enabled will instead be returned.
31017 .Sp
31018 It is just like \f(CW"uvchr_to_utf8_flags"\fR but it takes an extra parameter
31019 placed after all the others, \f(CW\*(C`msgs\*(C'\fR. If this parameter is 0, this function
31020 behaves identically to \f(CW"uvchr_to_utf8_flags"\fR. Otherwise, \f(CW\*(C`msgs\*(C'\fR should
31021 be a pointer to an \f(CW\*(C`HV *\*(C'\fR variable, in which this function creates a new HV to
31022 contain any appropriate message. The hash has three key\-value pairs, as
31023 follows:
31024 .RS 4
31025 .ie n .IP """text""" 4
31026 .el .IP \f(CWtext\fR 4
31027 .IX Item "text"
31028 The text of the message as a \f(CW\*(C`SVpv\*(C'\fR.
31029 .ie n .IP """warn_categories""" 4
31030 .el .IP \f(CWwarn_categories\fR 4
31031 .IX Item "warn_categories"
31032 The warning category (or categories) packed into a \f(CW\*(C`SVuv\*(C'\fR.
31033 .ie n .IP """flag_bit""" 4
31034 .el .IP \f(CWflag_bit\fR 4
31035 .IX Item "flag_bit"
31036 A single flag bit associated with this message, in a \f(CW\*(C`SVuv\*(C'\fR.
31037 The bit corresponds to some bit in the \f(CW*errors\fR return value.
31038 The possibilities are:
31039 .RS 4
31040 .ie n .IP """UNICODE_GOT_SURROGATE""" 4
31041 .el .IP \f(CWUNICODE_GOT_SURROGATE\fR 4
31042 .IX Item "UNICODE_GOT_SURROGATE"
31043 .PD 0
31044 .ie n .IP """UNICODE_GOT_NONCHAR""" 4
31045 .el .IP \f(CWUNICODE_GOT_NONCHAR\fR 4
31046 .IX Item "UNICODE_GOT_NONCHAR"
31047 .ie n .IP """UNICODE_GOT_SUPER""" 4
31048 .el .IP \f(CWUNICODE_GOT_SUPER\fR 4
31049 .IX Item "UNICODE_GOT_SUPER"
31050 .ie n .IP """UNICODE_GOT_PERL_EXTENDED""" 4
31051 .el .IP \f(CWUNICODE_GOT_PERL_EXTENDED\fR 4
31052 .IX Item "UNICODE_GOT_PERL_EXTENDED"
31053 .PD
31054 .RE
31055 .RS 4
31056 .RE
31057 .RE
31058 .RS 4
31059 .Sp
31060 It\*(Aqs important to note that specifying this parameter as non\-null will cause
31061 any warning this function would otherwise generate to be suppressed, and
31062 instead be placed in \f(CW*msgs\fR. The caller can check the lexical warnings state
31063 (or not) when choosing what to do with the returned message.
31064 .Sp
31065 Only a single message is returned; if a code point requires Perl extended UTF\-8
31066 to represent, it is also above\-Unicode. If either the
31067 \&\f(CW\*(C`UNICODE_WARN_PERL_EXTENDED\*(C'\fR or \f(CW\*(C`UNICODE_DISALLOW_PERL_EXTENDED\*(C'\fR flags are
31068 set, the return is controlled by them; if neither is set, the return is
31069 controlled by the \f(CW\*(C`UNICODE_WARN_SUPER\*(C'\fR and \f(CW\*(C`UNICODE_DISALLOW_SUPER\*(C'\fR flags.
31070 .Sp
31071 The caller, of course, is responsible for freeing any returned HV.
31072 .Sp
31073 .Vb 6
31074 \& U8 * uv_to_utf8_msgs ( U8 *d, UV uv, UV flags,
31075 \& HV **msgs)
31076 \& U8 * Perl_uv_to_utf8_msgs (pTHX_ U8 *d, UV uv, UV flags,
31077 \& HV **msgs)
31078 \& U8 * uvchr_to_utf8_flags_msgs( U8 *d, UV uv, UV flags,
31079 \& HV **msgs)
31080 .Ve
31081 .RE
31082 .RS 4
31083 .RE
31084 .ie n .IP """UVCHR_IS_INVARIANT""" 4
31085 .el .IP \f(CWUVCHR_IS_INVARIANT\fR 4
31086 .IX Xref "UVCHR_IS_INVARIANT"
31087 .IX Item "UVCHR_IS_INVARIANT"
31088 Evaluates to 1 if the representation of code point \f(CW\*(C`cp\*(C'\fR is the same whether or
31089 not it is encoded in UTF\-8; otherwise evaluates to 0. UTF\-8 invariant
31090 characters can be copied as\-is when converting to/from UTF\-8, saving time.
31091 \&\f(CW\*(C`cp\*(C'\fR is Unicode if above 255; otherwise is platform\-native.
31092 .RS 4
31093 .Sp
31094 .Vb 1
31095 \& bool UVCHR_IS_INVARIANT(UV cp)
31096 .Ve
31097 .RE
31098 .RS 4
31099 .RE
31100 .ie n .IP """UVCHR_SKIP""" 4
31101 .el .IP \f(CWUVCHR_SKIP\fR 4
31102 .IX Xref "UVCHR_SKIP"
31103 .IX Item "UVCHR_SKIP"
31104 returns the number of bytes required to represent the code point \f(CW\*(C`cp\*(C'\fR when
31105 encoded as UTF\-8. \f(CW\*(C`cp\*(C'\fR is a native (ASCII or EBCDIC) code point if less than
31106 255; a Unicode code point otherwise.
31107 .RS 4
31108 .Sp
31109 .Vb 1
31110 \& STRLEN UVCHR_SKIP(UV cp)
31111 .Ve
31112 .RE
31113 .RS 4
31114 .RE
31115 .ie n .IP """uvchr_to_utf8*""" 4
31116 .el .IP \f(CWuvchr_to_utf8*\fR 4
31117 .IX Item "uvchr_to_utf8*"
31118 .PD 0
31119 .ie n .IP """uvchr_to_utf8_flags*""" 4
31120 .el .IP \f(CWuvchr_to_utf8_flags*\fR 4
31121 .IX Item "uvchr_to_utf8_flags*"
31122 .PD
31123 Described under \f(CW"uv_to_utf8"\fR
31124 .ie n .IP """uvchr_to_utf8_flags_msgs*""" 4
31125 .el .IP \f(CWuvchr_to_utf8_flags_msgs*\fR 4
31126 .IX Item "uvchr_to_utf8_flags_msgs*"
31127 Described under \f(CW"uv_to_utf8_msgs"\fR
31128 .SH "Utility Functions"
31129 .IX Header "Utility Functions"
31130 .ie n .IP """C_ARRAY_END""" 4
31131 .el .IP \f(CWC_ARRAY_END\fR 4
31132 .IX Xref "C_ARRAY_END"
31133 .IX Item "C_ARRAY_END"
31134 Returns a pointer to one element past the final element of the input C array.
31135 .RS 4
31136 .Sp
31137 .Vb 1
31138 \& void * C_ARRAY_END(void *a)
31139 .Ve
31140 .RE
31141 .RS 4
31142 .RE
31143 .ie n .IP """C_ARRAY_LENGTH""" 4
31144 .el .IP \f(CWC_ARRAY_LENGTH\fR 4
31145 .IX Xref "C_ARRAY_LENGTH"
31146 .IX Item "C_ARRAY_LENGTH"
31147 Returns the number of elements in the input C array (so you want your
31148 zero\-based indices to be less than but not equal to).
31149 .RS 4
31150 .Sp
31151 .Vb 1
31152 \& STRLEN C_ARRAY_LENGTH(void *a)
31153 .Ve
31154 .RE
31155 .RS 4
31156 .RE
31157 .ie n .IP """getcwd_sv""" 4
31158 .el .IP \f(CWgetcwd_sv\fR 4
31159 .IX Xref "getcwd_sv"
31160 .IX Item "getcwd_sv"
31161 Fill \f(CW\*(C`sv\*(C'\fR with current working directory
31162 .RS 4
31163 .Sp
31164 .Vb 2
31165 \& int getcwd_sv( SV *sv)
31166 \& int Perl_getcwd_sv(pTHX_ SV *sv)
31167 .Ve
31168 .RE
31169 .RS 4
31170 .RE
31171 .ie n .IP """IN_PERL_COMPILETIME""" 4
31172 .el .IP \f(CWIN_PERL_COMPILETIME\fR 4
31173 .IX Xref "IN_PERL_COMPILETIME"
31174 .IX Item "IN_PERL_COMPILETIME"
31175 Returns 1 if this macro is being called during the compilation phase of the
31176 program; otherwise 0;
31177 .RS 4
31178 .Sp
31179 .Vb 1
31180 \& bool IN_PERL_COMPILETIME
31181 .Ve
31182 .RE
31183 .RS 4
31184 .RE
31185 .ie n .IP """IN_PERL_RUNTIME""" 4
31186 .el .IP \f(CWIN_PERL_RUNTIME\fR 4
31187 .IX Xref "IN_PERL_RUNTIME"
31188 .IX Item "IN_PERL_RUNTIME"
31189 Returns 1 if this macro is being called during the execution phase of the
31190 program; otherwise 0;
31191 .RS 4
31192 .Sp
31193 .Vb 1
31194 \& bool IN_PERL_RUNTIME
31195 .Ve
31196 .RE
31197 .RS 4
31198 .RE
31199 .ie n .IP """IS_SAFE_SYSCALL""" 4
31200 .el .IP \f(CWIS_SAFE_SYSCALL\fR 4
31201 .IX Xref "IS_SAFE_SYSCALL"
31202 .IX Item "IS_SAFE_SYSCALL"
31203 Same as "is_safe_syscall".
31204 .RS 4
31205 .Sp
31206 .Vb 2
31207 \& bool IS_SAFE_SYSCALL(const char *pv, STRLEN len,
31208 \& const char *what, const char *op_name)
31209 .Ve
31210 .RE
31211 .RS 4
31212 .RE
31213 .ie n .IP """is_safe_syscall""" 4
31214 .el .IP \f(CWis_safe_syscall\fR 4
31215 .IX Xref "is_safe_syscall"
31216 .IX Item "is_safe_syscall"
31217 Test that the given \f(CW\*(C`pv\*(C'\fR (with length \f(CW\*(C`len\*(C'\fR) doesn\*(Aqt contain any internal
31218 \&\f(CW\*(C`NUL\*(C'\fR characters.
31219 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
31220 category, and return FALSE.
31221 .Sp
31222 Return TRUE if the name is safe.
31223 .Sp
31224 \&\f(CW\*(C`what\*(C'\fR and \f(CW\*(C`op_name\*(C'\fR are used in any warning.
31225 .Sp
31226 Used by the \f(CWIS_SAFE_SYSCALL()\fR macro.
31227 .RS 4
31228 .Sp
31229 .Vb 6
31230 \& bool is_safe_syscall( const char *pv, STRLEN len,
31231 \& const char *what,
31232 \& const char *op_name)
31233 \& bool Perl_is_safe_syscall(pTHX_ const char *pv, STRLEN len,
31234 \& const char *what,
31235 \& const char *op_name)
31236 .Ve
31237 .RE
31238 .RS 4
31239 .RE
31240 .ie n .IP """my_setenv""" 4
31241 .el .IP \f(CWmy_setenv\fR 4
31242 .IX Xref "my_setenv"
31243 .IX Item "my_setenv"
31244 A wrapper for the C library \fBsetenv\fR\|(3). Don\*(Aqt use the latter, as the perl
31245 version has desirable safeguards
31246 .RS 4
31247 .Sp
31248 .Vb 2
31249 \& void my_setenv( const char *nam, const char *val)
31250 \& void Perl_my_setenv(pTHX_ const char *nam, const char *val)
31251 .Ve
31252 .RE
31253 .RS 4
31254 .RE
31255 .ie n .IP """newPADxVOP""" 4
31256 .el .IP \f(CWnewPADxVOP\fR 4
31257 .IX Xref "newPADxVOP"
31258 .IX Item "newPADxVOP"
31259 Constructs, checks and returns an op containing a pad offset. \f(CW\*(C`type\*(C'\fR is
31260 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
31261 or \f(CW\*(C`OP_PADCV\*(C'\fR. The returned op will have the \f(CW\*(C`op_targ\*(C'\fR field set by
31262 the \f(CW\*(C`padix\*(C'\fR argument.
31263 .Sp
31264 This is convenient when constructing a large optree in nested function
31265 calls, as it avoids needing to store the pad op directly to set the
31266 \&\f(CW\*(C`op_targ\*(C'\fR field as a side\-effect. For example
31267 .Sp
31268 .Vb 2
31269 \& o = op_append_elem(OP_LINESEQ, o,
31270 \& newPADxVOP(OP_PADSV, 0, padix));
31271 .Ve
31272 .RS 4
31273 .Sp
31274 .Vb 2
31275 \& OP * newPADxVOP( I32 type, I32 flags, PADOFFSET padix)
31276 \& OP * Perl_newPADxVOP(pTHX_ I32 type, I32 flags, PADOFFSET padix)
31277 .Ve
31278 .RE
31279 .RS 4
31280 .RE
31281 .ie n .IP """phase_name""" 4
31282 .el .IP \f(CWphase_name\fR 4
31283 .IX Xref "phase_name"
31284 .IX Item "phase_name"
31285 Returns the given phase\*(Aqs name as a NUL\-terminated string.
31286 .Sp
31287 For example, to print a stack trace that includes the current
31288 interpreter phase you might do:
31289 .Sp
31290 .Vb 2
31291 \& const char* phase_name = phase_name(PL_phase);
31292 \& mess("This is weird. (Perl phase: %s)", phase_name);
31293 .Ve
31294 .RS 4
31295 .Sp
31296 .Vb 1
31297 \& const char * const phase_name(enum perl_phase)
31298 .Ve
31299 .RE
31300 .RS 4
31301 .RE
31302 .ie n .IP """PoisonFree""" 4
31303 .el .IP \f(CWPoisonFree\fR 4
31304 .IX Item "PoisonFree"
31305 .PD 0
31306 .ie n .IP """Poison""" 4
31307 .el .IP \f(CWPoison\fR 4
31308 .IX Xref "Poison PoisonFree"
31309 .IX Item "Poison"
31310 .PD
31311 These each call \f(CWPoisonWith(0xEF)\fR for catching access to freed memory.
31312 .RS 4
31313 .Sp
31314 .Vb 2
31315 \& void PoisonFree(void* dest, int nitems, type)
31316 \& void Poison (void* dest, int nitems, type)
31317 .Ve
31318 .RE
31319 .RS 4
31320 .RE
31321 .ie n .IP """PoisonNew""" 4
31322 .el .IP \f(CWPoisonNew\fR 4
31323 .IX Xref "PoisonNew"
31324 .IX Item "PoisonNew"
31325 \&\f(CWPoisonWith(0xAB)\fR for catching access to allocated but uninitialized memory.
31326 .RS 4
31327 .Sp
31328 .Vb 1
31329 \& void PoisonNew(void* dest, int nitems, type)
31330 .Ve
31331 .RE
31332 .RS 4
31333 .RE
31334 .ie n .IP """PoisonWith""" 4
31335 .el .IP \f(CWPoisonWith\fR 4
31336 .IX Xref "PoisonWith"
31337 .IX Item "PoisonWith"
31338 Fill up memory with a byte pattern (a byte repeated over and over
31339 again) that hopefully catches attempts to access uninitialized memory.
31340 .RS 4
31341 .Sp
31342 .Vb 1
31343 \& void PoisonWith(void* dest, int nitems, type, U8 byte)
31344 .Ve
31345 .RE
31346 .RS 4
31347 .RE
31348 .ie n .IP """StructCopy""" 4
31349 .el .IP \f(CWStructCopy\fR 4
31350 .IX Xref "StructCopy"
31351 .IX Item "StructCopy"
31352 This is an architecture\-independent macro that does a shallow copy of one
31353 structure to another.
31354 .RS 4
31355 .Sp
31356 .Vb 1
31357 \& void StructCopy(type *src, type *dest, type)
31358 .Ve
31359 .RE
31360 .RS 4
31361 .RE
31362 .ie n .IP """sv_destroyable""" 4
31363 .el .IP \f(CWsv_destroyable\fR 4
31364 .IX Xref "sv_destroyable"
31365 .IX Item "sv_destroyable"
31366 Dummy routine which reports that object can be destroyed when there is no
31367 sharing module present. It ignores its single SV argument, and returns
31368 \&\*(Aqtrue\*(Aq. Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it
31369 could potentially warn under some level of strict\-ness.
31370 .RS 4
31371 .Sp
31372 .Vb 2
31373 \& bool sv_destroyable( SV *sv)
31374 \& bool Perl_sv_destroyable(pTHX_ SV *sv)
31375 .Ve
31376 .RE
31377 .RS 4
31378 .RE
31379 .ie n .IP """sv_nosharing""" 4
31380 .el .IP \f(CWsv_nosharing\fR 4
31381 .IX Xref "sv_nosharing"
31382 .IX Item "sv_nosharing"
31383 Dummy routine which "shares" an SV when there is no sharing module present.
31384 Or "locks" it. Or "unlocks" it. In other
31385 words, ignores its single SV argument.
31386 Exists to avoid test for a \f(CW\*(C`NULL\*(C'\fR function pointer and because it could
31387 potentially warn under some level of strict\-ness.
31388 .RS 4
31389 .Sp
31390 .Vb 2
31391 \& void sv_nosharing( SV *sv)
31392 \& void Perl_sv_nosharing(pTHX_ SV *sv)
31393 .Ve
31394 .RE
31395 .RS 4
31396 .RE
31397 .SH Versioning
31398 .IX Header "Versioning"
31399 .ie n .IP """new_version""" 4
31400 .el .IP \f(CWnew_version\fR 4
31401 .IX Xref "new_version"
31402 .IX Item "new_version"
31403 Returns a new version object based on the passed in SV:
31404 .Sp
31405 .Vb 1
31406 \& SV *sv = new_version(SV *ver);
31407 .Ve
31408 .Sp
31409 Does not alter the passed in ver SV. See "upg_version" if you
31410 want to upgrade the SV.
31411 .RS 4
31412 .Sp
31413 .Vb 2
31414 \& SV * new_version( SV *ver)
31415 \& SV * Perl_new_version(pTHX_ SV *ver)
31416 .Ve
31417 .RE
31418 .RS 4
31419 .RE
31420 .ie n .IP """PERL_REVISION""" 4
31421 .el .IP \f(CWPERL_REVISION\fR 4
31422 .IX Xref "PERL_REVISION"
31423 .IX Item "PERL_REVISION"
31424 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_REVISION\*(C'\fR
31425 from a future release of Perl. Do not use it for
31426 new code; remove it from existing code.
31427 .Sp
31428 The major number component of the perl interpreter currently being compiled or
31429 executing. This has been \f(CW5\fR from 1993 into 2020.
31430 .Sp
31431 Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR.
31432 .ie n .IP """PERL_SUBVERSION""" 4
31433 .el .IP \f(CWPERL_SUBVERSION\fR 4
31434 .IX Xref "PERL_SUBVERSION"
31435 .IX Item "PERL_SUBVERSION"
31436 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_SUBVERSION\*(C'\fR
31437 from a future release of Perl. Do not use it for
31438 new code; remove it from existing code.
31439 .Sp
31440 The micro number component of the perl interpreter currently being compiled or
31441 executing. In stable releases this gives the dot release number for
31442 maintenance updates. In development releases this gives a tag for a snapshot
31443 of the status at various points in the development cycle.
31444 .Sp
31445 Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR.
31446 .ie n .IP """PERL_VERSION""" 4
31447 .el .IP \f(CWPERL_VERSION\fR 4
31448 .IX Xref "PERL_VERSION"
31449 .IX Item "PERL_VERSION"
31450 \&\f(CW\*(C`\fR\f(CBDEPRECATED!\fR\f(CW\*(C'\fR It is planned to remove \f(CW\*(C`PERL_VERSION\*(C'\fR
31451 from a future release of Perl. Do not use it for
31452 new code; remove it from existing code.
31453 .Sp
31454 The minor number component of the perl interpreter currently being compiled or
31455 executing. Between 1993 into 2020, this has ranged from 0 to 33.
31456 .Sp
31457 Instead use one of the version comparison macros. See \f(CW"PERL_VERSION_EQ"\fR.
31458 .ie n .IP """PERL_VERSION_EQ""" 4
31459 .el .IP \f(CWPERL_VERSION_EQ\fR 4
31460 .IX Item "PERL_VERSION_EQ"
31461 .PD 0
31462 .ie n .IP """PERL_VERSION_GE""" 4
31463 .el .IP \f(CWPERL_VERSION_GE\fR 4
31464 .IX Item "PERL_VERSION_GE"
31465 .ie n .IP """PERL_VERSION_GT""" 4
31466 .el .IP \f(CWPERL_VERSION_GT\fR 4
31467 .IX Item "PERL_VERSION_GT"
31468 .ie n .IP """PERL_VERSION_LE""" 4
31469 .el .IP \f(CWPERL_VERSION_LE\fR 4
31470 .IX Item "PERL_VERSION_LE"
31471 .ie n .IP """PERL_VERSION_LT""" 4
31472 .el .IP \f(CWPERL_VERSION_LT\fR 4
31473 .IX Item "PERL_VERSION_LT"
31474 .ie n .IP """PERL_VERSION_NE""" 4
31475 .el .IP \f(CWPERL_VERSION_NE\fR 4
31476 .IX Xref "PERL_VERSION_EQ PERL_VERSION_GE PERL_VERSION_GT PERL_VERSION_LE PERL_VERSION_LT PERL_VERSION_NE"
31477 .IX Item "PERL_VERSION_NE"
31478 .PD
31479 Returns whether or not the perl currently being compiled has the specified
31480 relationship to the perl given by the parameters. For example,
31481 .Sp
31482 .Vb 5
31483 \& #if PERL_VERSION_GT(5,24,2)
31484 \& code that will only be compiled on perls after v5.24.2
31485 \& #else
31486 \& fallback code
31487 \& #endif
31488 .Ve
31489 .Sp
31490 Note that this is usable in making compile\-time decisions
31491 .Sp
31492 You may use the special value \*(Aq*\*(Aq for the final number to mean ALL possible
31493 values for it. Thus,
31494 .Sp
31495 .Vb 1
31496 \& #if PERL_VERSION_EQ(5,31,\*(Aq*\*(Aq)
31497 .Ve
31498 .Sp
31499 means all perls in the 5.31 series. And
31500 .Sp
31501 .Vb 1
31502 \& #if PERL_VERSION_NE(5,24,\*(Aq*\*(Aq)
31503 .Ve
31504 .Sp
31505 means all perls EXCEPT 5.24 ones. And
31506 .Sp
31507 .Vb 1
31508 \& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq)
31509 .Ve
31510 .Sp
31511 is effectively
31512 .Sp
31513 .Vb 1
31514 \& #if PERL_VERSION_LT(5,10,0)
31515 .Ve
31516 .Sp
31517 This means you don\*(Aqt have to think so much when converting from the existing
31518 deprecated \f(CW\*(C`PERL_VERSION\*(C'\fR to using this macro:
31519 .Sp
31520 .Vb 1
31521 \& #if PERL_VERSION <= 9
31522 .Ve
31523 .Sp
31524 becomes
31525 .Sp
31526 .Vb 1
31527 \& #if PERL_VERSION_LE(5,9,\*(Aq*\*(Aq)
31528 .Ve
31529 .RS 4
31530 .Sp
31531 .Vb 12
31532 \& bool PERL_VERSION_EQ(const U8 major, const U8 minor,
31533 \& const U8 patch)
31534 \& bool PERL_VERSION_GE(const U8 major, const U8 minor,
31535 \& const U8 patch)
31536 \& bool PERL_VERSION_GT(const U8 major, const U8 minor,
31537 \& const U8 patch)
31538 \& bool PERL_VERSION_LE(const U8 major, const U8 minor,
31539 \& const U8 patch)
31540 \& bool PERL_VERSION_LT(const U8 major, const U8 minor,
31541 \& const U8 patch)
31542 \& bool PERL_VERSION_NE(const U8 major, const U8 minor,
31543 \& const U8 patch)
31544 .Ve
31545 .RE
31546 .RS 4
31547 .RE
31548 .ie n .IP """prescan_version""" 4
31549 .el .IP \f(CWprescan_version\fR 4
31550 .IX Xref "prescan_version"
31551 .IX Item "prescan_version"
31552 Validate that a given string can be parsed as a version object, but doesn\*(Aqt
31553 actually perform the parsing. Can use either strict or lax validation rules.
31554 Can optionally set a number of hint variables to save the parsing code
31555 some time when tokenizing.
31556 .RS 4
31557 .Sp
31558 .Vb 10
31559 \& const char * prescan_version( const char *s,
31560 \& bool strict,
31561 \& const char **errstr,
31562 \& bool *sqv,
31563 \& int *ssaw_decimal,
31564 \& int *swidth,
31565 \& bool *salpha)
31566 \& const char * Perl_prescan_version(pTHX_ const char *s,
31567 \& bool strict,
31568 \& const char **errstr,
31569 \& bool *sqv,
31570 \& int *ssaw_decimal,
31571 \& int *swidth,
31572 \& bool *salpha)
31573 .Ve
31574 .RE
31575 .RS 4
31576 .RE
31577 .ie n .IP """scan_version""" 4
31578 .el .IP \f(CWscan_version\fR 4
31579 .IX Xref "scan_version"
31580 .IX Item "scan_version"
31581 Returns a pointer to the next character after the parsed
31582 version string, as well as upgrading the passed in SV to
31583 an RV.
31584 .Sp
31585 Function must be called with an already existing SV like
31586 .Sp
31587 .Vb 2
31588 \& sv = newSV(0);
31589 \& s = scan_version(s, SV *sv, bool qv);
31590 .Ve
31591 .Sp
31592 Performs some preprocessing to the string to ensure that
31593 it has the correct characteristics of a version. Flags the
31594 object if it contains an underscore (which denotes this
31595 is an alpha version). The boolean qv denotes that the version
31596 should be interpreted as if it had multiple decimals, even if
31597 it doesn\*(Aqt.
31598 .RS 4
31599 .Sp
31600 .Vb 4
31601 \& const char * scan_version( const char *s, SV *rv,
31602 \& bool qv)
31603 \& const char * Perl_scan_version(pTHX_ const char *s, SV *rv,
31604 \& bool qv)
31605 .Ve
31606 .RE
31607 .RS 4
31608 .RE
31609 .ie n .IP """upg_version""" 4
31610 .el .IP \f(CWupg_version\fR 4
31611 .IX Xref "upg_version"
31612 .IX Item "upg_version"
31613 In\-place upgrade of the supplied SV to a version object.
31614 .Sp
31615 .Vb 1
31616 \& SV *sv = upg_version(SV *sv, bool qv);
31617 .Ve
31618 .Sp
31619 Returns a pointer to the upgraded SV. Set the boolean qv if you want
31620 to force this SV to be interpreted as an "extended" version.
31621 .RS 4
31622 .Sp
31623 .Vb 2
31624 \& SV * upg_version( SV *ver, bool qv)
31625 \& SV * Perl_upg_version(pTHX_ SV *ver, bool qv)
31626 .Ve
31627 .RE
31628 .RS 4
31629 .RE
31630 .ie n .IP """vcmp""" 4
31631 .el .IP \f(CWvcmp\fR 4
31632 .IX Xref "vcmp"
31633 .IX Item "vcmp"
31634 Version object aware cmp. Both operands must already have been
31635 converted into version objects.
31636 .RS 4
31637 .Sp
31638 .Vb 2
31639 \& int vcmp( SV *lhv, SV *rhv)
31640 \& int Perl_vcmp(pTHX_ SV *lhv, SV *rhv)
31641 .Ve
31642 .RE
31643 .RS 4
31644 .RE
31645 .ie n .IP """vnormal""" 4
31646 .el .IP \f(CWvnormal\fR 4
31647 .IX Xref "vnormal"
31648 .IX Item "vnormal"
31649 Accepts a version object and returns the normalized string
31650 representation. Call like:
31651 .Sp
31652 .Vb 1
31653 \& sv = vnormal(rv);
31654 .Ve
31655 .Sp
31656 NOTE: you can pass either the object directly or the SV
31657 contained within the RV.
31658 .Sp
31659 The SV returned has a refcount of 1.
31660 .RS 4
31661 .Sp
31662 .Vb 2
31663 \& SV * vnormal( SV *vs)
31664 \& SV * Perl_vnormal(pTHX_ SV *vs)
31665 .Ve
31666 .RE
31667 .RS 4
31668 .RE
31669 .ie n .IP """vnumify""" 4
31670 .el .IP \f(CWvnumify\fR 4
31671 .IX Xref "vnumify"
31672 .IX Item "vnumify"
31673 Accepts a version object and returns the normalized floating
31674 point representation. Call like:
31675 .Sp
31676 .Vb 1
31677 \& sv = vnumify(rv);
31678 .Ve
31679 .Sp
31680 NOTE: you can pass either the object directly or the SV
31681 contained within the RV.
31682 .Sp
31683 The SV returned has a refcount of 1.
31684 .RS 4
31685 .Sp
31686 .Vb 2
31687 \& SV * vnumify( SV *vs)
31688 \& SV * Perl_vnumify(pTHX_ SV *vs)
31689 .Ve
31690 .RE
31691 .RS 4
31692 .RE
31693 .ie n .IP """vstringify""" 4
31694 .el .IP \f(CWvstringify\fR 4
31695 .IX Xref "vstringify"
31696 .IX Item "vstringify"
31697 In order to maintain maximum compatibility with earlier versions
31698 of Perl, this function will return either the floating point
31699 notation or the multiple dotted notation, depending on whether
31700 the original version contained 1 or more dots, respectively.
31701 .Sp
31702 The SV returned has a refcount of 1.
31703 .RS 4
31704 .Sp
31705 .Vb 2
31706 \& SV * vstringify( SV *vs)
31707 \& SV * Perl_vstringify(pTHX_ SV *vs)
31708 .Ve
31709 .RE
31710 .RS 4
31711 .RE
31712 .ie n .IP """vverify""" 4
31713 .el .IP \f(CWvverify\fR 4
31714 .IX Xref "vverify"
31715 .IX Item "vverify"
31716 Validates that the SV contains valid internal structure for a version object.
31717 It may be passed either the version object (RV) or the hash itself (HV). If
31718 the structure is valid, it returns the HV. If the structure is invalid,
31719 it returns NULL.
31720 .Sp
31721 .Vb 1
31722 \& SV *hv = vverify(sv);
31723 .Ve
31724 .Sp
31725 Note that it only confirms the bare minimum structure (so as not to get
31726 confused by derived classes which may contain additional hash entries):
31727 .RS 4
31728 .IP \(bu 4
31729 The SV is an HV or a reference to an HV
31730 .IP \(bu 4
31731 The hash contains a "version" key
31732 .IP \(bu 4
31733 The "version" key has a reference to an AV as its value
31734 .RE
31735 .RS 4
31736 .Sp
31737 .Vb 2
31738 \& SV * vverify( SV *vs)
31739 \& SV * Perl_vverify(pTHX_ SV *vs)
31740 .Ve
31741 .RE
31742 .RS 4
31743 .RE
31744 .SH "Warning and Dieing"
31745 .IX Xref "WARN_ALL WARN_AMBIGUOUS WARN_BAREWORD WARN_CLOSED WARN_CLOSURE WARN_DEBUGGING WARN_DEPRECATED WARN_DEPRECATED__DELIMITER_WILL_BE_PAIRED WARN_DEPRECATED__DOT_IN_INC WARN_DEPRECATED__GOTO_CONSTRUCT WARN_DEPRECATED__MISSING_IMPORT_CALLED_WITH_ARGS 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__KEYWORD_ALL WARN_EXPERIMENTAL__KEYWORD_ANY WARN_EXPERIMENTAL__PRIVATE_USE WARN_EXPERIMENTAL__RE_STRICT WARN_EXPERIMENTAL__REFALIASING WARN_EXPERIMENTAL__REGEX_SETS 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_NON_UNICODE WARN_NONCHAR 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"
31746 .IX Header "Warning and Dieing"
31747 In all these calls, the \f(CW\*(C`U32 w\fR\f(CIn\fR\f(CW\*(C'\fR parameters are warning category
31748 constants. You can see the ones currently available in
31749 "Category Hierarchy" in warnings, just capitalize all letters in the names
31750 and prefix them by \f(CW\*(C`WARN_\*(C'\fR. So, for example, the category \f(CW\*(C`void\*(C'\fR used in a
31751 perl program becomes \f(CW\*(C`WARN_VOID\*(C'\fR when used in XS code and passed to one of
31752 the calls below.
31753 .ie n .IP """ck_warner""" 4
31754 .el .IP \f(CWck_warner\fR 4
31755 .IX Item "ck_warner"
31756 .PD 0
31757 .ie n .IP """ck_warner_d""" 4
31758 .el .IP \f(CWck_warner_d\fR 4
31759 .IX Xref "ck_warner ck_warner_d"
31760 .IX Item "ck_warner_d"
31761 .PD
31762 If none of the warning categories given by \f(CW\*(C`err\*(C'\fR are enabled, do nothing;
31763 otherwise call \f(CW"warner"\fR or \f(CW"warner_nocontext"\fR with the passed\-in
31764 parameters;.
31765 .Sp
31766 \&\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,
31767 \&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
31768 categories.
31769 .Sp
31770 The two forms differ only in that \f(CW\*(C`ck_warner_d\*(C'\fR should be used if warnings for
31771 any of the categories are by default enabled.
31772 .RS 4
31773 .Sp
31774 .Vb 2
31775 \& void Perl_ck_warner (pTHX_ U32 err, const char *pat, ...)
31776 \& void Perl_ck_warner_d(pTHX_ U32 err, const char *pat, ...)
31777 .Ve
31778 .RE
31779 .RS 4
31780 .RE
31781 .ie n .IP """ckWARN""" 4
31782 .el .IP \f(CWckWARN\fR 4
31783 .IX Item "ckWARN"
31784 .PD 0
31785 .ie n .IP """ckWARN2""" 4
31786 .el .IP \f(CWckWARN2\fR 4
31787 .IX Item "ckWARN2"
31788 .ie n .IP """ckWARN3""" 4
31789 .el .IP \f(CWckWARN3\fR 4
31790 .IX Item "ckWARN3"
31791 .ie n .IP """ckWARN4""" 4
31792 .el .IP \f(CWckWARN4\fR 4
31793 .IX Xref "ckWARN ckWARN2 ckWARN3 ckWARN4"
31794 .IX Item "ckWARN4"
31795 .PD
31796 These return a boolean as to whether or not warnings are enabled for any of
31797 the warning category(ies) parameters: \f(CW\*(C`w\*(C'\fR, \f(CW\*(C`w1\*(C'\fR, ....
31798 .Sp
31799 Should any of the categories by default be enabled even if not within the
31800 scope of \f(CW\*(C`use\ warnings\*(C'\fR, instead use the \f(CW"ckWARN_d"\fR macros.
31801 .Sp
31802 The categories must be completely independent, one may not be subclassed from
31803 the other.
31804 .RS 4
31805 .Sp
31806 .Vb 4
31807 \& bool ckWARN (U32 w)
31808 \& bool ckWARN2(U32 w1, U32 w2)
31809 \& bool ckWARN3(U32 w1, U32 w2, U32 w3)
31810 \& bool ckWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
31811 .Ve
31812 .RE
31813 .RS 4
31814 .RE
31815 .ie n .IP """ckWARN_d""" 4
31816 .el .IP \f(CWckWARN_d\fR 4
31817 .IX Item "ckWARN_d"
31818 .PD 0
31819 .ie n .IP """ckWARN2_d""" 4
31820 .el .IP \f(CWckWARN2_d\fR 4
31821 .IX Item "ckWARN2_d"
31822 .ie n .IP """ckWARN3_d""" 4
31823 .el .IP \f(CWckWARN3_d\fR 4
31824 .IX Item "ckWARN3_d"
31825 .ie n .IP """ckWARN4_d""" 4
31826 .el .IP \f(CWckWARN4_d\fR 4
31827 .IX Xref "ckWARN_d ckWARN2_d ckWARN3_d ckWARN4_d"
31828 .IX Item "ckWARN4_d"
31829 .PD
31830 Like \f(CW"ckWARN"\fR, but for use if and only if the warning category(ies) is by
31831 default enabled even if not within the scope of \f(CW\*(C`use\ warnings\*(C'\fR.
31832 .RS 4
31833 .Sp
31834 .Vb 4
31835 \& bool ckWARN_d (U32 w)
31836 \& bool ckWARN2_d(U32 w1, U32 w2)
31837 \& bool ckWARN3_d(U32 w1, U32 w2, U32 w3)
31838 \& bool ckWARN4_d(U32 w1, U32 w2, U32 w3, U32 w4)
31839 .Ve
31840 .RE
31841 .RS 4
31842 .RE
31843 .ie n .IP """ckWARN2*""" 4
31844 .el .IP \f(CWckWARN2*\fR 4
31845 .IX Item "ckWARN2*"
31846 .PD 0
31847 .ie n .IP """ckWARN3*""" 4
31848 .el .IP \f(CWckWARN3*\fR 4
31849 .IX Item "ckWARN3*"
31850 .ie n .IP """ckWARN4*""" 4
31851 .el .IP \f(CWckWARN4*\fR 4
31852 .IX Item "ckWARN4*"
31853 .PD
31854 Described under \f(CW"ckWARN"\fR
31855 .ie n .IP """CLEAR_ERRSV""" 4
31856 .el .IP \f(CWCLEAR_ERRSV\fR 4
31857 .IX Xref "CLEAR_ERRSV"
31858 .IX Item "CLEAR_ERRSV"
31859 Clear the contents of \f(CW$@\fR, setting it to the empty string.
31860 .Sp
31861 This replaces any read\-only SV with a fresh SV and removes any magic.
31862 .RS 4
31863 .Sp
31864 .Vb 1
31865 \& void CLEAR_ERRSV()
31866 .Ve
31867 .RE
31868 .RS 4
31869 .RE
31870 .ie n .IP """croak""" 4
31871 .el .IP \f(CWcroak\fR 4
31872 .IX Item "croak"
31873 .PD 0
31874 .ie n .IP """croak_nocontext""" 4
31875 .el .IP \f(CWcroak_nocontext\fR 4
31876 .IX Xref "croak croak_nocontext"
31877 .IX Item "croak_nocontext"
31878 .PD
31879 These are XS interfaces to Perl\*(Aqs \f(CW\*(C`die\*(C'\fR function.
31880 .Sp
31881 They take a sprintf\-style format pattern and argument list, which are used to
31882 generate a string message. If the message does not end with a newline, then it
31883 will be extended with some indication of the current location in the code, as
31884 described for \f(CW"mess_sv"\fR.
31885 .Sp
31886 The error message will be used as an exception, by default
31887 returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
31888 modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, these croak
31889 functions never return normally.
31890 .Sp
31891 For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR
31892 (\f(CW$@\fR) will be used as an error message or object instead of building an
31893 error message from arguments. If you want to throw a non\-string object,
31894 or build an error message in an SV yourself, it is preferable to use
31895 the \f(CW"croak_sv"\fR function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR.
31896 .Sp
31897 The two forms differ only in that \f(CW\*(C`croak_nocontext\*(C'\fR does not take a thread
31898 context (\f(CW\*(C`aTHX\*(C'\fR) parameter. It is usually preferred as it takes up fewer
31899 bytes of code than plain \f(CW\*(C`Perl_croak\*(C'\fR, and time is rarely a critical resource
31900 when you are about to throw an exception.
31901 .RS 4
31902 .Sp
31903 .Vb 3
31904 \& void Perl_croak (pTHX_ const char *pat, ...)
31905 \& void croak_nocontext( const char *pat, ...)
31906 \& void Perl_croak_nocontext( const char *pat, ...)
31907 .Ve
31908 .RE
31909 .RS 4
31910 .RE
31911 .ie n .IP """croak_no_modify""" 4
31912 .el .IP \f(CWcroak_no_modify\fR 4
31913 .IX Xref "croak_no_modify"
31914 .IX Item "croak_no_modify"
31915 This encapsulates a common reason for dying, generating terser object code than
31916 using the generic \f(CW\*(C`Perl_croak\*(C'\fR. It is exactly equivalent to
31917 \&\f(CW\*(C`croak("%s", PL_no_modify)\*(C'\fR (which expands to something like
31918 "Modification of a read\-only value attempted").
31919 .Sp
31920 Less code used on exception code paths reduces CPU cache pressure.
31921 .RS 4
31922 .Sp
31923 .Vb 2
31924 \& void croak_no_modify()
31925 \& void Perl_croak_no_modify()
31926 .Ve
31927 .RE
31928 .RS 4
31929 .RE
31930 .ie n .IP """croak_nocontext*""" 4
31931 .el .IP \f(CWcroak_nocontext*\fR 4
31932 .IX Item "croak_nocontext*"
31933 Described under \f(CW"croak"\fR
31934 .ie n .IP """croak_sv""" 4
31935 .el .IP \f(CWcroak_sv\fR 4
31936 .IX Xref "croak_sv"
31937 .IX Item "croak_sv"
31938 This is an XS interface to Perl\*(Aqs \f(CW\*(C`die\*(C'\fR function.
31939 .Sp
31940 \&\f(CW\*(C`baseex\*(C'\fR is the error message or object. If it is a reference, it
31941 will be used as\-is. Otherwise it is used as a string, and if it does
31942 not end with a newline then it will be extended with some indication of
31943 the current location in the code, as described for "mess_sv".
31944 .Sp
31945 The error message or object will be used as an exception, by default
31946 returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
31947 modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, the \f(CW\*(C`croak_sv\*(C'\fR
31948 function never returns normally.
31949 .Sp
31950 To die with a simple string message, the "croak" function may be
31951 more convenient.
31952 .RS 4
31953 .Sp
31954 .Vb 2
31955 \& void croak_sv( SV *baseex)
31956 \& void Perl_croak_sv(pTHX_ SV *baseex)
31957 .Ve
31958 .RE
31959 .RS 4
31960 .RE
31961 .ie n .IP """die""" 4
31962 .el .IP \f(CWdie\fR 4
31963 .IX Item "die"
31964 .PD 0
31965 .ie n .IP """die_nocontext""" 4
31966 .el .IP \f(CWdie_nocontext\fR 4
31967 .IX Xref "die die_nocontext"
31968 .IX Item "die_nocontext"
31969 .PD
31970 These behave the same as "croak", except for the return type.
31971 They should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required.
31972 They never actually return.
31973 .Sp
31974 The two forms differ only in that \f(CW\*(C`die_nocontext\*(C'\fR does not take a thread
31975 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn\*(Aqt
31976 already have the thread context.
31977 .RS 4
31978 .Sp
31979 .Vb 3
31980 \& OP * Perl_die (pTHX_ const char *pat, ...)
31981 \& OP * die_nocontext( const char *pat, ...)
31982 \& OP * Perl_die_nocontext( const char *pat, ...)
31983 .Ve
31984 .RE
31985 .RS 4
31986 .RE
31987 .ie n .IP """die_sv""" 4
31988 .el .IP \f(CWdie_sv\fR 4
31989 .IX Xref "die_sv"
31990 .IX Item "die_sv"
31991 This behaves the same as "croak_sv", except for the return type.
31992 It should be used only where the \f(CW\*(C`OP *\*(C'\fR return type is required.
31993 The function never actually returns.
31994 .RS 4
31995 .Sp
31996 .Vb 2
31997 \& OP * die_sv( SV *baseex)
31998 \& OP * Perl_die_sv(pTHX_ SV *baseex)
31999 .Ve
32000 .RE
32001 .RS 4
32002 .RE
32003 .ie n .IP """ERRSV""" 4
32004 .el .IP \f(CWERRSV\fR 4
32005 .IX Xref "ERRSV"
32006 .IX Item "ERRSV"
32007 Returns the SV for \f(CW$@\fR, creating it if needed.
32008 .RS 4
32009 .Sp
32010 .Vb 1
32011 \& SV * ERRSV
32012 .Ve
32013 .RE
32014 .RS 4
32015 .RE
32016 .ie n .IP """fatal_warner""" 4
32017 .el .IP \f(CWfatal_warner\fR 4
32018 .IX Xref "fatal_warner"
32019 .IX Item "fatal_warner"
32020 Like "warner" except that it acts as if fatal warnings are enabled
32021 for the warning.
32022 .Sp
32023 If called when there are pending compilation errors this function may
32024 return.
32025 .Sp
32026 This is currently used to generate "used only once" fatal warnings
32027 since the COP where the name being reported is no longer the current
32028 COP when the warning is generated and may be useful for similar cases.
32029 .Sp
32030 \&\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,
32031 \&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
32032 categories.
32033 .RS 4
32034 .Sp
32035 .Vb 1
32036 \& void Perl_fatal_warner(pTHX_ U32 err, const char *pat, ...)
32037 .Ve
32038 .RE
32039 .RS 4
32040 .RE
32041 .ie n .IP """packWARN""" 4
32042 .el .IP \f(CWpackWARN\fR 4
32043 .IX Item "packWARN"
32044 .PD 0
32045 .ie n .IP """packWARN2""" 4
32046 .el .IP \f(CWpackWARN2\fR 4
32047 .IX Item "packWARN2"
32048 .ie n .IP """packWARN3""" 4
32049 .el .IP \f(CWpackWARN3\fR 4
32050 .IX Item "packWARN3"
32051 .ie n .IP """packWARN4""" 4
32052 .el .IP \f(CWpackWARN4\fR 4
32053 .IX Xref "packWARN packWARN2 packWARN3 packWARN4"
32054 .IX Item "packWARN4"
32055 .PD
32056 These macros are used to pack warning categories into a single U32 to pass to
32057 macros and functions that take a warning category parameter. The number of
32058 categories to pack is given by the name, with a corresponding number of
32059 category parameters passed.
32060 .RS 4
32061 .Sp
32062 .Vb 4
32063 \& U32 packWARN (U32 w1)
32064 \& U32 packWARN2(U32 w1, U32 w2)
32065 \& U32 packWARN3(U32 w1, U32 w2, U32 w3)
32066 \& U32 packWARN4(U32 w1, U32 w2, U32 w3, U32 w4)
32067 .Ve
32068 .RE
32069 .RS 4
32070 .RE
32071 .ie n .IP """SANE_ERRSV""" 4
32072 .el .IP \f(CWSANE_ERRSV\fR 4
32073 .IX Xref "SANE_ERRSV"
32074 .IX Item "SANE_ERRSV"
32075 Clean up ERRSV so we can safely set it.
32076 .Sp
32077 This replaces any read\-only SV with a fresh writable copy and removes
32078 any magic.
32079 .RS 4
32080 .Sp
32081 .Vb 1
32082 \& void SANE_ERRSV()
32083 .Ve
32084 .RE
32085 .RS 4
32086 .RE
32087 .ie n .IP """sv_regex_global_pos_clear""" 4
32088 .el .IP \f(CWsv_regex_global_pos_clear\fR 4
32089 .IX Xref "sv_regex_global_pos_clear"
32090 .IX Item "sv_regex_global_pos_clear"
32091 Resets the value in the regexp global match position magic, if it exists, so
32092 that it does not take effect.
32093 .RS 4
32094 .Sp
32095 .Vb 2
32096 \& void sv_regex_global_pos_clear( SV *sv)
32097 \& void Perl_sv_regex_global_pos_clear(pTHX_ SV *sv)
32098 .Ve
32099 .RE
32100 .RS 4
32101 .RE
32102 .ie n .IP """sv_regex_global_pos_get""" 4
32103 .el .IP \f(CWsv_regex_global_pos_get\fR 4
32104 .IX Xref "sv_regex_global_pos_get"
32105 .IX Item "sv_regex_global_pos_get"
32106 If the given SV has regexp global match position magic, sets the STRLEN
32107 pointed to by \f(CW\*(C`posp\*(C'\fR to the current value of the position and returns true.
32108 If not, returns false.
32109 .Sp
32110 If flags is zero, the return value will count in units of characters. If
32111 the \f(CW\*(C`SV_POSBYTES\*(C'\fR flag is present, this will count instead in units of bytes,
32112 which may be different if the SV has the \f(CW\*(C`SvUTF8\*(C'\fR flag set.
32113 .RS 4
32114 .Sp
32115 .Vb 4
32116 \& bool sv_regex_global_pos_get( SV *sv, STRLEN *posp,
32117 \& U32 flags)
32118 \& bool Perl_sv_regex_global_pos_get(pTHX_ SV *sv, STRLEN *posp,
32119 \& U32 flags)
32120 .Ve
32121 .RE
32122 .RS 4
32123 .RE
32124 .ie n .IP """sv_regex_global_pos_set""" 4
32125 .el .IP \f(CWsv_regex_global_pos_set\fR 4
32126 .IX Xref "sv_regex_global_pos_set"
32127 .IX Item "sv_regex_global_pos_set"
32128 Sets the value in the regexp global match position magic, first adding it if
32129 necessary. If \f(CW\*(C`pos\*(C'\fR is given as a negative value, this will count backwards
32130 from the end of the string.
32131 .Sp
32132 If flags is zero, \f(CW\*(C`pos\*(C'\fR will count in units of characters. If the
32133 \&\f(CW\*(C`SV_POSBYTES\*(C'\fR flag is present, this will count instead in units of bytes,
32134 which may be different if the SV has the \f(CW\*(C`SvUTF8\*(C'\fR flag set. In that case, it
32135 will be the caller\*(Aqs responsibility to ensure that \f(CW\*(C`pos\*(C'\fR only lands on the
32136 boundary between characters, and not in the middle of a multi\-byte character.
32137 .RS 4
32138 .Sp
32139 .Vb 4
32140 \& void sv_regex_global_pos_set( SV *sv, STRLEN pos,
32141 \& U32 flags)
32142 \& void Perl_sv_regex_global_pos_set(pTHX_ SV *sv, STRLEN pos,
32143 \& U32 flags)
32144 .Ve
32145 .RE
32146 .RS 4
32147 .RE
32148 .ie n .IP """sv_vstring_get""" 4
32149 .el .IP \f(CWsv_vstring_get\fR 4
32150 .IX Xref "sv_vstring_get"
32151 .IX Item "sv_vstring_get"
32152 If the given SV has vstring magic, stores the length of it into the variable
32153 addressed by \f(CW\*(C`lenp\*(C'\fR, and returns the string pointer. If not, returns
32154 \&\f(CW\*(C`NULL\*(C'\fR.
32155 .Sp
32156 If a pointer is returned to the caller, it will point to memory owned by the
32157 SV itself. The caller is not responsible for freeing it after this call,
32158 though it will not remain valid for longer than the lifetime of the SV itself.
32159 The caller should take a copy of it if it needs to be accessed after this
32160 time.
32161 .RS 4
32162 .Sp
32163 .Vb 4
32164 \& const char * sv_vstring_get( SV * const sv,
32165 \& STRLEN *lenp)
32166 \& const char * Perl_sv_vstring_get(pTHX_ SV * const sv,
32167 \& STRLEN *lenp)
32168 .Ve
32169 .RE
32170 .RS 4
32171 .RE
32172 .ie n .IP """vcroak""" 4
32173 .el .IP \f(CWvcroak\fR 4
32174 .IX Xref "vcroak"
32175 .IX Item "vcroak"
32176 This is an XS interface to Perl\*(Aqs \f(CW\*(C`die\*(C'\fR function.
32177 .Sp
32178 \&\f(CW\*(C`pat\*(C'\fR and \f(CW\*(C`args\*(C'\fR are a sprintf\-style format pattern and encapsulated
32179 argument list. These are used to generate a string message. If the
32180 message does not end with a newline, then it will be extended with
32181 some indication of the current location in the code, as described for
32182 "mess_sv".
32183 .Sp
32184 The error message will be used as an exception, by default
32185 returning control to the nearest enclosing \f(CW\*(C`eval\*(C'\fR, but subject to
32186 modification by a \f(CW$SIG{_\|_DIE_\|_}\fR handler. In any case, the \f(CW\*(C`croak\*(C'\fR
32187 function never returns normally.
32188 .Sp
32189 For historical reasons, if \f(CW\*(C`pat\*(C'\fR is null then the contents of \f(CW\*(C`ERRSV\*(C'\fR
32190 (\f(CW$@\fR) will be used as an error message or object instead of building an
32191 error message from arguments. If you want to throw a non\-string object,
32192 or build an error message in an SV yourself, it is preferable to use
32193 the "croak_sv" function, which does not involve clobbering \f(CW\*(C`ERRSV\*(C'\fR.
32194 .RS 4
32195 .Sp
32196 .Vb 2
32197 \& void vcroak( const char *pat, va_list *args)
32198 \& void Perl_vcroak(pTHX_ const char *pat, va_list *args)
32199 .Ve
32200 .RE
32201 .RS 4
32202 .RE
32203 .ie n .IP """vfatal_warner""" 4
32204 .el .IP \f(CWvfatal_warner\fR 4
32205 .IX Xref "vfatal_warner"
32206 .IX Item "vfatal_warner"
32207 This is like \f(CW"fatal_warner"\fR but \f(CW\*(C`args\*(C'\fR are an encapsulated
32208 argument list.
32209 .RS 4
32210 .Sp
32211 .Vb 4
32212 \& void vfatal_warner( U32 err, const char *pat,
32213 \& va_list *args)
32214 \& void Perl_vfatal_warner(pTHX_ U32 err, const char *pat,
32215 \& va_list *args)
32216 .Ve
32217 .RE
32218 .RS 4
32219 .RE
32220 .ie n .IP """vwarn""" 4
32221 .el .IP \f(CWvwarn\fR 4
32222 .IX Xref "vwarn"
32223 .IX Item "vwarn"
32224 This is an XS interface to Perl\*(Aqs \f(CW\*(C`warn\*(C'\fR function.
32225 .Sp
32226 This is like \f(CW"warn"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated
32227 argument list.
32228 .Sp
32229 Unlike with "vcroak", \f(CW\*(C`pat\*(C'\fR is not permitted to be null.
32230 .RS 4
32231 .Sp
32232 .Vb 2
32233 \& void vwarn( const char *pat, va_list *args)
32234 \& void Perl_vwarn(pTHX_ const char *pat, va_list *args)
32235 .Ve
32236 .RE
32237 .RS 4
32238 .RE
32239 .ie n .IP """vwarner""" 4
32240 .el .IP \f(CWvwarner\fR 4
32241 .IX Xref "vwarner"
32242 .IX Item "vwarner"
32243 This is like \f(CW"warner"\fR, but \f(CW\*(C`args\*(C'\fR are an encapsulated argument list.
32244 .RS 4
32245 .Sp
32246 .Vb 2
32247 \& void vwarner( U32 err, const char *pat, va_list *args)
32248 \& void Perl_vwarner(pTHX_ U32 err, const char *pat, va_list *args)
32249 .Ve
32250 .RE
32251 .RS 4
32252 .RE
32253 .ie n .IP """warn""" 4
32254 .el .IP \f(CWwarn\fR 4
32255 .IX Item "warn"
32256 .PD 0
32257 .ie n .IP """warn_nocontext""" 4
32258 .el .IP \f(CWwarn_nocontext\fR 4
32259 .IX Xref "warn warn_nocontext"
32260 .IX Item "warn_nocontext"
32261 .PD
32262 These are XS interfaces to Perl\*(Aqs \f(CW\*(C`warn\*(C'\fR function.
32263 .Sp
32264 They take a sprintf\-style format pattern and argument list, which are used to
32265 generate a string message. If the message does not end with a newline, then it
32266 will be extended with some indication of the current location in the code, as
32267 described for \f(CW"mess_sv"\fR.
32268 .Sp
32269 The error message or object will by default be written to standard error,
32270 but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
32271 .Sp
32272 Unlike with \f(CW"croak"\fR, \f(CW\*(C`pat\*(C'\fR is not permitted to be null.
32273 .Sp
32274 The two forms differ only in that \f(CW\*(C`warn_nocontext\*(C'\fR does not take a thread
32275 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn\*(Aqt
32276 already have the thread context.
32277 .RS 4
32278 .Sp
32279 .Vb 3
32280 \& void Perl_warn (pTHX_ const char *pat, ...)
32281 \& void warn_nocontext( const char *pat, ...)
32282 \& void Perl_warn_nocontext( const char *pat, ...)
32283 .Ve
32284 .RE
32285 .RS 4
32286 .RE
32287 .ie n .IP """warn_sv""" 4
32288 .el .IP \f(CWwarn_sv\fR 4
32289 .IX Xref "warn_sv"
32290 .IX Item "warn_sv"
32291 This is an XS interface to Perl\*(Aqs \f(CW\*(C`warn\*(C'\fR function.
32292 .Sp
32293 \&\f(CW\*(C`baseex\*(C'\fR is the error message or object. If it is a reference, it
32294 will be used as\-is. Otherwise it is used as a string, and if it does
32295 not end with a newline then it will be extended with some indication of
32296 the current location in the code, as described for "mess_sv".
32297 .Sp
32298 The error message or object will by default be written to standard error,
32299 but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
32300 .Sp
32301 To warn with a simple string message, the "warn" function may be
32302 more convenient.
32303 .RS 4
32304 .Sp
32305 .Vb 2
32306 \& void warn_sv( SV *baseex)
32307 \& void Perl_warn_sv(pTHX_ SV *baseex)
32308 .Ve
32309 .RE
32310 .RS 4
32311 .RE
32312 .ie n .IP """warner""" 4
32313 .el .IP \f(CWwarner\fR 4
32314 .IX Item "warner"
32315 .PD 0
32316 .ie n .IP """warner_nocontext""" 4
32317 .el .IP \f(CWwarner_nocontext\fR 4
32318 .IX Xref "warner warner_nocontext"
32319 .IX Item "warner_nocontext"
32320 .PD
32321 These output a warning of the specified category (or categories) given by
32322 \&\f(CW\*(C`err\*(C'\fR, using the sprintf\-style format pattern \f(CW\*(C`pat\*(C'\fR, and argument list.
32323 .Sp
32324 \&\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,
32325 \&\f(CW\*(C`packWARN4\*(C'\fR macros populated with the appropriate number of warning
32326 categories. If any of the warning categories they specify is fatal, a fatal
32327 exception is thrown.
32328 .Sp
32329 In any event a message is generated by the pattern and arguments. If the
32330 message does not end with a newline, then it will be extended with some
32331 indication of the current location in the code, as described for "mess_sv".
32332 .Sp
32333 The error message or object will by default be written to standard error,
32334 but this is subject to modification by a \f(CW$SIG{_\|_WARN_\|_}\fR handler.
32335 .Sp
32336 \&\f(CW\*(C`pat\*(C'\fR is not permitted to be null.
32337 .Sp
32338 The two forms differ only in that \f(CW\*(C`warner_nocontext\*(C'\fR does not take a thread
32339 context (\f(CW\*(C`aTHX\*(C'\fR) parameter, so is used in situations where the caller doesn\*(Aqt
32340 already have the thread context.
32341 .Sp
32342 These functions differ from the similarly named \f(CW"warn"\fR functions, in that
32343 the latter are for XS code to unconditionally display a warning, whereas these
32344 are for code that may be compiling a perl program, and does extra checking to
32345 see if the warning should be fatal.
32346 .RS 4
32347 .Sp
32348 .Vb 3
32349 \& void Perl_warner (pTHX_ U32 err, const char *pat, ...)
32350 \& void warner_nocontext( U32 err, const char *pat, ...)
32351 \& void Perl_warner_nocontext( U32 err, const char *pat, ...)
32352 .Ve
32353 .RE
32354 .RS 4
32355 .RE
32356 .SH XS
32357 .IX Header "XS"
32358 \&\fIxsubpp\fR compiles XS code into C. See "xsubpp" in perlutil.
32359 .ie n .IP """aMY_CXT""" 4
32360 .el .IP \f(CWaMY_CXT\fR 4
32361 .IX Item "aMY_CXT"
32362 .PD 0
32363 .ie n .IP """aMY_CXT_""" 4
32364 .el .IP \f(CWaMY_CXT_\fR 4
32365 .IX Item "aMY_CXT_"
32366 .ie n .IP """_aMY_CXT""" 4
32367 .el .IP \f(CW_aMY_CXT\fR 4
32368 .IX Item "_aMY_CXT"
32369 .PD
32370 Described in perlxs.
32371 .ie n .IP """ax""" 4
32372 .el .IP \f(CWax\fR 4
32373 .IX Xref "ax"
32374 .IX Item "ax"
32375 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the stack base offset,
32376 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
32377 must be called prior to setup the \f(CW\*(C`MARK\*(C'\fR variable.
32378 .RS 4
32379 .Sp
32380 .Vb 1
32381 \& Stack_off_t ax
32382 .Ve
32383 .RE
32384 .RS 4
32385 .RE
32386 .ie n .IP """CLASS""" 4
32387 .el .IP \f(CWCLASS\fR 4
32388 .IX Xref "CLASS"
32389 .IX Item "CLASS"
32390 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the
32391 class name for a C++ XS constructor. This is always a \f(CW\*(C`char*\*(C'\fR. See
32392 \&\f(CW"THIS"\fR.
32393 .RS 4
32394 .Sp
32395 .Vb 1
32396 \& char* CLASS
32397 .Ve
32398 .RE
32399 .RS 4
32400 .RE
32401 .ie n .IP """dAX""" 4
32402 .el .IP \f(CWdAX\fR 4
32403 .IX Xref "dAX"
32404 .IX Item "dAX"
32405 Sets up the \f(CW\*(C`ax\*(C'\fR variable.
32406 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
32407 .RS 4
32408 .Sp
32409 .Vb 1
32410 \& dAX;
32411 .Ve
32412 .RE
32413 .RS 4
32414 .RE
32415 .ie n .IP """dAXMARK""" 4
32416 .el .IP \f(CWdAXMARK\fR 4
32417 .IX Xref "dAXMARK"
32418 .IX Item "dAXMARK"
32419 Sets up the \f(CW\*(C`ax\*(C'\fR variable and stack marker variable \f(CW\*(C`mark\*(C'\fR.
32420 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
32421 .RS 4
32422 .Sp
32423 .Vb 1
32424 \& dAXMARK;
32425 .Ve
32426 .RE
32427 .RS 4
32428 .RE
32429 .ie n .IP """dITEMS""" 4
32430 .el .IP \f(CWdITEMS\fR 4
32431 .IX Xref "dITEMS"
32432 .IX Item "dITEMS"
32433 Sets up the \f(CW\*(C`items\*(C'\fR variable.
32434 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR by calling \f(CW\*(C`dXSARGS\*(C'\fR.
32435 .RS 4
32436 .Sp
32437 .Vb 1
32438 \& dITEMS;
32439 .Ve
32440 .RE
32441 .RS 4
32442 .RE
32443 .ie n .IP """dMY_CXT""" 4
32444 .el .IP \f(CWdMY_CXT\fR 4
32445 .IX Item "dMY_CXT"
32446 Described in perlxs.
32447 .ie n .IP """dMY_CXT_SV""" 4
32448 .el .IP \f(CWdMY_CXT_SV\fR 4
32449 .IX Xref "dMY_CXT_SV"
32450 .IX Item "dMY_CXT_SV"
32451 Now a placeholder that declares nothing
32452 .RS 4
32453 .Sp
32454 .Vb 1
32455 \& dMY_CXT_SV;
32456 .Ve
32457 .RE
32458 .RS 4
32459 .RE
32460 .ie n .IP """dUNDERBAR""" 4
32461 .el .IP \f(CWdUNDERBAR\fR 4
32462 .IX Xref "dUNDERBAR"
32463 .IX Item "dUNDERBAR"
32464 Sets up any variable needed by the \f(CW\*(C`UNDERBAR\*(C'\fR macro. It used to define
32465 \&\f(CW\*(C`padoff_du\*(C'\fR, but it is currently a noop. However, it is strongly advised
32466 to still use it for ensuring past and future compatibility.
32467 .RS 4
32468 .Sp
32469 .Vb 1
32470 \& dUNDERBAR;
32471 .Ve
32472 .RE
32473 .RS 4
32474 .RE
32475 .ie n .IP """dXSARGS""" 4
32476 .el .IP \f(CWdXSARGS\fR 4
32477 .IX Xref "dXSARGS"
32478 .IX Item "dXSARGS"
32479 Sets up stack and mark pointers for an XSUB, calling \f(CW\*(C`dSP\*(C'\fR and \f(CW\*(C`dMARK\*(C'\fR.
32480 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.
32481 This is usually handled automatically by \f(CW\*(C`xsubpp\*(C'\fR.
32482 .RS 4
32483 .Sp
32484 .Vb 1
32485 \& dXSARGS;
32486 .Ve
32487 .RE
32488 .RS 4
32489 .RE
32490 .ie n .IP """dXSI32""" 4
32491 .el .IP \f(CWdXSI32\fR 4
32492 .IX Xref "dXSI32"
32493 .IX Item "dXSI32"
32494 Sets up the \f(CW\*(C`ix\*(C'\fR variable for an XSUB which has aliases. This is usually
32495 handled automatically by \f(CW\*(C`xsubpp\*(C'\fR.
32496 .RS 4
32497 .Sp
32498 .Vb 1
32499 \& dXSI32;
32500 .Ve
32501 .RE
32502 .RS 4
32503 .RE
32504 .ie n .IP """items""" 4
32505 .el .IP \f(CWitems\fR 4
32506 .IX Xref "items"
32507 .IX Item "items"
32508 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate the number of
32509 items on the stack. See "Variable\-length Parameter Lists" in perlxs.
32510 .RS 4
32511 .Sp
32512 .Vb 1
32513 \& Stack_off_t items
32514 .Ve
32515 .RE
32516 .RS 4
32517 .RE
32518 .ie n .IP """ix""" 4
32519 .el .IP \f(CWix\fR 4
32520 .IX Xref "ix"
32521 .IX Item "ix"
32522 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to indicate which of an
32523 XSUB\*(Aqs aliases was used to invoke it. See "The ALIAS: Keyword" in perlxs.
32524 .RS 4
32525 .Sp
32526 .Vb 1
32527 \& I32 ix
32528 .Ve
32529 .RE
32530 .RS 4
32531 .RE
32532 .ie n .IP """MY_CXT""" 4
32533 .el .IP \f(CWMY_CXT\fR 4
32534 .IX Item "MY_CXT"
32535 .PD 0
32536 .ie n .IP """MY_CXT_CLONE""" 4
32537 .el .IP \f(CWMY_CXT_CLONE\fR 4
32538 .IX Item "MY_CXT_CLONE"
32539 .ie n .IP """MY_CXT_INIT""" 4
32540 .el .IP \f(CWMY_CXT_INIT\fR 4
32541 .IX Item "MY_CXT_INIT"
32542 .ie n .IP """pMY_CXT""" 4
32543 .el .IP \f(CWpMY_CXT\fR 4
32544 .IX Item "pMY_CXT"
32545 .ie n .IP """pMY_CXT_""" 4
32546 .el .IP \f(CWpMY_CXT_\fR 4
32547 .IX Item "pMY_CXT_"
32548 .ie n .IP """_pMY_CXT""" 4
32549 .el .IP \f(CW_pMY_CXT\fR 4
32550 .IX Item "_pMY_CXT"
32551 .PD
32552 Described in perlxs.
32553 .ie n .IP """RETVAL""" 4
32554 .el .IP \f(CWRETVAL\fR 4
32555 .IX Xref "RETVAL"
32556 .IX Item "RETVAL"
32557 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to hold the return value for an
32558 XSUB. This is always the proper type for the XSUB. See
32559 "The RETVAL Variable" in perlxs.
32560 .RS 4
32561 .Sp
32562 .Vb 1
32563 \& type RETVAL
32564 .Ve
32565 .RE
32566 .RS 4
32567 .RE
32568 .ie n .IP """ST""" 4
32569 .el .IP \f(CWST\fR 4
32570 .IX Xref "ST"
32571 .IX Item "ST"
32572 Used to access elements on the XSUB\*(Aqs stack.
32573 .RS 4
32574 .Sp
32575 .Vb 1
32576 \& SV* ST(int ix)
32577 .Ve
32578 .RE
32579 .RS 4
32580 .RE
32581 .ie n .IP """START_MY_CXT""" 4
32582 .el .IP \f(CWSTART_MY_CXT\fR 4
32583 .IX Item "START_MY_CXT"
32584 Described in perlxs.
32585 .ie n .IP """THIS""" 4
32586 .el .IP \f(CWTHIS\fR 4
32587 .IX Xref "THIS"
32588 .IX Item "THIS"
32589 Variable which is setup by \f(CW\*(C`xsubpp\*(C'\fR to designate the object in a C++
32590 XSUB. This is always the proper type for the C++ object. See \f(CW"CLASS"\fR and
32591 "Using XS With C++" in perlxs.
32592 .RS 4
32593 .Sp
32594 .Vb 1
32595 \& type THIS
32596 .Ve
32597 .RE
32598 .RS 4
32599 .RE
32600 .ie n .IP """UNDERBAR""" 4
32601 .el .IP \f(CWUNDERBAR\fR 4
32602 .IX Xref "UNDERBAR"
32603 .IX Item "UNDERBAR"
32604 The SV* corresponding to the \f(CW$_\fR variable. Works even if there
32605 is a lexical \f(CW$_\fR in scope.
32606 .ie n .IP """XS""" 4
32607 .el .IP \f(CWXS\fR 4
32608 .IX Xref "XS"
32609 .IX Item "XS"
32610 Macro to declare an XSUB and its C parameter list. This is handled by
32611 \&\f(CW\*(C`xsubpp\*(C'\fR. It is the same as using the more explicit \f(CW\*(C`XS_EXTERNAL\*(C'\fR macro; the
32612 latter is preferred.
32613 .ie n .IP """XS_EXTERNAL""" 4
32614 .el .IP \f(CWXS_EXTERNAL\fR 4
32615 .IX Xref "XS_EXTERNAL"
32616 .IX Item "XS_EXTERNAL"
32617 Macro to declare an XSUB and its C parameter list explicitly exporting the symbols.
32618 .ie n .IP """XS_INTERNAL""" 4
32619 .el .IP \f(CWXS_INTERNAL\fR 4
32620 .IX Xref "XS_INTERNAL"
32621 .IX Item "XS_INTERNAL"
32622 Macro to declare an XSUB and its C parameter list without exporting the symbols.
32623 This is handled by \f(CW\*(C`xsubpp\*(C'\fR and generally preferable over exporting the XSUB
32624 symbols unnecessarily.
32625 .ie n .IP """XSPROTO""" 4
32626 .el .IP \f(CWXSPROTO\fR 4
32627 .IX Xref "XSPROTO"
32628 .IX Item "XSPROTO"
32629 Macro used by \f(CW"XS_INTERNAL"\fR and \f(CW"XS_EXTERNAL"\fR to declare a function
32630 prototype. You probably shouldn\*(Aqt be using this directly yourself.
32631 .SH "Undocumented elements"
32632 .IX Header "Undocumented elements"
32633 The following functions have been flagged as part of the public
32634 API, but are currently undocumented. Use them at your own risk,
32635 as the interfaces are subject to change. Functions that are not
32636 listed in this document are not intended for public use, and
32637 should NOT be used under any circumstances.
32638 .PP
32639 If you feel you need to use one of these functions, first send
32640 email to perl5\[email protected] <mailto:[email protected]>.
32641 It may be that there is a good reason for the function not being
32642 documented, and it should be removed from this list; or it may
32643 just be that no one has gotten around to documenting it. In the
32644 latter case, you will be asked to submit a patch to document the
32645 function. Once your patch is accepted, it will indicate that the
32646 interface is stable (unless it is explicitly marked otherwise) and
32647 usable by you.
32648 .PP
32649
32650 .IX Xref "clone_params_del clone_params_new do_open do_openn sv_dup sv_dup_inc"
32651 .PP
32652 .Vb 1
32653 \& clone_params_del clone_params_new do_open do_openn sv_dup sv_dup_inc
32654 .Ve
32655 .PP
32656 Next are the API\-flagged elements that are considered experimental. Using one
32657 of these is even more risky than plain undocumented ones. They are listed
32658 here because they should be listed somewhere (so their existence doesn\*(Aqt get
32659 lost) and this is the best place for them.
32660 .PP
32661
32662 .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"
32663 .PP
32664 .Vb 4
32665 \& apply_attrs_string hv_store_flags thread_locale_init
32666 \& gv_fetchmethod_pv_flags leave_adjust_stacks thread_locale_term
32667 \& gv_fetchmethod_pvn_flags newXS_flags
32668 \& gv_fetchmethod_sv_flags savetmps
32669 .Ve
32670 .PP
32671 Finally are deprecated undocumented API elements.
32672 Do not use any for new code; remove all occurrences of all of these from
32673 existing code.
32674 .PP
32675 There are currently no items of this type
32676 .SH AUTHORS
32677 .IX Header "AUTHORS"
32678 Until May 1997, this document was maintained by Jeff Okamoto
32679 <[email protected]>. It is now maintained as part of Perl itself.
32680 .PP
32681 With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
32682 Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
32683 Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
32684 Stephen McCamant, and Gurusamy Sarathy.
32685 .PP
32686 API Listing originally by Dean Roehrich <[email protected]>.
32687 .PP
32688 Updated to be autogenerated from comments in the source by Benjamin Stuhl.
32689 .SH "SEE ALSO"
32690 .IX Header "SEE ALSO"
32691 \&\fIconfig.h\fR, perlapio, perlcall, perlclib, perlembed, perlfilter, perlguts, perlhacktips, perlintern, perlinterp, perliol, perlmroapi, perlreapi, perlreguts, perlxs